Skip to content

Commit

Permalink
feat(react): add CRA support to "nx init"
Browse files Browse the repository at this point in the history 
- Runs cra-to-nx for now
  • Loading branch information
@jaysoo
jaysoo authored and Jack Hsu committed Nov 29, 2022
1 parent 6c59cbb commit 0e0e702
Show file tree
Hide file tree
Showing 3 changed files with 51 additions and 315 deletions.
328 changes: 20 additions & 308 deletions docs/shared/migration/migration-cra.md
View file
Original file line number Diff line number Diff line change
@@ -1,327 +1,39 @@
# Migrating a Create-React-App project into an Nx Workspace

Create-React-App (CRA) is the most widely used tool for creating, building and testing a React app. This guide will show you how move an app generated with CRA into an Nx workspace. Once the migration process is complete, you'll be able to take advantage of all of Nx's features without needing to completely recreate your build process.
Create-React-App (CRA) is one of the most widely used tool for creating, building and testing a React app. This guide
will show you how move an app generated with CRA into an Nx workspace. Once the migration process is complete, you'll be
able to take advantage of all of Nx's features without needing to completely recreate your build process.

You can either use a CLI tool to migrate your app automatically, or you can follow the steps described below to do the migration manually.
## Automated migration

{% callout type="caution" title="Nx < 13" %}
This guide has been updated for Nx 13 and may not work for earlier versions of Nx.
{% /callout %}

If you have a monorepo (more than one project in the same repo), follow the [Adding Nx to Lerna/Yarn/PNPM/NPM Workspace](/recipes/adopting-nx/adding-to-monorepo) guide instead.

## Using a tool that will do it for you

