Managing multiple Workers projects with Lerna

​​ Before you start

All of the tutorials assume you have already completed the Get started guide, which gets you set up with a Cloudflare Workers account, and the Workers CLI tool, Wrangler Open external link .

​​ Overview

Using lerna Open external link , a tool for managing multiple JavaScript codebases inside a single monorepo, developers can work with multiple Wrangler projects and share dependencies between them. If your codebase is already managed with lerna, you can also add a new Wrangler project into your existing monorepo without disrupting your workflow.

Begin by installing lerna, and creating a new project in the folder workers-monorepo:

Install lerna and init a new project
$ npm install -g lerna
$ mkdir workers-monorepo && cd workers-monorepo
$ lerna init

Inside of packages, where lerna will look for your projects, you can create multiple new Wrangler codebases, or even git clone your existing Workers codebase to migrate it into a lerna monorepo:

Create projects using Wrangler
$ cd packages
$ wrangler init my-api

# If you have existing projects, you can clone them into the directory:
$ git clone https://github.com/cloudflare/worker-template.git

This approach to managing your Workers projects can become incredibly powerful when you begin to share dependencies between projects. Imagine that your codebase has a pre-defined set of API handlers that you want to reuse between your public and private APIs, in the packages public-api and private-api:

Create projects using Wrangler
$ cd packages
$ wrangler init public-api
$ wrangler init private-api

Next to your API projects, create a new package handlers, which can be imported into each project:

Create a new lerna package
$ lerna create handlers

packages/public-api/package.json
{
  "dependencies": {
    "handlers": "1.0.0"
  }
}

Link the packages together using the bootstrap command and use them inside of your code:

Link packages using lerna bootstrap
$ lerna bootstrap

packages/public-api/index.js
// Omitting addEventListener and boilerplate code

import { json } from 'handlers';
const handler = request => {
  return json({ status: 200 });
};

After adding an identical dependency to private-api/package.json, run lerna bootstrap again, and begin sharing code between your projects.

When you are ready to deploy your codebases, define a script in each package’s package.json file (for example, publish), so that you can later deploy both codebases in a coordinated manner using the command lerna run <SCRIPT_NAME>:

packages/public-api/package.json
{
  "name": "public-api",
  "scripts": {
    "publish": "wrangler publish"
  }
}

packages/private-api/package.json
{
  "name": "private-api",
  "scripts": {
    "publish": "wrangler publish"
  }
}

lerna run publish will look for the publish script defined in each package’s project.json, and if the project defines it, it will run the script inside of that project’s directory:

Publish packages using lerna run
~/workers-monorepo $ lerna run publish

lerna info Executing command in 2 packages: "npm run publish"
lerna info run Ran npm script "publish" in "public-api" in 4.8s:

> public-api@1.0.0 publish /workers-monorepo/packages/public-api
> wrangler publish

lerna info run Ran npm script "publish" in "private-api" in 6.5s:

> private-api@1.0.0 publish /workers-monorepo/packages/private-api
> wrangler publish

lerna success run Ran npm script "publish" in 2 packages in 6.5s:
lerna success - public-api
lerna success - private-api

​​ Related resources

If you would like to review an example repository, refer to the accompanying open-source codebase on GitHub Open external link for this tutorial.