create-single-spa
Single-spa offers a CLI for those who prefer autogenerated and managed configurations for webpack, babel, jest, etc. You do not have to use the CLI in order to use single-spa.
The CLI is called create-single-spa
(Github link). It is primarily intended for the creation of new projects, but may also be useful for migrating existing projects (especially migrating CRA or frameworkless projects).
Installation and Usage
If you wish to have create-single-spa globally available, run the following in a terminal
npm install --global create-single-spa# oryarn global add create-single-spa
Then run the following:
create-single-spa
Alternatively, you may use create-single-spa without global installation:
npm init single-spa# ornpx create-single-spa# oryarn create single-spa
This will open up a CLI prompt asking you what kind of project you want to create or update.
CLI arguments
You may pass arguments to create-single-spa like so:
# Different ways of doing the same thingcreate-single-spa --framework reactnpm init single-spa --framework reactnpx create-single-spa --framework reactyarn create single-spa --framework react
Here are the available CLI options:
--dir
You may specify which directory create-single-spa runs in through either of the following ways:
# Two ways of doing the same thingcreate-single-spa my-dircreate-single-spa --dir my-dir
--moduleType
You can specify which kind of microfrontend you are creating with the --moduleType
CLI argument:
create-single-spa --moduleType root-configcreate-single-spa --moduleType app-parcelcreate-single-spa --moduleType util-module
--framework
You can specify which framework you're using with the --framework
CLI argument. Note that if you specify a framework that you may omit the --moduleType
, as it is inferred to be app-parcel
.
create-single-spa --framework reactcreate-single-spa --framework vuecreate-single-spa --framework angular
--layout
When generating a root config, the --layout
CLI argument indicates that you want to use single-spa-layout in your root config.
Project types
create-single-spa asks you if you'd like to create a single-spa application, a utility module, or a root-config. All three module types assume that you are using the recommended setup.
If you select that you'd like to create a single-spa application, you will be prompted for which framework you'd like to choose. React is implemented with premade configurations for babel + webpack + jest. Angular is implemented with Angular CLI and single-spa-angular. Vue is implemented with Vue CLI and vue-cli-plugin-single-spa.
NPM packages
Within the create-single-spa repo, there are several NPM packages. The following sections document each package:
create-single-spa
The core CLI, which invokes generator-single-spa.
generator-single-spa
A Yeoman generator that prompts the user and then creates files. This is primarily invoked via the create-single-spa CLI, but can also be composed if you'd like to customize it.
webpack-config-single-spa
A shareable, customizable webpack config that is used for utility modules and single-spa applications.
Installation
npm install --save-dev webpack-config-single-spa webpack-merge# oryarn add --dev webpack-config-single-spa webpack-merge
Usage
const webpackMerge = require('webpack-merge');const singleSpaDefaults = require('webpack-config-single-spa');module.exports = webpackConfigEnv => {const defaultConfig = singleSpaDefaults({// The name of the organization this application is written fororgName: 'name-of-company',// The name of the current project. This usually matches the git repo's nameprojectName: 'name-of-project',// See https://webpack.js.org/guides/environment-variables/#root for explanation of webpackConfigEnvwebpackConfigEnv,})return webpackMerge.smart(defaultConfig, {// modify the webpack config however you'd like to by adding to this object})}
webpack-config-single-spa-react
A shareable, customizable webpack config that adds react-specific configuration to webpack-config-single-spa
.
Installation
npm install --save-dev webpack-config-single-spa-react webpack-merge# oryarn add --dev webpack-config-single-spa-react webpack-merge
Usage
const webpackMerge = require('webpack-merge');const singleSpaDefaults = require('webpack-config-single-spa-react');module.exports = webpackConfigEnv => {const defaultConfig = singleSpaDefaults({// The name of the organization this application is written fororgName: 'name-of-company',// The name of the current project. This usually matches the git repo's nameprojectName: 'name-of-project',// See https://webpack.js.org/guides/environment-variables/#root for explanation of webpackConfigEnvwebpackConfigEnv,})return webpackMerge.smart(defaultConfig, {// modify the webpack config however you'd like to by adding to this object})}
webpack-config-single-spa-ts
A shareable, customizable webpack config that adds typescript-specific configuration to webpack-config-single-spa
. Note that webpack-config-single-spa-ts has a peerDependency on typescript
.
Installation
npm install --save-dev webpack-config-single-spa-ts webpack-merge# oryarn add --dev webpack-config-single-spa-ts webpack-merge
Usage
const webpackMerge = require('webpack-merge');const singleSpaDefaults = require('webpack-config-single-spa-ts');module.exports = webpackConfigEnv => {const defaultConfig = singleSpaDefaults({// The name of the organization this application is written fororgName: 'name-of-company',// The name of the current project. This usually matches the git repo's nameprojectName: 'name-of-project',// See https://webpack.js.org/guides/environment-variables/#root for explanation of webpackConfigEnvwebpackConfigEnv,})return webpackMerge.smart(defaultConfig, {// modify the webpack config however you'd like to by adding to this object})}
const singleSpaTs = require('webpack-config-single-spa-ts');// Alternatively, you may modify a webpack config directlyconst myOtherWebpackConfig = {/* ... */}const finalConfig = singleSpaDefaults.modifyConfig(myOtherWebpackConfig)
webpack-config-single-spa-react-ts
A shareable, customizable webpack config that creates a webpack config that works with both react and typescript. Note that webpack-config-single-spa-react-ts simply merges the config from webpack-config-single-spa-react with that of webpack-config-single-spa-ts.
Installation
npm install --save-dev webpack-config-single-spa-react-ts webpack-merge# oryarn add --dev webpack-config-single-spa-react-ts webpack-merge
Usage
const webpackMerge = require('webpack-merge');const singleSpaDefaults = require('webpack-config-single-spa-react-ts');module.exports = webpackConfigEnv => {const defaultConfig = singleSpaDefaults({// The name of the organization this application is written fororgName: 'name-of-company',// The name of the current project. This usually matches the git repo's nameprojectName: 'name-of-project',// See https://webpack.js.org/guides/environment-variables/#root for explanation of webpackConfigEnvwebpackConfigEnv,})return webpackMerge.smart(defaultConfig, {// modify the webpack config however you'd like to by adding to this object})}