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 UsageIf you wish to have create-single-spa globally available, run the following in a terminal
Then run the following:
Alternatively, you may use create-single-spa without global installation:
This will open up a CLI prompt asking you what kind of project you want to create or update.
#
CLI argumentsYou may pass arguments to create-single-spa like so:
Here are the available CLI options:
#
--dirYou may specify which directory create-single-spa runs in through either of the following ways:
#
--moduleTypeYou can specify which kind of microfrontend you are creating with the --moduleType
CLI argument:
#
--frameworkYou 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
.
#
--layoutWhen generating a root config, the --layout
CLI argument indicates that you want to use single-spa-layout in your root config.
#
Project typescreate-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 packagesWithin the create-single-spa repo, there are several NPM packages. The following sections document each package:
#
create-single-spaThe core CLI, which invokes generator-single-spa.
#
generator-single-spaA 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-spaA shareable, customizable webpack config that is used for utility modules and single-spa applications.
#
Installation#
Usage#
webpack-config-single-spa-reactA shareable, customizable webpack config that adds react-specific configuration to webpack-config-single-spa
.
#
Installation#
Usage#
webpack-config-single-spa-tsA 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#
Usage#
webpack-config-single-spa-react-tsA 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#
Usage#
single-spa-web-server-utilsThe single-spa-web-server-utils
package is a collection of functions that help when implementing a web server for an index.html file. This package can be used to inline import maps into an HTML, which helps with the performance of your application. Additionally, it can be used to modify a browser import map so that it's suitable for usage in NodeJS for dynamic module loading and server rendering (Dynamic Module Loading and Server Rendering)).
The web server utils poll the import map from a URL and generate a browserImportMap
and nodeImportMap
from the response.
#
Installation#
getImportMapsThe getImportMaps
function accepts an object parameter and returns a promise that resolves with an object with two import maps: browserImportMap
and nodeImportMap
.
#
Customizing WebpackThe create-single-spa CLI internally uses webpack-merge to merge together webpack configs. Additionally, the CLI generates a webpack.config.js
file in each project where you can customize the webpack config further via webpack-merge
.
#
Merging rulesWhen merging webpack rules, use webpack-merge's mergeWithRules
function to avoid duplicate rules.
#
Loaderswebpack-config-single-spa
and its variants often depend on webpack loaders. Because webpack loaders are loaded via file path, it's possible to accidentally have duplicate copies of the same loader, if the same loader is also installed in both webpack-config-single-spa and in your project. This can result in errors.
To avoid duplicate copies of loaders, first check whether it is already installed by wepback-config-single-spa before adding it to your own project (see package.json). If the loader is listed there, then do not install it into your project, too. If you already have the loader installed in your project, uninstall it.
When referencing a loader that is installed as a dependency of webpack-config-single-spa, use require.resolve to ensure the loader is imported from the correct path: