Migrating from v1 to v2

[joeldenning]

Steps to upgrade

[email protected] release
Webpack 5 announcement post

1. Upgrade to webpack 5, webpack-dev-server 4, and webpack-cli 4

npm install --save-dev webpack@latest webpack-dev-server@next webpack-cli@latest

2. Find any dependencies in your package.json that start with webpack-config-single-spa or ts-config-single-spa. Upgrade them to the new version.

# DO NOT run all of these in your project. Only run the commands that apply to your project. 

npm install --save-dev webpack-config-single-spa@latest
npm install --save-dev webpack-config-single-spa-ts@latest
npm install --save-dev webpack-config-single-spa-react@latest
npm install --save-dev webpack-config-single-spa-react-ts@latest
npm install --save-dev ts-config-single-spa@latest

3. Upgrade all webpack loaders and webpack plugins that are dependencies in your package.json. Loaders are dependencies whose names often end with -loader. Plugins are dependencies whose names often include webpack-plugin.

4. Update your package.json scripts. All instances of webpack-dev-server should be replaced with webpack serve. All instances of --env.thing should be replaced with --env thing. You can remove the =true from any --env parts of webpack commands, as webpack 5 defaults it to true without the =true.

{
  "scripts": {
    "lint": "eslint src",
-   "start": "webpack-dev-server",
+   "start": "webpack serve",
    "test": "jest --passWithNoTests",
    "build": "webpack --mode=production",
-    "analyze": "webpack --mode=production --env.analyze=true",
+    "analyze": "webpack --mode=production --env analyze",
    "format": "prettier --write .",
    "watch-tests": "jest --watch",
    "coverage": "jest --coverage --passWithNoTests"
  }
}

5. Remove src/set-public-path.js from your repository, if you haven't already. Webpack public path is now set via webpack plugin, so the set-public-path.js file is unnecessary.

6. Remove systemjs-webpack-interop, css-loader, and style-loader, from your project, as they are now included in webpack-config-single-spa as a dependency.

npm uninstall systemjs-webpack-interop css-loader style-loader

7. Upgrade index.html scripts

In your root config, upgrade systemjs, single-spa, and import-map-overrides. Delete the named-exports.min.js file, as it's not needed in newer versions of systemjs.

<!-- Old -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/system.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/extras/named-exports.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/extras/amd.min.js"></script>

<!-- New -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/system.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/extras/amd.min.js"></script>

8. Test it out!

npm start
npm run build
npm run analyze

Optional steps

Upgrade webpack-merge

npm install --save-dev webpack-merge@latest

Then in your webpack config, change how you import webpack-merge:

// Old
const webpackMerge = require('webpack-merge');

// New
const { merge } = require('webpack-merge');

Then change how you call the webpack merge function:

// Old
webpackMerge.smart(...)

// New
merge(...)

If you're overriding webpack module.rules, consider using mergeWithRules to avoid duplicate rules. Example

See https://github.com/survivejs/webpack-merge and https://github.com/survivejs/webpack-merge/blob/develop/CHANGELOG.md#503--2020-07-06 for more info.

Upgrading root config

If you created your root config a long time ago, a lot has changed in both the create-single-spa v1 and v2 releases since then. Root configs now use webpack-config-single-spa.

npm install --save-dev webpack-config-single-spa@latest

Now update your webpack.config.js, to match this template. Here's an example.

style-loader and css-loader issues

If you run into issues with style-loader/css-loader, it may be caused by duplicate copies of the libraries - one in webpack-config-single-spa and one in your project. To solve, tell webpack to use the version in webpack-config-single-spa, by using require.resolve()

npm uninstall style-loader css-loader

// webpack.config.js
return merge(singleSpaDefaults, {
  module: {
    rules: [
    module: {
      rules: [
        {
          test: /\.css$/i,
          use: [
            require.resolve("style-loader", {
              paths: [require.resolve("webpack-config-single-spa")],
            }),
            require.resolve("css-loader", {
              paths: [require.resolve("webpack-config-single-spa")],
            }),
          ],
        },
      ],
    ]
  }
})

Stuck?

Comment here, or in the #general channel in our slack workspace to ask questions.

[joeldenning]

Thread with example upgrade PRs. Feel free to reply with your own:

• Webpack 5 react-microfrontends/navbar#19 react-microfrontends/navbar@f724828 react-microfrontends/navbar@c1a777c
• Upgrading to webpack 5. react-microfrontends/api#10 react-microfrontends/api@8886ee7 react-microfrontends/api@849cde4
• Switch to pnpm and webpack 5 react-microfrontends/people#19 react-microfrontends/people@3aa7644 react-microfrontends/people@4d0af0a
• Upgrading to webpack 5, switching to pnpm react-microfrontends/root-config#21 react-microfrontends/root-config@e790826 react-microfrontends/root-config@be5c431
• Switching to pnpm. Upgrading to webpack 5. react-microfrontends/planets#17
• react-microfrontends/styleguide@504c851
• polyglot-microfrontends/root-config@2d156ff polyglot-microfrontends/root-config@e2194a4
• polyglot-microfrontends/navbar@084cea2 polyglot-microfrontends/navbar@c51a2e4
• polyglot-microfrontends/styleguide@46fbc26 polyglot-microfrontends/styleguide@c2fe2f5 polyglot-microfrontends/styleguide@735a89a

[filoxo]

Additional example webpack@5 upgrade PRs:

• Upgrade to Webpack 5 filoxo/single-spa-example-rxjs-shared-state#4
• Feat/upgrade webpack filoxo/single-spa-example-shared-styled-components#7
• Upgrade to webpack@5, webpack-merge@5 filoxo/single-spa-example-webpack-lazystyletag#3
• Upgrade Webpack 5 filoxo/single-spa-html-with-js-example#6

[tam81]

Hi @joeldenning ,

I wrote a shared library and used it in another app. Both are following the webpack single spa config. I am facing the issue - ReferenceError: System is not defined when running unit test in the app which is referring to shared code.

I stuck me several days already so any help or hint so that I can overcome this issue.

Sorry if this is not the right channel to ask this question.

Thanks and regards,

[joeldenning]

Hi @tam81, this is a good place to ask this question. Does your code call System.import() in it? Or is the error happening even without a System.import() in your code?

If your code has a System.import(), you likely will need to mock SystemJS in your project.

// jest.config.js
module.exports = {
  "setupFiles": "<rootDir>/src/setup-tests.js"
}

// setup-tests.js

global.System = {
  "import": jest.fn()
}

[joeldenning]

Another thing @tam81, someone else reported this same issue at https://single-spa.slack.com/archives/CLB2VV0UF/p1612775178011200. You can join our single-spa slack workspace at https://join.slack.com/t/single-spa/shared_invite/zt-l2iljnpv-pW_o92mMpMR8RWfIOI6pTQ which will let you see the conversation there (in case it helps in your situation, too)

[tam81]

Hi @joeldenning ,

Thank you for your quick response. My code does not call System.import() but I were able to solve the problem follow your suggestion.

One more thing, I also need to mock System.register() too.
`// setup-tests.js

global.System = {
"import": jest.fn(),
"register": jest.fn(),
}`

Thanks

[joeldenning]

Glad to hear you got it working!

[KshitijRaj09]

@joeldenning @tam81 I am also facing same problem. I have created a utility module using single-spa and using the utility-module inside my single-spa application. While running the test using jest. I am getting error ReferenceError: System is not defined.
utility-module present in application's node_modules as an dependency.
If you could help.
Thanks.