Upgrade to a new release

Journey Workspaces is a Create React App (CRA) template that leverages all existing capabilities of Create React App.

There are two ways to upgrade to a new Journey Workspaces release:

1. Create a new CRA app, then copy your configs to the new app's repo folder.
2. An in-place upgrade of your existing CRA app.

Upgrade with a new CRA app

When you create a new template project using npx create-react-app my-app --template @journey-ui/cra-template-ws@23.04.0, the latest version of react-scripts is installed which means you get all the latest Journey Workspaces features and improvements in newly created apps automatically.

Once you have your new CRA application folder, copy over the configs from your existing application, keeping in mind that there may be differences in config file formats between Journey Workspaces releases.

We have simplified the way upgrades are executed. Bumping the @journey-ui/workspaces version in package.json and running npm install (or yarn install) in this folder should be enough, but there can be breaking changes. While we endeavour to keep the number of breaking changes small to minimise the impact on upgrades, sometimes these are necessary. To learn about breaking changes in this release, see the migration guide for this release.

In-place upgrade of an existing CRA app

To upgrade an existing CRA app in-place, we need to change two system files, package.json and craco.config.js, both of which you can find in the root folder of your existing app.

You may also need to make changes to your config files. To learn about config files, see the Configuration section of this documentation.

package.json file changes

Open package.json, located in the root folder of your application's repo, and change the "dependencies" section to look like this:

  "dependencies": {
    "@craco/craco": "^7.1.0",
    "@journey-ui/workspaces": "^23.4.2",
    "@testing-library/jest-dom": "^5.17.0",
    "@testing-library/react": "^14.0.0",
    "@testing-library/user-event": "^13.5.0",
    "@transact-open-ux/cli": "^0.1.6",
    "@types/jest": "^27.5.2",
    "@types/node": "^16.18.58",
    "@types/react": "^18.2.28",
    "@types/react-dom": "^18.2.13",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-scripts": "^5.0.1",
    "stream-browserify": "^3.0.0",
    "typescript": "^4.9.5",
    "web-vitals": "^2.1.4"
  },

The stream-browserify library is the only new entry here. The other changes are upgrades to existing libraries.

After updating the package.json file, run npm install to pull in the new library dependencies.

craco.config.js file changes

Open craco.config.js, located in the root of your application's repo, and replace the file contents with the following:

module.exports = {
    webpack: {
      configure: webpackConfig => {
        const scopePluginIndex = webpackConfig.resolve.plugins.findIndex(
          ({ constructor }) => constructor && constructor.name === 'ModuleScopePlugin'
        );

      // Required for Webpack 5/ Node 18
      const webpackConfigNode18 = {
        ...webpackConfig,
        resolve: {
          ...webpackConfig.resolve,
          fallback: {
            ...webpackConfig.resolve.fallback,
            stream: require.resolve("stream-browserify"),
          },
        },
      };

      webpackConfigNode18.resolve.plugins.splice(scopePluginIndex, 1);
      return webpackConfigNode18;
      }
    }
  };

You should now be able to run npm start (or yarn start) to start your application as normal.

Config file format changes

If npm start fails after making the system file changes above, this may be because the format of the config files has changed. Check for errors in your terminal to determine if this the cause.

Information about config files is available in the Configuration section of this documentation.