How to manage multiple Front-End projects with a monorepo
- Written by
Rui Saraiva- Published
- Last updated
πΒ This blog post is crafted for individuals with solid web development skills. If you're already familiar with setting up web projects but want to enhance your skills further, we recommend reading our previous blog post,Β How to set up a Front-End project with Vite, React, and TypeScript (opens in a new tab), which covers foundational concepts that will reinforce your understanding of the content discussed in this blog post.
Imagine having an organization with multiple projects. Wouldn't it be great to have all those projects inside a single repository where you could easily share code and maintain consistency across the organization?
We asked ourselves these same questions when we researched the best way to introduce a new Front-End project to an existing repository. Our goal was to reuse as much code as possible to maintain consistency across projects and introduce as little complexity as possible.Β This is where the concept of monorepos comes into play.
Do you want to build or revamp your digital product?
What is a monorepo?
You may have heard the term "monorepo" before. A monorepo is a single repository containing multiple distinct projects, with well-defined relationships.
Are monorepo and monolith the same?
A good monorepo is the opposite of a monolith! You can read more about this and other misconceptions in Victor Savkinβs articleΒ βMisconceptions about Monorepos: Monorepo != Monolithβ (opens in a new tab).
What are the advantages of using a monorepo?
Monorepos have a lot of advantages, but to make them work, you need to have the right tools. As your workspace grows, the tools have to help you keep it fast, manageable, and easy to understand.
- Local computation caching:Β the ability to store and replay file and process output of tasks. On the same machine, you will never build or test the same thing twice.
- Local task orchestration:Β the ability to run tasks in the correct order and in parallel. All tools listed below can do it in about the same way, except Lerna, which is more limited.
- Distributed computation caching: the ability to share cached artifacts across different environments. This means that your whole organization, including CI agents, will never build or test the same thing twice.
- Distributed task execution: the ability to distribute a command across multiple machines, while largely preserving the developer ergonomics of running it on a single machine.
- Detecting affected projects/packages: determine which projects might be affected by a change, in order to only build or run tests for those projects.
- Workspace analysis: the ability to understand the graph of projects within the workspace without additional configuration.
- Dependency graph visualization:Β visualize dependency relationships between projects and/or tasks. The visualization is interactive meaning that you are able to search, filter, hide, focus/highlight, and query the nodes in the graph.
- Code sharing: facilitates sharing of discrete pieces of source code between projects.
- Code generation:Β native support for command-based code generation.
βIt's not just about the features
Features matter! Things like support for distributed task execution can be game changers, especially in large monorepos. ButΒ there are other extremely important things, such as developer ergonomics, maturity, documentation, editor support, and so on.
Some tools that help you manage a monorepo
There are many solutions that aim at different goals. Each tool fits a specific set of needs and gives you a precise set of features. Here are some of the available tools:
- Bazel (opens in a new tab)Β (by Google) - A fast, scalable, multi-language and extensible build system.
- Gradle (opens in a new tab)Β (by Gradle, Inc) - A fast, flexible polyglot build system designed for multi-project builds.
- Lage (opens in a new tab)Β (by Microsoft) - Task runner in JS monorepos.
- Lerna (opens in a new tab)Β (maintained by Nrwl) - A tool for managing JavaScript projects with multiple packages.
- Nx (opens in a new tab)Β (by Nrwl) - Next generation build system with first class monorepo support and powerful integrations.
- Pants (opens in a new tab)Β (by Pants Build) - A fast, scalable, user-friendly build system for codebases of all sizes.
- Rush (opens in a new tab)Β (by Microsoft) - Geared for large monorepos with lots of teams and projects. Part of the Rush Stack family of projects.
- Turborepo (opens in a new tab)Β (by Vercel) - The high-performance build system for JavaScript & TypeScript codebases.
Why Turborepo?
The problem
Monorepos have many advantages - butΒ they struggle to scale. Each workspace has its own test suite, its own listing, and its own build process. A single monorepo might haveΒ hundreds of tasks to execute.
The solution
Turborepo solves monorepos' scaling problem. Its remote cache stores the result of all your tasks, meaning thatΒ your CI never needs to do the same work twice.
Task scheduling can be difficult in a monorepo. ImagineΒ yarn buildΒ needs to run beforeΒ yarnΒ testΒ across all your workspaces. TurborepoΒ can schedule your tasks for maximum speed, across all available cores.
Turborepo can beΒ adopted incrementally. It uses theΒ package.jsonΒ scripts you've already written, the dependencies you've already declared, and a single turbo.json file. You canΒ use it with any package manager, likeΒ npm,Β yarnΒ orΒ pnpm. You can add it to any monorepo in just a few minutes.
What Turborepo is not
TurborepoΒ doesn't handle package installation. Tools likeΒ npm,Β pnpmΒ orΒ yarnΒ already do that brilliantly. But they run tasks inefficiently, meaning slow CI pipelines.
We recommend thatΒ Turborepo runs your tasks, and your favorite package manager installs your packages.
Set up a monorepo: step by step
π The implementation provided in this guide is available inΒ this GitHub repository (opens in a new tab), where the commits correspond to the steps outlined throughout the guide, following the same order.
Tutorial Node.js version: 18.17.0
Tutorial npm version: 9.5.0
Step 1: Initiate a new npm project
mkdir demo-monorepo
cd demo-monorepo
npm init -y
git initYouβll then end up with the following file structure:
.
βββ package.jsonβStep 2: Set up npm workspaces
npmΒ workspaces (opens in a new tab)Β is a generic term that refers to the set of features in the npm CLI that provides support to managing multiple packages from your local file system from within a singular top-level root package.
Letβs define the workspaces via theΒ workspaces property of theΒ package.jsonΒ file:
{
"name": "demo-monorepo",
"version": "1.0.0",
"description": "",
"main": "index.js",
"workspaces": [
"apps/*",
"packages/*"
],
"devDependencies": {},
"keywords": [],
"author": "",
"license": "ISC"
}We added bothΒ apps/*Β andΒ packages/*Β which tells npm that every npm project directly inside bothΒ appsΒ andΒ packagesΒ folders is considered as a workspace package.
You can use any name you want for the folder names. We are going to use the apps folder for managing front-end projects and the packages folder for managing other packages that will be used by ourΒ appsΒ Front-End projects.
By the end of this step, the file structure shall remain unchanged:
βββ package.jsonStep 3: Set up a couple of front-end projects
Letβs start adding our first front-end project by cloning the repository we created on theΒ βHow to set up a front-end project with Vite, React, and TypeScriptβ (opens in a new tab)Β blog post:
npx degit pixelmatters/setup-project-demo#v2.0.1 apps/project-oneThis command clones the repository into theΒ apps/project-oneΒ folder. The cloned repo has a couple of files/folders that we want to move to the repository root.
Move theΒ .githubΒ folder by running:
mv apps/project-one/.github .githubMove theΒ .huskyΒ folder by running:
mv apps/project-one/.husky .huskyAfter moving the Husky git-hook files, we also need to move the post install script (prepare) Β and theΒ huskyΒ npm dependency from apps/project-one/package.jsonΒ to the rootΒ package.jsonΒ file:
"name": "demo-monorepo",
"version": "1.0.0",
"description": "",
"main": "index.js",
"workspaces": [
"apps/*",
"packages/*"
],
"scripts": { // This object was updated
"prepare": "husky install"
},
"devDependencies": { // This object was added
"husky": "^8.0.3"
},
"keywords": [],
"author": "",
"license": "ISC"
}Move theΒ .vscodeΒ folder by running:
mv apps/project-one/.vscode .vscodeMove theΒ .commitlintrcΒ file by running:
mv apps/project-one/.commitlintrc.json .commitlintrc.jsonAfter moving the commitlint configuration file, we also need to move the its npm dependencies to the rootΒ package.jsonΒ file:
{
"name": "demo-monorepo",
"version": "1.0.0",
"description": "",
"main": "index.js",
"workspaces": [
"apps/*",
"packages/*"
],
"scripts": {
"prepare": "husky install"
},
"devDependencies": {
"@commitlint/cli": "^17.6.7", // This line was added
"@commitlint/config-conventional": "^17.6.7", // This line was added
"husky": "^8.0.3"
},
"keywords": [],
"author": "",
"license": "ISC"
}Move theΒ .nvmrcΒ file by running:
mv apps/project-one/.nvmrc .nvmrcThatβs all for the monorepo base configuration files for now.
When using npm workspaces, there must be only oneΒ package-lock.jsonΒ file on the repository, which must live in the repository root, meaning that weβll need to remove every lock files inside our workspaces. For now we only have one workspace to remove from:
rm apps/project-one/package-lock.jsonBefore we install all npm dependencies, letβs reuse our existingΒ .gitignoreΒ file by copying it fromΒ app/project-oneΒ into the root:
cp apps/project-one/.gitignore .Note that each npm workspace must have a unique name. We will update theΒ app/project-oneΒ workspace project name fromΒ demo-projectΒ toΒ project-one:
{
"name": "project-one", // This line was updated
"version": "0.0.0",
// ...
}Now we are ready to install all workspaces dependencies by runningΒ npm installΒ on the root of the monorepo. This will create a newΒ package-lock.jsonΒ on the root folder.
Now, we should be able to run npm scripts for theΒ project-oneΒ project by using theΒ workspaceΒ option:
npm run dev --workspace project-one
// or
npm run dev -w project-oneRunning this command will start a local Vite development server onΒ http://localhost:5173Β and by accessing that link you should see something like the following:

At this point, we have one project working within a monorepo via npm workspaces. πΒ Now, letβs clone theΒ project-oneΒ project to create a second front-end project.
cp -r apps/project-one apps/project-twoThis command will duplicate theΒ apps/project-oneΒ folder intoΒ apps/project-twoΒ folder.
Before we start running the project-two development server, letβs update a couple of files so we donβt end up with unexpected conflicts.Β First, we can update the app/project-one/index.html file to have a Project One title:
<html lang="en">
<head>
<meta charset="UTF-8" />
<link rel="icon" type="image/svg+xml" href="/src/favicon.svg" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Project One</title>
</head>
<body>
<div id="root"></div>
<script type="module" src="/src/main.tsx"></script>
</body>
</html>Another one we can update is theΒ apps/project-one/src/App.tsxΒ file by updatingΒ Hello Vite + React!Β toΒ Hello Project One!:
import { useState } from 'react'
import logo from './logo.svg'
import './App.css'
export const App: React.FC = () => {
const [count, setCount] = useState(0)
return (
<div className="app">
<header className="app-header">
<img src={logo} className="app-logo" alt="logo" />
<p>Hello Project One!</p>{/* This line was updated */}
<p>
<button type="button" onClick={() => setCount((count) => count + 1)}>
count is: {count}
</button>
</p>
<p>
Edit <code>App.tsx</code> and save to test HMR updates.
</p>
<p>
<a
className="app-link"
href="https://reactjs.org"
target="_blank"
rel="noopener noreferrer"
>
Learn React
</a>
{' | '}
<a
className="app-link"
href="https://vitejs.dev/guide/features.html"
target="_blank"
rel="noopener noreferrer"
>
Vite Docs
</a>
</p>
</header>
</div>
)
}Letβs make the same adjustments to theΒ project-twoΒ Front-End project:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<link rel="icon" type="image/svg+xml" href="/src/favicon.svg" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Project Two</title>
</head>
<body>
<div id="root"></div>
<script type="module" src="/src/main.tsx"></script>
</body>
</html>import { useState } from 'react'
import logo from './logo.svg'
import './App.css'
export const App: React.FC = () => {
const [count, setCount] = useState(0)
return (
<div className="app">
<header className="app-header">
<img src={logo} className="app-logo" alt="logo" />
<p>Hello Project Two!</p>{/* This line was updated */}
<p>
<button type="button" onClick={() => setCount((count) => count + 1)}>
count is: {count}
</button>
</p>
<p>
Edit <code>App.tsx</code> and save to test HMR updates.
</p>
<p>
<a
className="app-link"
href="https://reactjs.org"
target="_blank"
rel="noopener noreferrer"
>
Learn React
</a>
{' | '}
<a
className="app-link"
href="https://vitejs.dev/guide/features.html"
target="_blank"
rel="noopener noreferrer"
>
Vite Docs
</a>
</p>
</header>
</div>
)
}Now that we have multiple front-end projects within our monorepo, we can take advantage of npm workspaces and run scripts on multiple workspaces at the same time. So, by running the following command we can run the tests for bothΒ project-oneΒ andΒ project-twoΒ front-end projects. Notice theΒ --workspacesΒ option:
npm run test --workspacesWhen we run the previous command, the following error was raised:
β― npm run test --workspaces
npm ERR! code EDUPLICATEWORKSPACE
npm ERR! must not have multiple workspaces with the same name
npm ERR! package 'project-one' has conflicts in the following paths:
npm ERR! /Users/ruisaraiva/dev/pixelmatters/demo-monorepo/apps/project-one
npm ERR! /Users/ruisaraiva/dev/pixelmatters/demo-monorepo/apps/project-twoThis error states that we must not have multiple workspaces with the same name. This is one of the rules of workspaces. Every workspace must have a unique name. With that in mind, letβs update theΒ project-twoΒ workspace name inside theΒ apps/project-two/package.jsonΒ file:
{
"name": "project-two", // This line was updated
"version": "0.0.0",
"engines": {
"node": ">=18.17.0",
"npm": ">=9.0.0"
},
// ...
}Now, letβs run install all dependencies again to pick up the new workspace name:
npm installWe can now try running the tests for bothΒ project-oneΒ andΒ project-twoΒ front-end projects again:
npm run test --workspacesThis time the command didnβt exit with the error from before. We got the following output:
β― npm run test --workspaces
> [email protected] test
> jest
PASS src/demo.test.ts
FAIL src/App.test.tsx
β renders hello message
Test Suites: 1 failed, 1 passed, 2 total
Tests: 1 failed, 1 passed, 2 total
Snapshots: 0 total
Time: 1.932 s, estimated 3 s
Ran all test suites.
> [email protected] test
> jest
PASS src/demo.test.ts
FAIL src/App.test.tsx
β renders hello message
Test Suites: 1 failed, 1 passed, 2 total
Tests: 1 failed, 1 passed, 2 total
Snapshots: 0 total
Time: 1.637 s, estimated 2 s
Ran all test suites.Our tests are failing because weβve changed the HTML, but you can see from the output that the command has run the tests for theΒ project-oneΒ and then the tests for theΒ project-two, automatically. Before we continue, letβs update the tests to pass:
import '@testing-library/jest-dom'
import { render, screen } from '@testing-library/react'
import { App } from './App'
it('renders hello message', () => {
render(<App />)
expect(screen.getByText('Hello Project One!')).toBeInTheDocument() // This line was updated
})import '@testing-library/jest-dom'
import { render, screen } from '@testing-library/react'
import { App } from './App'
it('renders hello message', () => {
render(<App />)
expect(screen.getByText('Hello Project Two!')).toBeInTheDocument() // This line was updated
})Now we should be able to run the tests and all tests should pass:
npm run test --workspacesβ― npm run test --workspaces
> [email protected] test
> jest
PASS src/demo.test.ts
PASS src/App.test.tsx
Test Suites: 2 passed, 2 total
Tests: 2 passed, 2 total
Snapshots: 0 total
Time: 2.037 s
Ran all test suites.
> [email protected] test
> jest
PASS src/demo.test.ts
PASS src/App.test.tsx
Test Suites: 2 passed, 2 total
Tests: 2 passed, 2 total
Snapshots: 0 total
Time: 1.608 s, estimated 2 s
Ran all test suites. Yeah, everything is working as expected. βοΈΒ Following the same workflow, letβs try to run both front-end projects development servers:
npm run dev --workspacesAfter running the previous command, we can only accessΒ http://localhost:5173Β which is rendering theΒ project-oneΒ React project.
Shouldnβt we be able to access theΒ project-twoΒ as well? Yes, but there is one catch when running scripts with theΒ workspacesΒ option: it only runs one script at a time. Since our development server never stops running unless we manually stop it, it will only runΒ project-one's workspaceΒ devΒ script.
To run bothΒ project-oneΒ andΒ project-twoΒ development servers, we need to run each one of them manually. On our current terminal window, letβs startΒ project-one's development server:
npm run dev -w project-oneThen on a new terminal window, we can startΒ project-two's development server:
npm run dev -w project-twoWe can now accessΒ project-oneΒ in the browser atΒ http://localhost:5173Β andΒ project-twoΒ atΒ http://localhost:5174.


