Building React Apps with the Nx Standalone Setup

In this tutorial you'll learn how to use React with Nx in a "standalone" (non-monorepo) setup.

What are you going to learn?

• how to create a new React application
• how to run a single task (i.e. serve your app) or run multiple tasks in parallel
• how to leverage code generators to scaffold components
• how to modularize your codebase and impose architectural constraints for better maintainability

Note, while you could easily use Nx together with your manually set up React application, we're going to use the @nx/react plugin for this tutorial which provides some nice enhancements when working with React. Visit our "Why Nx" page to learn more about plugins and what role they play in the Nx architecture.

Final Code

Here's the source code of the final result for this tutorial.

Creating a new React App

Create a new standalone React application with the following command:

You can choose any bundler you like. In this tutorial we're going to use Vite. The above command generates the following structure:

The setup includes..

• a new React application at the root of the Nx workspace (src/app)
• a Cypress based set of e2e tests (e2e/)
• Prettier preconfigured
• ESLint preconfigured
• Jest preconfigured

Let me explain a couple of things that might be new to you.

Serving the App

The most common tasks are already mapped in the package.json file:

To serve your new React application, just run: npm start. Alternatively you can directly use Nx by using

Your application should be served at http://localhost:4200.

Nx uses the following syntax to run tasks:

Inferred Tasks

Nx identifies available tasks for your project from tooling configuration files, package.json scripts and the targets defined in project.json. To view the tasks that Nx has detected, look in the Nx Console project detail view or run:

If you expand the build task, you can see that it was created by the @nx/vite plugin by analyzing your vite.config.ts file. Notice the outputs are defined as {projectRoot}/dist/myreactapp. This value is being read from the build.outDir defined in your vite.config.ts file. Let's change that value in your vite.config.ts file:

Now if you look at the project details view, the outputs for the build target will say {projectRoot}/build/myreactapp. This feature ensures that Nx will always cache the correct files.

You can also override the settings for inferred tasks by modifying the targetDefaults in nx.json or setting a value in your project.json file. Nx will merge the values from the inferred tasks with the values you define in targetDefaults and in your specific project's configuration.

Testing and Linting - Running Multiple Tasks

Our current setup doesn't just come with targets for serving and building the React application, but also has targets for unit testing, e2e testing and linting. We can use the same syntax as before to run these tasks:

More conveniently, we can also run them in parallel using the following syntax:

Caching

One thing to highlight is that Nx is able to cache the tasks you run.

Note that all of these targets are automatically cached by Nx. If you re-run a single one or all of them again, you'll see that the task completes immediately. In addition, (as can be seen in the output example below) there will be a note that a matching cache result was found and therefore the task was not run again.

Not all tasks might be cacheable though. You can configure the cache properties in the targets under targetDefaults in the nx.json file. You can also learn more about how caching works.

Nx Plugins? Why?

One thing you might be curious about is the inferred tasks. You may wonder why we are detecting tasks from your tooling configuration instead of directly defining them in package.json scripts or in the project.json file.

Nx understands and supports both approaches, allowing you to define tasks in your package.json and project.json files or have Nx plugins automatically detect them. The inferred tasks give you the benefit of automatically setting the Nx cache settings for you based on your tooling configuration. In this tutorial, we take advantage of those inferred tasks to demonstrate the full value of Nx plugins.

So, what are Nx Plugins? Nx Plugins are optional packages that extend the capabilities of Nx, catering to various specific technologies. For instance, we have plugins tailored to React (e.g., @nx/react), Vite (@nx/vite), Cypress (@nx/cypress), and more. These plugins offer additional features, making your development experience more efficient and enjoyable when working with specific tech stacks.

Visit our "Why Nx" page for more details.

Creating New Components

You can just create new React components as you normally would. However, Nx plugins usually also ship generators. They allow you to easily scaffold code, configuration or entire projects. To see what capabilities the @nx/react plugin ships, run the following command and inspect the output:

Run the following command to generate a new "hello-world" component. Note how we append --dry-run to first check the output.

As you can see it generates a new component in the app/hello-world/ folder. If you want to actually run the generator, remove the --dry-run flag.

Building the App for Deployment

If you're ready and want to ship your application, you can build it using

All the required files will be placed in the dist/myreactapp folder and can be deployed to your favorite hosting provider.

You're ready to go!

In the previous sections you learned about the basics of using Nx, running tasks and navigating an Nx workspace. You're ready to ship features now!

But there's more to learn. You have two possibilities here:

• Jump to the next steps section to find where to go from here or
• keep reading and learn some more about what makes Nx unique when working with React.

Modularizing your React App with Local Libraries

When you develop your React application, usually all your logic sits in the app folder. Ideally separated by various folder names which represent your "domains". As your app grows, this becomes more and more monolithic though.

Nx allows you to separate this logic into "local libraries". The main benefits include

• better separation of concerns
• better reusability
• more explicit "APIs" between your "domain areas"
• better scalability in CI by enabling independent test/lint/build commands for each library
• better scalability in your teams by allowing different teams to work on separate libraries

Creating Local Libraries

Let's assume our domain areas include products, orders and some more generic design system components, called ui. We can generate a new library for each of these areas using the React library generator:

Note how we use the --directory flag to place the libraries into a subfolder. You can choose whatever folder structure you like, even keep all of them at the root-level.

