Nx Monorepo Libs Consumer

A demo create-react-app ("CRA") app that consumes libraries from an Nx monorepo.

Working With Packages From registry.npmjs.org

Treat this like a normal CRA project, there are no changes in the workflow.

Working With Nx Libs Locally

If you need to make changes to one or more underlying libs in the Nx repo, you'll need to link to those libraries locally, instead of using the version downloaded from npmjs.org.

This will allow you to see and test the changes before publishing the libraries for external usage.

Workflow in Brief

1. Convert this app to a pnpm workspace and reinstall the packages.
2. Increment the semver for the library to be worked on.
3. Make code changes in the library and this app.
4. Publish the updated library.
5. Convert the app back to non-workspace.
6. Upgrade to the new library version.

Workflow Step by Step

Convert App to Pnpm Workspace

1. Navigate to the app project root.

2. Create the workspace file.

   cp pnpm-workspace.yaml.example pnpm-workspace.yaml

3. Adjust the path to the monorepo libs if needed. By default it's assumed that the monorepo and the app are peers in the directory structure, e.g. src/monorepo and src/my-app.

4. Install dependencies, linking the monorepo libs locally.

   npx pnpm i --no-lockfile

   The --no-lockfile switch ensures that we don't overwrite pnpm-lock.yaml.

5. Verify that the linking worked.

   $ ls -l node_modules/@gsong/
   lrwxr-xr-x 30 george  1 Jun  7:01 ui -> ../../../monorepo/dist/libs/ui

   You should see that the library is linked to a local directory.

Increment Library Semver

1. Navigate to the library directory.

   cd $(MONOREPO)/libs/ui

2. Upgrade the version number

   npm version [type]

   Where [type] is major, minor, patch, etc.

Make Code Changes

1. Set up the real-time development build system.

   1. In the monorepo project root:

      npm run build:libs:watch

   2. In the app project root:

      npm start

2. Make the code changes in the library.

Publish the Library

1. Navigate to the monorepo project root.

2. Build the library and its dependencies.

   nx build ui --with-deps

3. Navigate to the library dist directory.

   cd $(MONOREPO)/dist/libs/ui

4. Publish.

   npm publish --access public

Convert Back to Non-Workspace App

1. Quit the real-time monorepo build watchers and the CRA dev server.

2. Navigate to the app project root.

3. Remove the workspace file.

   rm pnpm-workspace.yaml

4. Undo the local package link and upgrade.

   npx pnpm i @gsong/ui@latest

5. Verify that the unlinking worked.

   $ ls -l node_modules/@gsong/
   lrwxr-xr-x 69 george  1 Jun  8:05 design-system -> ../.pnpm/@gsong/design-system@0.0.1/node_modules/@gsong/design-system
   lrwxr-xr-x 47 george  1 Jun  8:05 ui -> ../.pnpm/@gsong/ui@0.0.3/node_modules/@gsong/ui

   You should see that the library (and its dependency) is linked to the pnpm registry.

6. Verify that everything is working properly.

   npm run build && npx serve -s build