Levelling up monorepos with npm workspaces

Learn more about how to leverage the default features of npm workspaces to help you manage your monorepo project while also checking out some of the new npm cli features.

Transcript

1. Levelling up Monorepos with
   npm
   workspaces
   DevOps.js | March 2022
   

   View Slide

2. whoami
   Ruy Adorno
   Senior Software
   Developer
   npm cli team at
   GitHub
   @ruyadorno
   

   View Slide

3. What are we going to
   be covering
   Intro to npm workspaces
   Getting Started
   Using npm workspaces features
   Running scripts
   Installing new packages
   Managing workspaces properties
   Cutting releases of a workspace
   Executing package scripts
   What to be looking forward to
   

   View Slide

4. npm workspaces
   Name of the set of features to support
   managing nested packages from a single
   top-level package
   Centralizes installation of all dependencies to
   a single node_modules folder
   Uses only a single package-lock.json file
   What is it?
   ` `
   ` `
   

   View Slide

5. npm workspaces
   Ideal for managing monorepos projects
   Single place to report & manage issues
   Single lint, build, test & release processes
   Eases coordination of changes across
   packages
   Eases development environment setup,
   troubleshooting
   Advantages
   

   View Slide

6. npm workspaces
   Timeline
   .
   │
   v7.0.0 (Aug 2020) ├── Introduced support to
   │ npm workspaces
   │
   │
   │
   v7.7.0 (Mar 2021) ├── Config properties, -w --ws
   │ supports: npm run & npm exec
   │
   v7.11.0 (Apr 2021) ├── Introduced workspace support
   │ to npm init
   │
   v7.14.0 (May 2021) ├── Support to add deps to a
   │ workspace using:
   │ npm -w install
   │
   │
   v8.1.0 (Oct 2021) ├── Added:
   │ --include-workspace-root
   │ and --no-workspaces
   │
   +
   

   View Slide

7. Using npm workspaces
   

   View Slide

8. Real project
   Evolved sample project that is set up as a
   monorepo, containing multiple workspaces with
   different web services and dev tooling.
   Monorepo App
   ├── slides
   │ Workspace that contains the source
   │ for this slide presentation.
   ├──────── Slidev
   ├── user-sync service
   │ Workspace that has a service that
   │ listens to an endpoint and stores
   │ user data received to the db.
   ├──────── Fastify
   ├──────── Prisma
   ├──────── Tap (tests)
   ├── webapp service
   │ Workspace with a service that
   │ serves the UI to render the user list.
   ├──────── Next.js
   ├──────── Tailwind CSS
   ├──────── Prisma
   └──────── Jest (tests)
   

   View Slide

9. npm init
   How to start using it?
   $ npm init -y -w ./workspace-a
   {
   "name": "my-project",
   "version": "1.0.0",
   "workspaces": ["./workspace-a"]
   }
   

   View Slide

10. Installing packages
    Adding a dependency ( ) to a workspace
    named workspace-a :
    Something to be looking forward to: noHoist
    ` `
    ` `
    $ npm -w ./workspace-a install
    ` `
    

    View Slide

11. Running scripts
    By workspace name:
    It support scoped names too:
    By workspace path:
    The workspace argument can go anywhere:
    It’s possible to run scripts in the context of a
    workspace:
    $ npm -w workspace-a run dev
    $ npm -w @myscope/workspace-a run dev
    $ npm -w ./workspace-a run dev
    $ npm run dev -w ./workspace-a
    

    View Slide

12. Organizing scripts
    The following example uses npm-run-all :
    The root package.json can orchestrate the
    spawning of nested package scripts.
    ` `
    ` `
    "scripts": {
    "dev:webapp": "npm run -w webapp dev",
    "dev:user-sync": "npm run -w user-sync dev",
    "dev": "run-p dev:*",
    "start": "npm run dev",
    "lint:webapp": "npm run -w webapp lint",
    "lint:user-sync": "npm run -w user-sync lint",
    "lint": "run-s lint:*",
    "pretest": "npm run lint",
    "test:webapp": "npm test -w webapp",
    "test:user-sync": "npm test -w user-sync",
    "test": "run-s test:*"
    },
    

    View Slide

13. Managing workspaces
    properties
    New command (added in v7.20.0) that retrieves
    and set info from package.json .
    ` `
    $ npm pkg
    

    View Slide

14. Managing workspaces
    properties
    Retrieving package.json info from a package:
    ` `
    $ npm pkg get
    {
    "name": "monorepo-app",
    "version": "1.0.0",
    "private": true,
    "workspaces": [
    "slides",
    "user-sync",
    "webapp",
    "website"
    ],
    ...
    }
    

    View Slide

15. Managing workspaces
    properties
    $ npm pkg get name version --ws
    

    View Slide

16. Cutting releases of a
    workspace
    Something to be looking forward to:
    Auto commit and tagging
    Bumping package version for a workspace:
    $ npm version -w ./workspace-a
    

    View Slide

17. Executing package
    scripts
    Executing a package in the context of a
    workspace:
    Executing a package in the context of all
    configured workspaces:
    $ npm exec -w ./workspace-a
    $ npm exec --ws
    

    View Slide

18. Learn More
    Docs: https://docs.npmjs.com
    GitHub: https://github.com/npm/cli
    Find me:
    @ruyadorno
    @ruyadorno
    https://ruyadorno.com
    

    View Slide