Running the above commands should lead to the following directory structure:

Each of these libraries

• has a project details view where you can see the available tasks (e.g. running tests for just orders: nx test orders)
• has its own project.json file where you can customize targets
• has a dedicated index.ts file which is the "public API" of the library
• is mapped in the tsconfig.base.json at the root of the workspace

Importing Libraries into the React Application

All libraries that we generate automatically have aliases created in the root-level tsconfig.base.json.

Hence we can easily import them into other libraries and our React application. As an example, let's create and expose a ProductList component from our modules/products library. Either create it by hand or run

We don't need to implement anything fancy as we just want to learn how to import it into our main React application.

Make sure the ProductList is exported via the index.ts file of our products library. This is our public API with the rest of the workspace. Only export what's really necessary to be usable outside the library itself.

We're ready to import it into our main application now. First (if you haven't already), let's set up React Router.

Configure it in the main.tsx.

Then we can import the ProductList component into our app.tsx and render it via the routing mechanism whenever a user hits the /products route.

Serving your app (nx serve) and then navigating to /products should give you the following result:

Let's apply the same for our orders library.

• generate a new component OrderList in modules/orders and export it in the corresponding index.ts file
• import it into the app.tsx and render it via the routing mechanism whenever a user hits the /orders route

In the end, your app.tsx should look similar to this:

Visualizing your Project Structure

Nx automatically detects the dependencies between the various parts of your workspace and builds a project graph. This graph is used by Nx to perform various optimizations such as determining the correct order of execution when running tasks like nx build, identifying affected projects and more. Interestingly you can also visualize it.

Just run:

You should be able to see something similar to the following in your browser.

Notice how ui is not yet connected to anything because we didn't import it in any of our projects.

Exercise for you: change the codebase such that ui is used by orders and products. Note: you need to restart the nx graph command to update the graph visualization or run the CLI command with the --watch flag.

Imposing Constraints with Module Boundary Rules

Once you modularize your codebase you want to make sure that the modules are not coupled to each other in an uncontrolled way. Here are some examples of how we might want to guard our small demo workspace:

• we might want to allow orders to import from ui but not the other way around
• we might want to allow orders to import from products but not the other way around
• we might want to allow all libraries to import the ui components, but not the other way around

When building these kinds of constraints you usually have two dimensions:

• type of project: what is the type of your library. Example: "feature" library, "utility" library, "data-access" library, "ui" library
• scope (domain) of the project: what domain area is covered by the project. Example: "orders", "products", "shared" ... this really depends on the type of product you're developing

Nx comes with a generic mechanism that allows you to assign "tags" to projects. "tags" are arbitrary strings you can assign to a project that can be used later when defining boundaries between projects. For example, go to the project.json of your orders library and assign the tags type:feature and scope:orders to it.

Then go to the project.json of your products library and assign the tags type:feature and scope:products to it.

Finally, go to the project.json of the ui library and assign the tags type:ui and scope:shared to it.

Notice how we assign scope:shared to our UI library because it is intended to be used throughout the workspace.

Next, let's come up with a set of rules based on these tags:

• type:feature should be able to import from type:feature and type:ui
• type:ui should only be able to import from type:ui
• scope:orders should be able to import from scope:orders, scope:shared and scope:products
• scope:products should be able to import from scope:products and scope:shared

To enforce the rules, Nx ships with a custom ESLint rule. Open the .eslintrc.base.json at the root of the workspace and add the following depConstraints in the @nx/enforce-module-boundaries rule configuration:

To test it, go to your modules/products/src/lib/product-list/product-list.tsx file and import the OrderList from the orders project:

If you lint your workspace you'll get an error now:

If you have the ESLint plugin installed in your IDE you should immediately see an error:

Learn more about how to enforce module boundaries.

Migrating to a Monorepo

When you are ready to add another application to the repo, you'll probably want to move myreactapp to its own folder. To do this, you can run the convert-to-monorepo generator or manually move the configuration files.

You can also go through the full React monorepo tutorial

Setup CI for Your React App

This tutorial walked you through how Nx can improve the developer experience for local development, but Nx can also make a big difference in CI. Without adequate tooling, CI times tend to grow exponentially with the size of the codebase. Nx helps reduce wasted time in CI with the affected command and Nx Replay's remote caching. Nx also efficiently parallelizes tasks across machines with Nx Agents.

To set up Nx Cloud run:

And click the link provided. You'll need to follow the instructions on the website to sign up for your account.

Then you can set up your CI with the following command:

This will create a default CI configuration that sets up Nx Cloud to use distributed task execution. This automatically runs all tasks on separate machines in parallel wherever possible, without requiring you to manually coordinate copying the output from one machine to another.

Check out one of these detailed tutorials on setting up CI with Nx:

• Circle CI with Nx
• GitHub Actions with Nx

Next Steps

Here's some things you can dive into next:

• Learn more about the underlying mental model of Nx
• Learn how to migrate your React app to Nx
• Learn how to setup Tailwind
• Setup Storybook for our shared UI library

Also, make sure you

• Join the Official Nx Discord Server to ask questions and find out the latest news about Nx.
• Follow Nx on Twitter to stay up to date with Nx news
• Read our Nx blog
• Subscribe to our Youtube channel for demos and Nx insights