@procore/core-scripts/docs/upgrading_to_v10.md

A CLI to enhance your development experience

# Upgrading to `@procore/core-scripts` v10

## Why upgrade

In this latest version of core-scripts, we are not bringing any new CLI functionality. It is primarily an upgrade to webpack 5 under the hood.

This brings the exciting new capability of [module federation](https://indepth.dev/posts/1173/webpack-5-module-federation-a-game-changer-in-javascript-architecture), which is webpack's solution to micro frontends.

If you would like to read more about the planned micro frontend architecture at Procore, please visit [this comprehensive overview](https://procoretech.atlassian.net/wiki/spaces/AA/pages/1613758671/Micro+Frontends).

## Upgrade steps

- Update your `package.json` to use the latest version of `@procore/core-scripts` and run `yarn install`
- Try to run `yarn core-scripts app:start` and `yarn core-scripts app:build`

## Enabling Module Federation for your app

The primary reason to upgrade to core-scripts v10 is to enable module federation. Ths is pretty easy to do in an application. You will need to edit your `procore.config.js`. Let's dissect the following module configuration a bit:

```js
module.exports = () => {
  return {
    app: {
      moduleFederation: {
        // This is your unique application id. Replace "myapp" with a unique string.
        // The recommendation to ensure uniqueness is to use a camelcased version
        // of your app's repository name.
        id: 'myapp',

        // You can expose (share) multiple components between micro frontends.
        // For now, we are simply exposing our CustomElement component mount point,
        // which calls ReactDOM.render to render out the application into a custom element.
        //
        // Rendering into a custom element is important because it provides encapsulation from
        // other micro frontends.

        // The keys should be PascalCased, and the values should point straight to component src files
        exposes: {
          MyApp: 'src/CustomElement.js',
        },

        // The dependencies listed here will be "shared" by micro frontends. This
        // means that if your application is loaded into the host, and the host
        // already contains dependencies that you are intending to use, it will
        // re-use the host's depedencies first
        //
        // Keep in mind that pinning dependencies will likely result in the
        // dependencies not being shared.
        //
        // But also keep in mind that not pinning dependencies can potentially
        // result in runtime errors, which must be handled accordingly.
        //
        // We should strive to enable dependabot or some type of automated
        // dependency updater on application repositories so that that all of
        // our applications are using similar versions of shared dependencies.
        shared: {
          react: '16.13.1',
          'react-dom': '16.13.1',
          'react-router-dom': '^5.2.0',
        },
      },
    },

    // ... other config
  }
}
```

If you would like to know more about module federation in general, please visit https://webpack.js.org/concepts/module-federation/ for reference.

## Things to account for

The upgrade process should be relatively straightforward, but this is assuming the client at hand does not have significant modifications to the webpack config via `procore.config.js`.

If your client has many webpack modifications, you may need to account for it during the upgrade process. In particular you may want to note the following:

### Custom loaders or plugins (or any other dependencies)

If the client has added any custom loaders or plugins to the webpack config, you will want to ensure that these plugins are compatible with webpack 5.

### Overriding style-loader or css-loader options

In the latest version of style-loader and css-loader, the default options for importing styles have changed. Of particular note is the [esModule](https://webpack.js.org/loaders/css-loader/#esmodule) option which now has the default set to `true`.

We have accounted for this in the base configuration that core-scripts uses, but if a client has happened to override configuration for either of these loaders it may need to be accounted for.

If you are importing scss styles and the css module names appear wonky this is most likely to be the culprit.

### Read the general webpack 4 to 5 upgrade guidelines

https://webpack.js.org/migrate/5/

## Reach Out

If you are having difficulties upgrading to webpack 5 and need help please reach out to the Frontend Foundations team.