Workspaces for npm: a multi-package build manager
Last updated 2 months ago by bstefanescu .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install npm-ws -g
SYNC missed versions from official npm registry.

npm-ws - Workspaces for npm

A multi-package project manager for npm.

This is a tool to easily build, test and publish your javascript products that contains multiple inter-dependent npm packages inside a single source repository.

npm-ws was initially created to manage the development life cycle of Qute.


  • Provides basic tasks for npm package development like build, test, publish, version etc.
  • Extensible task registry: you can define simple tasks directly in the root package.json or more complex tasks using javascript files.
  • Can easily be integrate with any javascript bundler and tester.
  • Built-in integration with rollup and mocha
  • Integrated development server (with live reload support over multiple dependent packages)


Node version 10 is required.


To install:

npm install -g npm-ws

Then add a build entry in your package.json to define your repository layout, custom tasks and other build configuration.

The root package of a monorepo product is not publishable (you must use private: true in your root package.json). The root package only serves as a container for publishable packages.

The root package is the workspace. The workspace can contain one or more npm packages (or projects). A workspace is respnsible to run tasks on its projects.

Tasks are of two types:

  1. global tasks - which runs at workspace level. Example: help, projects etc.
  2. project tasks - which are run on each project respecting the dependency order between projects (i.e. projects required by another project will be processed first).


ws [project] [task] [task arguments ...]


  1. project - an optional package name. For scoped packages you can use the local name too. When specified the task will run only on that project. Otherwise the task is run on all the workspace projects.
  2. task - an optional task. If not specified the help task will be run.
  3. All the other arguments will be passed to the task as arguments.

When running ws inside a project directory it will run the tasks only on that project (as if the project argument was given)


Not all the build configuration and tasks are documented. To see an example of how to configure a workspace look into the root package.json of Qute;

More documentation is comming soon.


Install the workspace (and contained projects) dependencies. Dependency projects will be linked in the node_modules directory of the dependent project.

You must use this command to initialize the dependencies and not npm install.

ws install


Remove all generated node_modules directories

ws uninstall


Run a shell command against all the projects.


ws shell ls -1

will list the content of each project

ws subproject shell ls -1

will list the content of the given subproject


Run the build (against all projects). This task requires some additional configuration. If you are using rollup as the bundler - you only need to specify a rollup config file (or one per project type). If you don't use rollup then you need to write a script to integrate the bundler.

ws build


Run the tests (against all projects). This task requires some additional configuration. By default mocha will be used as the tester. If you want to use another tester then you need to write an integration script.

ws test


Run a set of tasks against all projects.

Each task will be run on each of the workspace projects. After a task completes then the next task is run on each of the workspace projects.


ws run build test

To specify arguments for a task in the run list use quotes or double quotes:

ws run "build prod" test


Update version of all projects (including workspace package.json) to the given version.

ws version 'version'

where version is:

  1. an explicit version. Example: 1.1.0.
  2. the string 'major'
  3. the string 'minor'
  4. the string 'patch'


Publish all publishable projects.

The arguments passed to publish task are passed down to npm publish.


ws publish --dry-run


Start the development server. Usually used in conjunction with watch.


ws start


Watch for file changes and rebuild. Usually used in conjunction with start


ws run "build dev" watch start


List the projects in the workspace

ws projects


Display the help screen.s

ws help


Link dependent projects

ws link


Remove dependent project links

ws unlink


Remove files (with glob support). Usually called from another tasks (like clean)




Bogdan Stefanescu - Intial Work - Quandora

Current Tags

  • 0.9.3                                ...           latest (2 months ago)

4 Versions

  • 0.9.3                                ...           2 months ago
  • 0.9.2                                ...           2 months ago
  • 0.9.1                                ...           5 months ago
  • 0.9.0                                ...           5 months ago
Maintainers (1)
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 0
Dependencies (9)
Dev Dependencies (0)
Dependents (0)

Copyright 2014 - 2016 © |