By the end of this step, the file structure shall look like the following:
.
βββ .github
β βββ workflows
β βββ chromatic.yml
β βββ main.yml
β βββ release.yml
βββ .husky
β βββ commit-msg
βββ .vscode
β βββ settings.json
βββ apps
β βββ project-one
β β βββ .storybook
β β βββ __mocks__
β β βββ cypress
β β βββ src
β β βββ .eslintrc.js
β β βββ .gitignore
β β βββ .prettierrc
β β βββ .stylelintignore
β β βββ .stylelintrc.json
β β βββ README.md
β β βββ cypress.config.ts
β β βββ index.html
β β βββ jest.config.ts
β β βββ package.json
β β βββ release.config.js
β β βββ tsconfig.json
β β βββ tsconfig.node.json
β β βββ vite.config.ts
β βββ project-two
β βββ .storybook
β βββ __mocks__
β βββ cypress
β βββ src
β βββ .eslintrc.js
β βββ .gitignore
β βββ .prettierrc
β βββ .stylelintignore
β βββ .stylelintrc.json
β βββ README.md
β βββ cypress.config.ts
β βββ index.html
β βββ jest.config.ts
β βββ package.json
β βββ release.config.js
β βββ tsconfig.json
β βββ tsconfig.node.json
β βββ vite.config.ts
βββ packages
β βββ eslint-config
β β βββ .eslintrc.js
β β βββ .prettierrc
β β βββ index.js
β β βββ jest.js
β β βββ package.json
β βββ prettier-config
β β βββ .prettierrc
β β βββ index.js
β β βββ package.json
β βββ release-config
β β βββ .eslintrc.js
β β βββ .prettierrc
β β βββ index.js
β β βββ package.json
β βββ stylelint-config
β βββ .eslintrc.js
β βββ .prettierrc
β βββ index.js
β βββ package.json
βββ .commitlintrc.json
βββ .gitignore
βββ .nvmrc
βββ package-lock.json
βββ package.jsonStep 4: Set up shared config files
Since weβve duplicated theΒ project-oneΒ for creatingΒ project-twoΒ folder, we ended up with some configuration files that look exactly the same.
Ideally we would reduce code duplication as much as possible. For that, we can take advantage of npm workspaces by creating individual workspaces for our configuration files and then reuse them across the monorepo.
The main configuration files include:
- ESLint configuration;
- Prettier configuration;
- Stylelint configuration;
- semantic-release configuration.
ESLint
Starting with the ESLint, weβll create a new workspace to store its configuration file using the following command:
npm init -w ./packages/eslint-config -yMove theΒ .eslintrc.jsonΒ file fromΒ apps/project-oneΒ and paste it inside the newΒ packages/eslint-configΒ workspace folder and remove the corresponding file fromΒ apps/project-two:
mv apps/project-one/.eslintrc.json packages/eslint-config
rm apps/project-two/.eslintrc.jsonLetβs change the file name fromΒ .eslintrc.jsonΒ toΒ index.jsΒ and update its contents with:
module.exports = {
env: {
browser: true,
es2021: true,
},
extends: [
'eslint:recommended',
'plugin:react/recommended',
'plugin:react-hooks/recommended',
'plugin:react/jsx-runtime',
'plugin:prettier/recommended',
'plugin:@typescript-eslint/recommended',
'plugin:@typescript-eslint/recommended-requiring-type-checking',
'plugin:storybook/recommended',
],
parser: '@typescript-eslint/parser',
parserOptions: {
ecmaFeatures: {
jsx: true,
},
ecmaVersion: 2021,
sourceType: 'module',
tsconfigRootDir: __dirname,
project: ['./apps/**/tsconfig.json', './packages/**/tsconfig.json'],
},
plugins: ['react', '@typescript-eslint'],
rules: {
'prettier/prettier': 'error',
},
settings: {
react: {
version: 'detect',
},
},
};We used most of the configuration and left out the Jest configuration parts. We can create aΒ jest.jsΒ file inside theΒ eslint-configΒ workspace and add the Jest specific configuration options for ESLint:
module.exports = {
env: {
node: true,
},
overrides: [
{
files: ['src/**/*.test.ts', 'src/**/*.test.tsx'],
extends: ['plugin:jest/recommended'],
plugins: ['jest'],
env: {
'jest/globals': true,
},
},
],
};
Now that we have moved the ESLint configuration files, we will move its dependencies as well. Moving all ESLint related npm dependencies into the eslint-config workspace package.json will look something like:
{
"name": "eslint-config",
"version": "1.0.0",
"description": "",
"main": "index.js",
"dependencies": {
"@babel/core": "^7.22.9",
"@typescript-eslint/eslint-plugin": "^6.2.1",
"@typescript-eslint/parser": "^6.2.1",
"eslint": "^8.46.0",
"eslint-config-prettier": "^8.9.0",
"eslint-plugin-cypress": "^2.13.3",
"eslint-plugin-jest": "^27.2.3",
"eslint-plugin-prettier": "^5.0.0",
"eslint-plugin-react": "^7.33.1",
"eslint-plugin-react-hooks": "^4.6.0",
"eslint-plugin-react-refresh": "^0.4.3",
"eslint-plugin-storybook": "^0.6.13"
},
"devDependencies": {},
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC"
}Remember to remove these dependencies from each projectβsΒ package.jsonΒ file.
Before reusing this workspace, letβs first configure it to use its own ESLint config:
echo "module.exports = { extends: ['./index'].map(require.resolve) }" > packages/eslint-config/.eslintrc.jsWith the configuration in place, we can now add a new script to theΒ eslint-configΒ workspaceΒ package.jsonΒ file:
{
"name": "eslint-config",
"version": "1.0.0",
"description": "",
"main": "index.js",
"dependencies": {
"@babel/core": "^7.22.9",
"@typescript-eslint/eslint-plugin": "^6.2.1",
"@typescript-eslint/parser": "^6.2.1",
"eslint": "^8.46.0",
"eslint-config-prettier": "^8.9.0",
"eslint-plugin-cypress": "^2.13.3",
"eslint-plugin-jest": "^27.2.3",
"eslint-plugin-prettier": "^5.0.0",
"eslint-plugin-react": "^7.33.1",
"eslint-plugin-react-hooks": "^4.6.0",
"eslint-plugin-react-refresh": "^0.4.3",
"eslint-plugin-storybook": "^0.6.13"
},
"devDependencies": {},
"scripts": {
"lint:scripts": "eslint ." // This line was updated
},
"keywords": [],
"author": "",
"license": "ISC"
}With ourΒ eslint-configΒ workspace ready to be used, we can now reference it from other workspaces. Letβs start withΒ project-oneΒ by adding a newΒ .eslintrc.jsΒ file with the following content:
module.exports = {
extends: ['eslint-config', 'eslint-config/jest'].map(require.resolve),
parserOptions: {
tsconfigRootDir: __dirname,
project: './tsconfig.json',
},
ignorePatterns: ['cypress/**/*', 'dist', '.eslintrc.js'],
}As you can see from the code snippet above, we are using a package calledΒ eslint-configΒ which matches theΒ eslint-configΒ workspace name.
In order to use it, we need to declare it as a workspace dependency as we would do for any other package on the npm registry.
We can install theΒ eslint-configΒ workspace as a dependency ofΒ project-oneΒ by running:
npm install -D eslint-config -w project-oneLetβs do the same forΒ project-two:
npm install -D eslint-config -w project-twoLast but not least, lets copy theΒ .eslintrc.jsΒ file from project-one workspace intoΒ project-twoΒ and remove the originalΒ .eslintignoreΒ files:
cp apps/project-one/.eslintrc.js apps/project-two
rm apps/project-one/.eslintignore
rm apps/project-two/.eslintignoreAt this point, we have our ESLint configuration being reused on bothΒ project-oneΒ andΒ project-twoΒ workspaces. π
To ensure everything is working as intended, you can check it by runningΒ npm run lint:scripts --workspaces --if-presentΒ (theΒ --if-presentΒ flag ensures that the command gets executed only if the specified script exists in the workspace).
Prettier
Next, we will create a new workspace for the Prettier configuration:
npm init -w ./packages/prettier-config -yFollowing the same approach we used for the ESLint configuration, we can move theΒ apps/project-one/.prettierrcΒ file into the newΒ prettier-configΒ workspace and remove the corresponding file fromΒ apps/project-two:
mv apps/project-one/.prettierrc packages/prettier-config
rm apps/project-two/.prettierrcLetβs rename the moved file fromΒ .prettierrcΒ toΒ index.jsΒ and convert its content into a CommonJS module:
module.exports = {
semi: false,
singleQuote: true,
}Now that we have moved the Prettier configuration file, we will move its dependencies as well (once again, remember to remove these dependencies from each projectβsΒ package.json). Moving all Prettier related npm dependencies into theΒ prettier-configΒ workspaceβsΒ package.jsonΒ will look something like:
{
"name": "prettier-config",
"version": "1.0.0",
"description": "",
"main": "index.js",
"dependencies": { // This object was added
"prettier": "^3.0.0"
},
"devDependencies": {},
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC"
}Now, we can reference this configuration on other workspaces. But first, we need to install theΒ prettier-configΒ workspace package as a dependency:
npm install -D prettier-config -w project-one
npm install -D prettier-config -w project-two
npm install -D prettier-config -w eslint-configLetβs update the Prettier configuration files for all workspaces.
echo "\"prettier-config\"" > apps/project-one/.prettierrc
echo "\"prettier-config\"" > apps/project-two/.prettierrc
echo "\"prettier-config\"" > packages/eslint-config/.prettierrc
echo "\"./index.js\"" > packages/prettier-config/.prettierrcAt this point, we have our Prettier configuration being reused on bothΒ project-one,Β project-two, and remaining workspaces. π
Once again, to ensure everything is working as intended, you can check it by running the same command we used before:Β npm run lint:scripts --workspaces --if-present.
Stylelint
Next, we will create a new workspace for the Stylelint configuration:
npm init -w ./packages/stylelint-config -yFollowing the same approach we used for the Prettier configuration, we can move theΒ apps/project-one/.prettierrcΒ file into the newΒ stylelint-configΒ workspace and remove the corresponding file fromΒ apps/project-two:
mv apps/project-one/.stylelintrc.json packages/stylelint-config
rm apps/project-two/.stylelintrc.jsonNow that we have moved the Stylelint configuration files, we will move its dependencies as well. Moving all Stylelint related npm dependencies into theΒ stylelint-configΒ workspaceΒ package.jsonΒ will look something like:
{
"name": "stylelint-config",
"version": "1.0.0",
"description": "",
"main": "index.js",
"dependencies": {
"stylelint": "^15.10.2", // This line was added
"stylelint-config-recess-order": "^4.3.0", // This line was added
"stylelint-config-standard": "^34.0.0" // This line was added
},
"devDependencies": {},
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC"
}Once again, remember to remove these dependencies fromΒ apps/project-oneΒ andΒ apps/project-two.
Letβs now rename theΒ .stylelintrc.jsonΒ file weβve previously moved toΒ index.jsΒ and convert its content into a CommonJS module:
module.exports = {
extends: ['stylelint-config-standard', 'stylelint-config-recess-order'],
}Letβs also configure ESLint and Prettier for this workspace:
npm install -D eslint-config prettier-config -w stylelint-config
echo "\"prettier-config\"" > packages/stylelint-config/.prettierrc
echo "module.exports = { extends: ['eslint-config'].map(require.resolve) }" > packages/stylelint-config/.eslintrc.jsNow, we can reference this configuration on other workspaces. But first, we need to install theΒ stylelint-configΒ workspace package as a dependency:
npm install -D stylelint-config -w project-one
npm install -D stylelint-config -w project-twoLetβs update the Stylelint configuration files for bothΒ project-oneΒ andΒ project-twoΒ workspaces.
echo "{ \"extends\": \"stylelint-config\" }" > apps/project-one/.stylelintrc.json
echo "{ \"extends\": \"stylelint-config\" }" > apps/project-two/.stylelintrc.jsonAt this point, we have our Stylelint configuration being reused on bothΒ project-oneΒ andΒ project-twoΒ workspaces. π
To ensure everything is working as intended, you can similarly check it by runningΒ npm run lint:styles --workspaces --if-present.
Semantic Release
Next, we will create a new workspace for theΒ semantic-releaseΒ configuration:
npm init -w ./packages/release-config -yFollowing the same approach we used for the Stylelint configuration, we can move theΒ apps/project-one/.releaserc.jsonΒ file into the newΒ release-configΒ workspace and remove the corresponding file fromΒ apps/project-two:
mv apps/project-one/.releaserc.json packages/release-config
rm apps/project-two/.releaserc.jsonNow that we have moved theΒ semantic-releaseΒ configuration file, we will move its dependencies as well. Moving allΒ semantic-releaseΒ related npm dependencies into theΒ release-configΒ workspaceΒ package.jsonΒ will look something like:
{
"name": "release-config",
"version": "1.0.0",
"description": "",
"main": "index.js",
"dependencies": { // This object was added
"semantic-release": "^21.0.7"
},
"devDependencies": {},
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC"
}Remember to remove these dependencies fromΒ apps/project-oneΒ andΒ apps/project-two.
Letβs now rename theΒ .releaserc.jsonΒ file weβve previously moved toΒ index.jsΒ and convert its content into a CommonJS module:
module.exports = {
branches: ['main'],
plugins: [
'@semantic-release/commit-analyzer',
'@semantic-release/release-notes-generator',
'@semantic-release/github',
],
}Letβs also configure ESLint and Prettier for this workspace:
npm install -D eslint-config prettier-config -w release-config
echo "\"prettier-config\"" > packages/release-config/.prettierrc
echo "module.exports = { extends: ['eslint-config'].map(require.resolve) }" > packages/release-config/.eslintrc.jsNow, we can reference this configuration on other workspaces. But first, we need to install theΒ release-configΒ workspace package as a dependency:
npm install -D release-config -w project-one
npm install -D release-config -w project-twoLetβs update theΒ semantic-releaseΒ configuration files for bothΒ project-oneΒ andΒ project-twoΒ workspaces.
echo "module.exports = require('release-config')" > apps/project-one/release.config.js
echo "module.exports = require('release-config')" > apps/project-two/release.config.jsAt this point, we have ourΒ semantic-releaseΒ configuration being reused on bothΒ project-oneΒ andΒ project-twoΒ workspaces. π
By the end of this step, the file structure shall look like the following:
.
βββ .github
β βββ workflows
β βββ chromatic.yml
β βββ main.yml
β βββ release.yml
βββ .husky
β βββ commit-msg
βββ .vscode
β βββ settings.json
βββ apps
β βββ project-one
β β βββ .storybook
β β βββ __mocks__
β β βββ cypress
β β βββ src
β β βββ .eslintrc.js
β β βββ .gitignore
β β βββ .prettierrc
β β βββ .stylelintignore
β β βββ .stylelintrc.json
β β βββ README.md
β β βββ cypress.config.ts
β β βββ index.html
β β βββ jest.config.ts
β β βββ package.json
β β βββ release.config.js
β β βββ tsconfig.json
β β βββ tsconfig.node.json
β β βββ vite.config.ts
β βββ project-two
β βββ .storybook
β βββ __mocks__
β βββ cypress
β βββ src
β βββ .eslintrc.js
β βββ .gitignore
β βββ .prettierrc
β βββ .stylelintignore
β βββ .stylelintrc.json
β βββ README.md
β βββ cypress.config.ts
β βββ index.html
β βββ jest.config.ts
β βββ package.json
β βββ release.config.js
β βββ tsconfig.json
β βββ tsconfig.node.json
β βββ vite.config.ts
βββ packages
β βββ eslint-config
β β βββ .eslintrc.js
β β βββ .prettierrc
β β βββ index.js
β β βββ jest.js
β β βββ package.json
β βββ prettier-config
β β βββ .prettierrc
β β βββ index.js
β β βββ package.json
β βββ release-config
β β βββ .eslintrc.js
β β βββ .prettierrc
β β βββ index.js
β β βββ package.json
β βββ stylelint-config
β βββ .eslintrc.js
β βββ .prettierrc
β βββ index.js
β βββ package.json
βββ .commitlintrc.json
βββ .gitignore
βββ .nvmrc
βββ package-lock.json
βββ package.jsonStep 5: Set up shared design system
In order to set up a shared design system for our monorepo, weβll have to:
- Move Storybook to a separate workspace;
- Namespace stories by workspace.
Currently, we have two instances of Storybook configured: one forΒ project-oneΒ workspace and another forΒ project-two. Letβs take advantage of our monorepo architecture and move Storybook into itβs own workspace.
We can start by creating a new workspace for all Storybook related configurations:
npm init -w ./apps/design-system -yNow, letβs move the configuration files fromΒ project-oneΒ into the new workspace and remove the corresponding files fromΒ project-two:
mv apps/project-one/.storybook apps/design-system
rm -rf apps/project-two/.storybookNext, we can move Storybookβs dependencies fromΒ project-one'sΒ package.jsonΒ file into theΒ design-system's package.json file and remove the corresponding dependencies fromΒ project-two'sΒ package.jsonΒ as well:
{
"name": "design-system",
"version": "1.0.0",
"description": "",
"main": "index.js",
"devDependencies": {
"@storybook/addon-essentials": "^7.2.0", // This line was added
"@storybook/addon-interactions": "^7.2.0", // This line was added
"@storybook/addon-links": "^7.2.0", // This line was added
"@storybook/addon-onboarding": "^1.0.8", // This line was added
"@storybook/blocks": "^7.2.0", // This line was added
"@storybook/react": "^7.2.0", // This line was added
"@storybook/react-vite": "^7.2.0", // This line was added
"@storybook/testing-library": "^0.2.0", // This line was added
"storybook": "^7.2.0" // This line was added
},
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC"
}Letβs reuse our ESLint and Prettier configurations as well:
npm install -D eslint-config -w design-system
npm install -D prettier-config -w design-system
echo "\"prettier-config\"" > apps/design-system/.prettierrcCreate aΒ .eslintrc.jsΒ file on theΒ design-systemΒ workspace with the following content:
module.exports = {
extends: ['eslint-config'].map(require.resolve),
ignorePatterns: ['!.storybook'],
}Letβs remove bothΒ storybookΒ and build-storybook npm scripts fromΒ project-oneΒ andΒ project-twoΒ workspaces and add them to theΒ design-systemΒ workspace like:
{
"name": "design-system",
"version": "1.0.0",
"description": "",
"main": "index.js",
"devDependencies": {
"@storybook/addon-essentials": "^7.2.0",
"@storybook/addon-interactions": "^7.2.0",
"@storybook/addon-links": "^7.2.0",
"@storybook/addon-onboarding": "^1.0.8",
"@storybook/blocks": "^7.2.0",
"@storybook/react": "^7.2.0",
"@storybook/react-vite": "^7.2.0",
"@storybook/testing-library": "^0.2.0",
"eslint-config": "^1.0.0",
"prettier-config": "^1.0.0",
"storybook": "^7.2.0"
},
"scripts": {
"dev": "storybook dev -p 6006", // This line was added
"build": "storybook build" // This line was added
},
"keywords": [],
"author": "",
"license": "ISC"
}With all of these updates, letβs start the Storybook development server by running the following command:
npm run dev -w apps/design-systemWe get the following error:
[vite] Internal server error: Failed to resolve import "../src/index.css" from ".storybook/preview.js". Does the file exist?We are trying to import aΒ index.cssΒ file that does not exist on that specific path anymore because our monorepo now has a difference structure. For now, letβs remove that import statement and try to run the Storybook development server again.