You can use the [`cra-to-nx`](https://www.npmjs.com/package/cra-to-nx) tool, that will run the following steps for you, and will turn your Create-React-App (CRA) project into an Nx workspace.

Just `cd` into your Create-React-App (CRA) project and run the following command:
The easiest way to setup Nx in your CRA project is to use the automated migration tool.

```shell
npx cra-to-nx
npx nx init
```

Then just sit back and wait. After a while, take advantage of the [full magic of Nx](/getting-started/intro).
Start from [the commands mentioned in this article](/recipes/adopting-nx/migration-cra#try-nx).

{% callout type="caution" title="Commit your changes" %}
The command will fail if you try to execute it, and you have uncommitted changes in your repository. Commit any local changes, and then try to run the command.
{% /callout %}

See it in action:

{% youtube
src="https://www.youtube.com/embed/_XmbVpwo1vs"
title="Switch from CRA to Nx"
width="100%" /%}

## Doing the migration manually

In this article, you’ll learn how to:

- Create an Nx workspace for a React application
- Migrate a React application into your Nx workspace
- Convert CRA scripts for use in Nx
- Create a library and use it in your application

For this example, you’ll be migrating the default CRA typescript template app into an Nx workspace. This is the code that is generated when you run `npx create-react-app webapp --template typescript`.
The command above will detect that the project is generated with CRA, and that it has not been _ejected_, or _
customized_ with either `react-app-rewired` or `@craco/craco`. If the project has either been ejected or customized,
then the migration will still continue but you will be prompted for more information.

There is also a [repo](https://github.com/nrwl/cra-to-nx-migration) that shows the finished result of this guide and for each step a [diff](https://github.com/nrwl/cra-to-nx-migration/commits/main) will be provided to see the exact code changes that occur for that step.
That's it!

{% github-repository url="https://github.com/nrwl/cra-to-nx-migration" /%}
{% callout type="note" title="Vite" %}
You will notice that the project now uses [Vite](https://vitejs.dev/) and [Vitest](https://vitest.dev/) to build and
test your application. Vite is a next-gen tooling for building frontend applications, and is much faster than Webpack (
which CRA uses).

### 1. Create your workspace

To start migrating your app, create an Nx workspace:

```shell
npx create-nx-workspace@latest acme --appName=webapp --preset=react --style=css --nx-cloud
```

{% callout type="warning" title="Scope & appName?" %}
Replace `acme` with your organization's npm scope. This will be used when importing workspace projects. You can also replace `webapp` with a different name -- you can have more than one app in an Nx workspace.
If you do not want to use Vite, you can run `npx nx init --vite=false` instead.
{% /callout %}

### 2. Add npm packages to your workspace to support CRA

We'll need to add a few dependencies to the Nx workspace that are needed to allow CRA to function.

{% tabs %}
{% tab label="yarn" %}

```shell
yarn add --dev react-scripts @testing-library/jest-dom eslint-config-react-app @craco/craco
yarn add web-vitals
```

{% /tab %}
{% tab label="npm" %}

```shell
npm install --force --save-dev react-scripts @testing-library/jest-dom eslint-config-react-app @craco/craco
npm install --save web-vitals
```

{% /tab %}
{% /tabs %}

{% callout type="note" title="What is @craco/craco?" %}
The `@craco/craco` package allows us to customize the webpack and jest config without ejecting.
{% /callout %}

### 3. Replace code generated by Nx with the CRA app

The source code for each app in an Nx workspace should be contained within the folder of a generated app. The `create-nx-workspace` command from step 1 created an app folder at `apps/webapp` that we can use to contain the CRA app. Delete the existing contents and copy over the CRA app code.

```shell
cd apps/webapp
ls -A . | grep -v 'project.json' | xargs rm -rf
cd -
cp -r /path/to/cra-app/{README.md,package.json,tsconfig.json,src,public} apps/webapp
```

Replace `/path/to/cra-app` with the actual path to your CRA app on your machine.

### 4. Customize webpack using craco

The `@craco/craco` package allows you to customize the webpack config of CRA by creating `apps/webapp/craco.config.js`. Inline comments explain what each section is doing:

#### Copy this code if you are using CRA >=v5

```javascript
const path = require('path');
const TsConfigPathsPlugin = require('tsconfig-paths-webpack-plugin');
const ModuleScopePlugin = require('react-dev-utils/ModuleScopePlugin');
module.exports = {
webpack: {
configure: (config) => {
// Remove guard against importing modules outside of \`src\`.
// Needed for workspace projects.
config.resolve.plugins = config.resolve.plugins.filter(
(plugin) => !(plugin instanceof ModuleScopePlugin)
);
// Add support for importing workspace projects.
config.resolve.plugins.push(
new TsConfigPathsPlugin({
configFile: path.resolve(__dirname, 'tsconfig.json'),
extensions: ['.ts', '.tsx', '.js', '.jsx'],
mainFields: ['module', 'main'],
})
);

// Replace include option for babel loader with exclude
// so babel will handle workspace projects as well.
config.module.rules[1].oneOf.forEach((r) => {
if (r.loader && r.loader.indexOf('babel') !== -1) {
r.exclude = /node_modules/;
delete r.include;
}
});

return config;
},
},
jest: {
configure: (config) => {
config.resolver = '@nrwl/jest/plugins/resolver';
return config;
},
},
};
```

#### Copy this code if you are using CRA <=v4

```javascript
const path = require('path');
const TsConfigPathsPlugin = require('tsconfig-paths-webpack-plugin');
const ModuleScopePlugin = require('react-dev-utils/ModuleScopePlugin');
module.exports = {
webpack: {
configure: (config) => {
// Remove guard against importing modules outside of \`src\`.
// Needed for workspace projects.
config.resolve.plugins = config.resolve.plugins.filter(
(plugin) => !(plugin instanceof ModuleScopePlugin)
);
// Add support for importing workspace projects.
config.resolve.plugins.push(
new TsConfigPathsPlugin({
configFile: path.resolve(__dirname, 'tsconfig.json'),
extensions: ['.ts', '.tsx', '.js', '.jsx'],
mainFields: ['module', 'main'],
})
);

// Replace include option for babel loader with exclude
// so babel will handle workspace projects as well.
config.module.rules.forEach((r) => {
if (r.oneOf) {
const babelLoader = r.oneOf.find(
(rr) => rr.loader.indexOf('babel-loader') !== -1
);
babelLoader.exclude = /node_modules/;
delete babelLoader.include;
}
});

return config;
},
},
jest: {
configure: (config) => {
config.resolver = '@nrwl/jest/plugins/resolver';
return config;
},
},
};
```

### 5. Update package scripts

Update your app's `package.json` file (path: `apps/webapp/package.json`) to use `craco` instead of `react-scripts`.

```text {% fileName="apps/webapp/package.json" %}
{
...
"scripts": {
"serve": "craco start",
"build": "BUILD_PATH=../../dist/apps/cra-app craco build",
"test": "craco test",
"eject": "react-scripts eject"
},
...
}
```

{% callout type="note" title="BUILD_PATH" %}
The `BUILD_PATH` variable is set to be consistent with other Nx projects. This is optional so you can remove it.
{% /callout %}

### 6. Remove targets from project.json

Your new project will use the `craco` scripts we added in `apps/webapp/package.json` in the previous step. Therefore, it will not need the `targets` set in `project.json` by Nx. In fact, if we leave the targets there, Nx will try to use this and it will fail. So we need to remove them.

In `apps/webapp/project.json` remove the `targets` object. The result will look like this:

```json {% fileName="apps/webapp/project.json" %}
{
"root": "apps/webapp",
"sourceRoot": "apps/webapp/src",
"projectType": "application",
"tags": []
}
```

### 7. Extend the app's tsconfig.json from the base

Modify `apps/webapp/tsconfig.json` to extend the root `tsconfig.base.json`. This is primarily to pickup the typescript aliases from the root tsconfig file.

```jsonc {% fileName="apps/webapp/tsconfig.json" %}
{
"extends": "../../tsconfig.base.json",
...
}
```

### 8. Add tsconfig files for jest and eslint

It's helpful to have separate `tsconfig.json` files for testing and linting. In this instance, the actual typescript settings are identical to the base config, so these tsconfig files will extend the base without modifying any values.

```shell
echo '{ "extends": "./tsconfig.json" }' > apps/webapp/tsconfig.app.json
echo '{ "extends": "./tsconfig.json" }' > apps/webapp/tsconfig.spec.json
```

### 9. Skip CRA preflight check since Nx manages the monorepo.

CRA checks to make sure there are no incompatible dependencies before any scripts run, but the `@nrwl/react` plugin serves the same purpose and requires slightly different versions in order to function correctly in an Nx workspace. Setting this environment variable disables CRA's check.

```shell
echo "SKIP_PREFLIGHT_CHECK=true" > .env
```

### 10. Add all node_modules to .gitignore

An `apps/webapp/node_modules` folder will be generated to hold some cache values when a build is run. This cache shouldn't be committed to git, so we tell git to ignore any `node_modules` folder.

```shell
echo "node_modules" >> .gitignore
```

## Try Nx

### 1. Try the commands

The following commands are now available for you to try.
Use the same scripts as before, and Nx will run underneath the hood with `nx exec`.

```shell
npx nx serve webapp
npx nx build webapp
npx nx test webapp
npm start
npm run build
npm test
```

The `serve` command will automatically update when code changes, but needs to be restarted if you add a whole new library to your workspace.

`build` and `test` are set up to automatically cache their results. Subsequent runs of `nx build webapp` (without changing any code) should only take a couple seconds.

(No code changes for this step.)

### 2. Create a library

Nx makes it very easy to create isolated collections of reusable code in libraries. Running this script will create a library named `ui-button`.

```shell
nx generate lib ui-button
```

[View the code changes](https://github.com/nrwl/cra-to-nx-migration/commit/87cdbd1e8195b9ca1e726f15d6ced18c02f728b7)

### 3. Use the library

The new library can be used in your app like by adding this code to `App.tsx`:

```typescriptx {% fileName="App.tsx" %}
//...
import { UiButton } from '@acme/ui-button';
//...
<UiButton onClick={learnMore}>Learn React</UiButton>;
//...
```

Make sure you also copy the code for your new `ui-button` from [here](https://github.com/nrwl/cra-to-nx-migration/commit/782ce78d46b14f5f802e1b1cf31be566d15ce41f).

The `@acme/ui-button` path alias is defined in the root `tsconfig.base.json` file.

Now serve the app again to see the result:

```shell
nx serve webapp
```

[View the code changes](https://github.com/nrwl/cra-to-nx-migration/commit/782ce78d46b14f5f802e1b1cf31be566d15ce41f)

## Summary

- Create-React-App projects can be migrated into an Nx workspace using existing build and serve processes
- `@craco/craco` allows you to continue using CRA and modify the webpack configuration
- Caching is automatically enabled as part of the migration
`build` and `test` are set up to automatically cache their results. Subsequent runs of `npm run build` (without changing any code), for example, should only take a couple seconds.
Loading

0 comments on commit 0e0e702

Please sign in to comment.