Our current Storybook configuration is based on a single project folder structure but now we have multiple projects inside our monorepo.
We need to update the Storybook configuration to pick up stories from bothΒ project-oneΒ andΒ project-twoΒ workspaces.
This can be done by updating the stories configuration on theΒ apps/design-system/.storybook/main.tsΒ file:
import type { StorybookConfig } from '@storybook/react-vite'
const config: StorybookConfig = {
stories: ['../../*/src/**/*.stories.@(js|jsx|ts|tsx)'], // This line was updated
addons: [
'@storybook/addon-links',
'@storybook/addon-essentials',
'@storybook/addon-onboarding',
'@storybook/addon-interactions',
],
framework: {
name: '@storybook/react-vite',
options: {},
},
docs: {
autodocs: 'tag',
},
}
export default configWe can start the Storybook development server again and see the following error:
π¨ Unable to index ../project-one/src/App.stories.tsx,../project-two/src/App.stories.tsx:
Error: Duplicate stories with id: components-app--defaultYou can see from the error above that Storybook is trying to index the App story fromΒ project-one andΒ project-twoΒ and since both have the same name, Storybook is showing theΒ Duplicate storiesΒ error.
In order to be able to render both stories on Storybook, we can simply prefix the story names with the project they belong to. For example, the stories for the App component ofΒ project-oneΒ have the main titleΒ Components/AppΒ and we can prefix it withΒ Project OneΒ to create a new hierarchy on the left sidebar menu.
Letβs update theΒ App.stories.tsxΒ file fromΒ project-one:
import { Meta, StoryObj } from '@storybook/react'
import { App } from './App'
const meta = {
title: 'Project One/Components/App', // This line was updated
component: App,
} satisfies Meta<typeof App>
export default meta
type Story = StoryObj<typeof meta>
export const Default = {} satisfies StoryAnd now theΒ App.stories.tsxΒ file fromΒ project-two:
import { Meta, StoryObj } from '@storybook/react'
import { App } from './App'
const meta = {
title: 'Project Two/Components/App', // This line was updated
component: App,
} satisfies Meta<typeof App>
export default meta
type Story = StoryObj<typeof meta>
export const Default = {} satisfies StoryNow after restarting the Storybook development server we should see theΒ project-oneΒ App story being rendered by default:

The left sidebar menu now show stories forΒ Project OneΒ and stories forΒ Project TwoΒ separately.
Now, we can import the global styles to render the correct font. Since we have the sameΒ index.cssΒ file on both projects, we can move it to aΒ sharedΒ workspace and then reuse it on both projects.
Letβs start by creating a new workspace calledΒ sharedΒ inside theΒ packagesΒ folder:
npm init -w ./packages/shared -yTo keep the monorepo consistent, create aΒ srcΒ folder inside the newΒ sharedΒ workspace:
mkdir packages/shared/srcWe can now move theΒ index.cssΒ file into the folder we just created and remove theΒ index.cssΒ file fromΒ project-two:
mv apps/project-one/src/index.css packages/shared/src/
rm apps/project-two/src/index.cssNow, to reuse theΒ index.cssΒ file from the shared workspace into bothΒ project-one,Β project-two, andΒ design-systemΒ we will install theΒ sharedΒ workspace as a dependency on each of them:
npm install shared -w apps/project-one
npm install shared -w apps/project-two
npm install shared -w apps/design-systemImport theΒ index.cssΒ file the fromΒ sharedΒ into Storybook by updating theΒ apps/design-sytem/storybook/preview.jsΒ file:
import type { Preview } from '@storybook/react'
import 'shared/src/index.css' // This line was added
const preview: Preview = {
parameters: {
actions: { argTypesRegex: '^on[A-Z].*' },
controls: {
matchers: {
color: /(background|color)$/i,
date: /Date$/,
},
},
layout: 'fullscreen',
},
}
export default previewUpdate the import on bothΒ project-one's andΒ project-two'sΒ main.tsxΒ file:
import React from 'react'
import ReactDOM from 'react-dom/client'
import 'shared/src/index.css' // This line was updated
import { App } from './App'
ReactDOM.createRoot(document.getElementById('root')!).render(
<React.StrictMode>
<App />
</React.StrictMode>,
)We should now see the correct font being used in Storybook:

By the end of this step, the file structure shall look like the following:
.
βββ .github
β βββ workflows
β βββ chromatic.yml
β βββ main.yml
β βββ release.yml
βββ .husky
β βββ commit-msg
βββ .vscode
β βββ settings.json
βββ apps
β βββ design-system
β β βββ .storybook
β β βββ .eslintrc.js
β β βββ .prettierrc
β β βββ package.json
β βββ project-one
β β βββ __mocks__
β β βββ cypress
β β βββ src
β β βββ .eslintrc.js
β β βββ .gitignore
β β βββ .prettierrc
β β βββ .stylelintignore
β β βββ .stylelintrc.json
β β βββ README.md
β β βββ cypress.config.ts
β β βββ index.html
β β βββ jest.config.ts
β β βββ package.json
β β βββ release.config.js
β β βββ tsconfig.json
β β βββ tsconfig.node.json
β β βββ vite.config.ts
β βββ project-two
β βββ .storybook
β βββ __mocks__
β βββ cypress
β βββ src
β βββ .eslintrc.js
β βββ .gitignore
β βββ .prettierrc
β βββ .stylelintignore
β βββ .stylelintrc.json
β βββ README.md
β βββ cypress.config.ts
β βββ index.html
β βββ jest.config.ts
β βββ package.json
β βββ release.config.js
β βββ tsconfig.json
β βββ tsconfig.node.json
β βββ vite.config.ts
βββ packages
β βββ eslint-config
β β βββ .eslintrc.js
β β βββ .prettierrc
β β βββ index.js
β β βββ jest.js
β β βββ package.json
β βββ prettier-config
β β βββ .prettierrc
β β βββ index.js
β β βββ package.json
β βββ release-config
β β βββ .eslintrc.js
β β βββ .prettierrc
β β βββ index.js
β β βββ package.json
β βββ shared
β β βββ src
β β βββ package.json
β βββ stylelint-config
β βββ .eslintrc.js
β βββ .prettierrc
β βββ index.js
β βββ package.json
βββ .commitlintrc.json
βββ .gitignore
βββ .nvmrc
βββ package-lock.json
βββ package.jsonStep 6: Set up Turborepo
Currently, to run bothΒ project-oneΒ andΒ project-twoΒ at the same time we need to open two different terminal windows and run theΒ devΒ command for each project manually as we discussed above on the βSet up a couple of front-end projectsβ section.
Thatβs where Turborepo comes in to save the day. Turborepo is a smart build system for JavaScript/TypeScript monorepos. Unlike other build systems, Turborepo is designed to be incrementally adopted, so you can add it to most codebases in a few minutes.
Letβs follow the TurborepoβsΒ docs (opens in a new tab)Β to add it to our monorepo π
Install turbo:
npm install turbo -DCreateΒ turbo.json: file with aΒ devΒ pipeline:
{
"$schema": "https://turborepo.org/schema.json",
"pipeline": {
"dev": {
"cache": false
},
}
}EditΒ .gitignore:
node_modules
.DS_Store
dist
dist-ssr
*.local
storybook-static
# The next line was added
.turboCreate newΒ devΒ script inside the rootΒ package.jsonΒ file:
{
"name": "demo-monorepo",
"version": "1.0.0",
"description": "",
"main": "index.js",
"workspaces": [
"apps/*",
"packages/*"
],
"scripts": {
"prepare": "husky install",
"dev": "turbo dev --parallel --continue" // This line was added
},
"devDependencies": {
"@commitlint/cli": "^17.6.7",
"@commitlint/config-conventional": "^17.6.7",
"husky": "^8.0.3",
"turbo": "^1.10.12"
},
"keywords": [],
"author": "",
"license": "ISC"
}Now we canΒ run npm runΒ dev and Turborepo will run theΒ devΒ script on all workspaces that have aΒ devΒ configured. This way we can start the development servers for Storybook (design system), project one, and project two in parallel. If we donβt want to run on all workspaces, we can use theΒ filter (opens in a new tab)Β option to target the ones we want.
Letβs create a pipeline to build our projects as well. We will update theΒ turbo.jsonΒ file as follows:
{
"$schema": "https://turborepo.org/schema.json",
"pipeline": {
"dev": {
"cache": false
},
"build": { // This object was added
"dependsOn": ["^build"],
"outputs": ["dist/**", "storybook-static/**"]
}
}
}This change has a couple different properties likeΒ dependsOnΒ andΒ outputs.Β Turborepo is smart and creates a dependency graph in order to run scripts in the most optimized way.
We tell Turborepo that when itβs time to build a workspace, it should build its dependencies first.
This is configured by theΒ dependsOnΒ property. TheΒ outputsΒ property tells Turborepo what to cache after the script successfully finishes, which in our case is the output folder of Vite build command and the output folder of Storybook build command. This way, Turborepo doesnβt do the same work twice. You can read more about Turborepoβs caching on theΒ docs (opens in a new tab).
Letβs add a newΒ buildΒ script to our rootΒ package.jsonΒ file:
{
"name": "demo-monorepo",
"version": "1.0.0",
"description": "",
"main": "index.js",
"workspaces": [
"apps/*",
"packages/*"
],
"scripts": {
"prepare": "husky install",
"dev": "turbo dev --parallel --continue",
"build": "turbo build" // This line was added
},
"devDependencies": {
"@commitlint/cli": "^17.6.7",
"@commitlint/config-conventional": "^17.6.7",
"husky": "^8.0.3",
"turbo": "^1.10.12"
},
"keywords": [],
"author": "",
"license": "ISC"
}The first time weΒ run npm runΒ build it will take some time to build everything. The second time we run the script, without making any changes, will finish almost instantaneously.
First time Turborepo stats when running npm run build:
Tasks: 3 successful, 3 total
Cached: 0 cached, 3 total
Time: 8.067sSecond time Turborepo stats when running npm run build:
Tasks: 3 successful, 3 total
Cached: 3 cached, 3 total
Time: 128ms >>> FULL TURBOAs you can see, in the second time it took less than 150 milliseconds to finish the build command. When we take advantage of Turborepoβs cache, we will see aΒ >>> FULL TURBOΒ message on the output.
We can add another pipeline for running tests with Turborepo as well. First, we update theΒ turbo.jsonΒ file:
{
"$schema": "https://turborepo.org/schema.json",
"pipeline": {
"dev": {
"cache": false
},
"build": {
"dependsOn": ["^build"],
"outputs": ["dist/**", "storybook-static/**"]
},
"test": { // This object was added
"dependsOn": ["^build"],
"outputs": [],
"inputs": ["src/**/*.tsx", "src/**/*.ts"]
}
}
}Letβs add a newΒ testΒ script to our rootΒ package.jsonΒ file:
{
"name": "demo-monorepo",
"version": "1.0.0",
"description": "",
"main": "index.js",
"workspaces": [
"apps/*",
"packages/*"
],
"scripts": {
"prepare": "husky install",
"dev": "turbo dev --parallel --continue",
"build": "turbo build",
"test": "turbo test" // This line was added
},
"devDependencies": {
"@commitlint/cli": "^17.6.7",
"@commitlint/config-conventional": "^17.6.7",
"husky": "^8.0.3",
"turbo": "^1.10.12"
},
"keywords": [],
"author": "",
"license": "ISC"
}If weΒ run npm runΒ test it will show an error like the following:
command (/Users/ruisaraiva/.../demo-monorepo/packages/shared) npm run test exited (1)
command (/Users/ruisaraiva/.../demo-monorepo/packages/stylelint-config) npm run test exited (1)
Tasks: 0 successful, 2 total
Cached: 0 cached, 2 total
Time: 794ms
ERROR run failed: command exited (1)This happens because our workspaces inside theΒ packagesΒ folder have aΒ testΒ script that exits with the error above.
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1" // Remove this line
},We can simply remove these placeholderΒ testΒ scripts andΒ run npm runΒ test again where the output should be something like:
β― npm run test
> [email protected] test
> turbo test
β’ Packages in scope: design-system, eslint-config, prettier-config, project-one, project-two, release-config, shared, stylelint-config
β’ Running test in 8 packages
β’ Remote caching disabled
project-two:test: cache miss, executing 6f5ffb2848ba9d11
project-one:test: cache miss, executing 44571033308de93b
project-one:test:
project-one:test: > [email protected] test
project-one:test: > jest
project-one:test:
project-two:test:
project-two:test: > [email protected] test
project-two:test: > jest
project-two:test:
project-one:test: PASS src/App.test.tsx
project-two:test: PASS src/App.test.tsx
project-two:test: PASS src/demo.test.ts
project-one:test: PASS src/demo.test.ts
project-two:test:
project-two:test: Test Suites: 2 passed, 2 total
project-two:test: Tests: 2 passed, 2 total
project-two:test: Snapshots: 0 total
project-two:test: Time: 0.787 s, estimated 1 s
project-two:test: Ran all test suites.
project-one:test:
project-one:test: Test Suites: 2 passed, 2 total
project-one:test: Tests: 2 passed, 2 total
project-one:test: Snapshots: 0 total
project-one:test: Time: 0.787 s, estimated 1 s
project-one:test: Ran all test suites.
Tasks: 2 successful, 2 total
Cached: 0 cached, 2 total
Time: 2.946sNow if you run the command again, you should see theΒ >>> FULL TURBOΒ text in the output as well.
Last but not least, we can create another pipeline for theΒ lintΒ script. First, we update theΒ turbo.jsonΒ file:
{
"$schema": "https://turborepo.org/schema.json",
"pipeline": {
"dev": {
"cache": false
},
"build": {
"dependsOn": ["^build"],
"outputs": ["dist/**", "storybook-static/**"]
},
"test": {
"dependsOn": ["^build"],
"outputs": [],
"inputs": ["src/**/*.tsx", "src/**/*.ts"]
},
"lint": { // This object was added
"dependsOn": ["^build"],
"outputs": []
}
}
}Letβs add a newΒ lintΒ script to our rootΒ package.jsonΒ file:
{
"name": "demo-monorepo",
"version": "1.0.0",
"description": "",
"main": "index.js",
"workspaces": [
"apps/*",
"packages/*"
],
"scripts": {
"prepare": "husky install",
"dev": "turbo dev --parallel --continue",
"build": "turbo build",
"test": "turbo test",
"lint": "turbo lint" // This line was added
},
"devDependencies": {
"@commitlint/cli": "^17.6.7",
"@commitlint/config-conventional": "^17.6.7",
"husky": "^8.0.3",
"turbo": "^1.10.12"
},
"keywords": [],
"author": "",
"license": "ISC"
}If we run npm runΒ lint it will show the following:
β― npm run lint
> [email protected] lint
> turbo lint
β’ Packages in scope: design-system, eslint-config, prettier-config, project-one, project-two, release-config, shared, stylelint-config
β’ Running lint in 8 packages
β’ Remote caching disabled
No tasks were executed as part of this run.
Tasks: 0 successful, 0 total
Cached: 0 cached, 0 total
Time: 146msAs you can screen from the output, there are no workspaces with aΒ lintΒ script available. BothΒ project-oneΒ andΒ project-twoΒ have aΒ lint:scriptsΒ and aΒ lint:stylesΒ script.
We can create a newΒ lintΒ script that simply calls both scripts. So, lets add a new script to bothΒ project-oneΒ andΒ project-twoΒ projectsβΒ package.jsonΒ file and update theΒ lint:scriptsΒ script from both projects to enable a more verbose output of ESLint in order for Turborepo to cache it properly, usingΒ TIMING=1:
{
"name": "project-one",
"version": "0.0.0",
"engines": {
"node": ">=18.17.0",
"npm": ">=9.0.0"
},
"scripts": {
"dev": "vite",
"build": "vite build",
"serve": "vite preview",
"lint": "npm run lint:scripts && npm run lint:styles", // This line was added
"lint:scripts": "TIMING=1 eslint --ext .ts,.tsx .", // This line was updated
"lint:styles": "stylelint \"src/**/*.css\"",
"test": "jest",
"cypress:open": "cypress open"
},
// ...
}
Now if we runΒ npm run lintΒ again, it should output something like:
β― npm run lint
> [email protected] lint
> turbo lint
β’ Packages in scope: design-system, eslint-config, prettier-config, project-one, project-two, release-config, shared, stylelint-config
β’ Running lint in 8 packages
β’ Remote caching disabled
project-two:lint: cache miss, executing c1987b986258151d
project-one:lint: cache miss, executing 31c5a2d919a903ba
project-one:lint:
project-one:lint: > [email protected] lint
project-one:lint: > npm run lint:scripts && npm run lint:styles
project-one:lint:
project-two:lint:
project-two:lint: > [email protected] lint
project-two:lint: > npm run lint:scripts && npm run lint:styles
project-two:lint:
project-one:lint:
project-one:lint: > [email protected] lint:scripts
project-one:lint: > TIMING=1 eslint --ext .ts,.tsx .
project-one:lint:
project-two:lint:
project-two:lint: > [email protected] lint:scripts
project-two:lint: > TIMING=1 eslint --ext .ts,.tsx .
project-two:lint:
project-one:lint: Rule | Time (ms) | Relative
project-one:lint: :---------------------------------------|----------:|--------:
project-one:lint: prettier/prettier | 205.426 | 52.1%
project-one:lint: @typescript-eslint/no-misused-promises | 85.829 | 21.8%
project-one:lint: @typescript-eslint/no-floating-promises | 39.324 | 10.0%
project-one:lint: @typescript-eslint/no-unsafe-assignment | 14.449 | 3.7%
project-one:lint: @typescript-eslint/no-unsafe-argument | 14.211 | 3.6%
project-one:lint: react/display-name | 7.677 | 1.9%
project-one:lint: @typescript-eslint/no-unused-vars | 4.060 | 1.0%
project-one:lint: react/no-direct-mutation-state | 1.607 | 0.4%
project-one:lint: @typescript-eslint/no-unsafe-return | 1.424 | 0.4%
project-one:lint: react/no-unknown-property | 1.221 | 0.3%
project-two:lint: Rule | Time (ms) | Relative
project-two:lint: :---------------------------------------|----------:|--------:
project-two:lint: prettier/prettier | 216.367 | 53.2%
project-two:lint: @typescript-eslint/no-misused-promises | 85.785 | 21.1%
project-two:lint: @typescript-eslint/no-floating-promises | 38.538 | 9.5%
project-two:lint: @typescript-eslint/no-unsafe-argument | 14.407 | 3.5%
project-two:lint: @typescript-eslint/no-unsafe-assignment | 14.117 | 3.5%
project-two:lint: react/display-name | 7.757 | 1.9%
project-two:lint: @typescript-eslint/no-unused-vars | 5.955 | 1.5%
project-two:lint: @typescript-eslint/no-unsafe-return | 1.787 | 0.4%
project-two:lint: react/no-direct-mutation-state | 1.694 | 0.4%
project-two:lint: react/no-unknown-property | 1.288 | 0.3%
project-one:lint:
project-one:lint: > [email protected] lint:styles
project-one:lint: > stylelint "src/**/*.css"
project-one:lint:
project-two:lint:
project-two:lint: > [email protected] lint:styles
project-two:lint: > stylelint "src/**/*.css"
project-two:lint:
Tasks: 2 successful, 2 total
Cached: 0 cached, 2 total
Time: 4.902sWe now have theΒ dev,Β build,Β test, andΒ lintΒ pipelines configured! π By the end of this step, the file structure shall look like the following:
.
βββ .github
β βββ workflows
β βββ chromatic.yml
β βββ main.yml
β βββ release.yml
βββ .husky
β βββ commit-msg
βββ .vscode
β βββ settings.json
βββ apps
β βββ design-system
β β βββ .storybook
β β βββ .eslintrc.js
β β βββ .prettierrc
β β βββ package.json
β βββ project-one
β β βββ __mocks__
β β βββ cypress
β β βββ src
β β βββ .eslintrc.js
β β βββ .gitignore
β β βββ .prettierrc
β β βββ .stylelintignore
β β βββ .stylelintrc.json
β β βββ README.md
β β βββ cypress.config.ts
β β βββ index.html
β β βββ jest.config.ts
β β βββ package.json
β β βββ release.config.js
β β βββ tsconfig.json
β β βββ tsconfig.node.json
β β βββ vite.config.ts
β βββ project-two
β βββ .storybook
β βββ __mocks__
β βββ cypress
β βββ src
β βββ .eslintrc.js
β βββ .gitignore
β βββ .prettierrc
β βββ .stylelintignore
β βββ .stylelintrc.json
β βββ README.md
β βββ cypress.config.ts
β βββ index.html
β βββ jest.config.ts
β βββ package.json
β βββ release.config.js
β βββ tsconfig.json
β βββ tsconfig.node.json
β βββ vite.config.ts
βββ packages
β βββ eslint-config
β β βββ .eslintrc.js
β β βββ .prettierrc
β β βββ index.js
β β βββ jest.js
β β βββ package.json
β βββ prettier-config
β β βββ .prettierrc
β β βββ index.js
β β βββ package.json
β βββ release-config
β β βββ .eslintrc.js
β β βββ .prettierrc
β β βββ index.js
β β βββ package.json
β βββ shared
β β βββ src
β β βββ package.json
β βββ stylelint-config
β βββ .eslintrc.js
β βββ .prettierrc
β βββ index.js
β βββ package.json
βββ .commitlintrc.json
βββ .gitignore
βββ .nvmrc
βββ package-lock.json
βββ package.json
βββ turbo.jsonStep 7: Set CI/CD workflows
Our CI/CD workflows need to be updated in order to run for bothΒ project-one,Β project-twoΒ andΒ design-systemΒ projects.
Lint and test pipelines
Currently, we have a main workflow with a single job, calledΒ lint-and-test. This works great for a simple repo, but not for a monorepo.
Since we have aΒ lintΒ script on most workspaces and aΒ testΒ script only on a couple workspaces, we can split theΒ lint-and-testΒ job into multiple ones so we have greater flexibility.
To do that, we will update theΒ main.ymlΒ workflow file to look like the following:
name: "Main"
on: pull_request
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version-file: ".nvmrc"
cache: "npm"
- name: Install dependencies
run: npm ci
- name: Run Linters
run: npm run lint
test:
runs-on: ubuntu-latest
strategy:
matrix:
project: [project-one, project-two]
fail-fast: false
steps:
- uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version-file: ".nvmrc"
cache: "npm"
- name: Install dependencies
run: npm ci
- name: Run Tests
run: npm test -- --filter="{${{ matrix.project }}}..."
env:
CI: true
- name: Install Cypress dependencies
uses: cypress-io/github-action@v5
with:
# just perform install
runTests: false
- name: Run Cypress
uses: cypress-io/github-action@v5
with:
build: npm run build
start: npm run serve -- --port=5173
wait-on: "http://127.0.0.1:5173"
browser: chrome
# we have already installed all dependencies above
install: false
working-directory: apps/${{ matrix.project }}You can see from the code above that we now haveΒ lintΒ andΒ testΒ jobs. TheΒ lintΒ job will run theΒ lintΒ script on all workspaces. The test job is a bit different, as we added aΒ matrix strategy (opens in a new tab)Β that lets us use variables in a single job definition to automatically create multiple job runs based on the combinations of the variables.
We added a variable calledΒ projectΒ as an array of project names. This lets us create two job runs, each one with its ownΒ projectΒ variable.
We then use theΒ matrix.projectΒ variable to filter the workspaces for which we want to run the tests.
Release pipeline
With theΒ lintΒ andΒ testΒ CI/CD pipelines updates, letβs move on to the release pipeline. We have aΒ semantic-releaseΒ configuration for bothΒ project-oneΒ andΒ project-twoΒ workspaces.
TheΒ semantic-releaseΒ package was created to be used on a simple repo, not on monorepos. In order to use semantic-release within a monorepo, we need to install theΒ semantic-release-monorepoΒ plugin first:
npm install -D semantic-release-monorepo -w project-one
npm install -D semantic-release-monorepo -w project-twoNow, we are going to create a newΒ releaseΒ script inside bothΒ project-oneΒ andΒ project-twoΒ workspaces, which executes theΒ semantic-release -e semantic-release-monorepoΒ command:
{
"name": "project-one",
"version": "0.0.0",
"engines": {
"node": ">=18.17.0",
"npm": ">=9.0.0"
},
"scripts": {
"dev": "vite --host",
"build": "vite build",
"serve": "vite preview --host",
"lint": "npm run lint:scripts && npm run lint:styles",
"lint:scripts": "TIMING=1 eslint --ext .ts,.tsx .",
"lint:styles": "stylelint \"src/**/*.css\"",
"test": "jest",
"cypress:open": "cypress open",
"release": "semantic-release -e semantic-release-monorepo" // This line was added
},
// ...
}In order to have different Git tags forΒ project-oneΒ andΒ project-twoΒ workspaces, you need to update theΒ semantic-releaseΒ configurations accordingly (release.config.js):
const sharedConfig = require('release-config')
const { name } = require('./package.json')
module.exports = {
...sharedConfig,
tagFormat: `${name}@\${version}`,
}With this update, new release tags will be formatted asΒ {package-name}@vX.X.XΒ depending on the changes and workspaces that they affect.
You can now add a new pipeline to Turborepo by updating theΒ turbo.jsonΒ file:
{
"$schema": "https://turborepo.org/schema.json",
"pipeline": {
"dev": {
"cache": false
},
"build": {
"dependsOn": ["^build"],
"outputs": ["dist/**", "storybook-static/**"]
},
"test": {
"dependsOn": ["^build"],
"outputs": [],
"inputs": ["src/**/*.tsx", "src/**/*.ts"]
},
"lint": {
"dependsOn": ["^build"],
"outputs": []
},
"release": { // This object was added
"cache": false
}
}
}Letβs create aΒ releaseΒ script on the root of the monorepo to run the TurborepoΒ releaseΒ pipeline:
{
"name": "demo-monorepo",
"version": "1.0.0",
"description": "",
"main": "index.js",
"workspaces": [
"apps/*",
"packages/*"
],
"scripts": {
"prepare": "husky install",
"dev": "turbo dev --parallel --continue",
"build": "turbo build",
"test": "turbo test",
"lint": "turbo lint",
"release": "turbo release --concurrency=1" // This line was added
},
"devDependencies": {
"@commitlint/cli": "^17.6.7",
"@commitlint/config-conventional": "^17.6.7",
"husky": "^8.0.3",
"turbo": "^1.10.12"
},
"keywords": [],
"author": "",
"license": "ISC"
}With everything ready to be used, letβs update theΒ release.ymlΒ workflow file to use the newΒ releaseΒ Turborepo pipeline:
name: "Release"
on:
push:
branches:
- main
jobs:
semantic-release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version-file: ".nvmrc"
cache: "npm"
- name: Install dependencies
run: npm ci
- name: Release a new version
# π This line was updated
run: npm run release
env:
GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"Chromatic pipeline
For the Chromatic pipeline, we need to build any child dependencies of theΒ design-systemΒ workspace and run the Storybook build inside theΒ apps/design-systemΒ folder. For that, update theΒ chromatic.ymlΒ file to the following:
name: "Chromatic"
on: push
jobs:
chromatic-deployment:
runs-on: ubuntu-latest
steps:
- name: Checkout repo
uses: actions/checkout@v3
with:
fetch-depth: 50
- name: Use Node.js
uses: actions/setup-node@v3
with:
node-version-file: ".nvmrc"
cache: "npm"
- name: Install dependencies
run: npm ci
# π This step was added
- name: Build Storybook dependencies
run: npm run build -- --filter="design-system^..."
- name: Publish to Chromatic
uses: chromaui/action@v1
with:
# π This line was added
workingDir: apps/design-system
# π This line was added
buildScriptName: build
token: ${{ secrets.GITHUB_TOKEN }}
projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
autoAcceptChanges: ${{ github.ref == 'refs/heads/main' }}
exitOnceUploaded: true
skip: "dependabot/**"Once youβre done, the file structure shall look like the following:
.
βββ .github
β βββ workflows
β βββ chromatic.yml
β βββ main.yml
β βββ release.yml
βββ .husky
β βββ commit-msg
βββ .vscode
β βββ settings.json
βββ apps
β βββ design-system
β β βββ .storybook
β β βββ .eslintrc.js
β β βββ .prettierrc
β β βββ package.json
β βββ project-one
β β βββ __mocks__
β β βββ cypress
β β βββ src
β β βββ .eslintrc.js
β β βββ .gitignore
β β βββ .prettierrc
β β βββ .stylelintignore
β β βββ .stylelintrc.json
β β βββ README.md
β β βββ cypress.config.ts
β β βββ index.html
β β βββ jest.config.ts
β β βββ package.json
β β βββ release.config.js
β β βββ tsconfig.json
β β βββ tsconfig.node.json
β β βββ vite.config.ts
β βββ project-two
β βββ .storybook
β βββ __mocks__
β βββ cypress
β βββ src
β βββ .eslintrc.js
β βββ .gitignore
β βββ .prettierrc
β βββ .stylelintignore
β βββ .stylelintrc.json
β βββ README.md
β βββ cypress.config.ts
β βββ index.html
β βββ jest.config.ts
β βββ package.json
β βββ release.config.js
β βββ tsconfig.json
β βββ tsconfig.node.json
β βββ vite.config.ts
βββ packages
β βββ eslint-config
β β βββ .eslintrc.js
β β βββ .prettierrc
β β βββ index.js
β β βββ jest.js
β β βββ package.json
β βββ prettier-config
β β βββ .prettierrc
β β βββ index.js
β β βββ package.json
β βββ release-config
β β βββ .eslintrc.js
β β βββ .prettierrc
β β βββ index.js
β β βββ package.json
β βββ shared
β β βββ src
β β βββ package.json
β βββ stylelint-config
β βββ .eslintrc.js
β βββ .prettierrc
β βββ index.js
β βββ package.json
βββ .commitlintrc.json
βββ .gitignore
βββ .nvmrc
βββ package-lock.json
βββ package.json
βββ turbo.jsonAnd it's done!Β
Managing multiple front-end projects using a monorepo can be a game-changer for development teams that are looking for improved efficiency, consistency, and scalability. By consolidating all related codebases under a single repository, developers can streamline their workflows, simplify dependency management, and promote code reusability across projects.
Ultimately, adopting a monorepo for Front-End projects empowers teams to take full control of their development processes, enabling them to innovate faster, deliver more reliable products, and maintain long-term scalability.
Embrace the monorepo approach, and watch as your development efforts become more efficient, collaborative, and future-proof!Β
Meet Pixelmatters' unique approach to work.
Written by

Rui Saraiva
Principal Engineer