React Monorepo Setup Tutorial with pnpm and Vite: React project + UI, Utils

Last evening, I found an error on the docs of chakra-ui, which I have recently been using on my personal project. I forked the project and I tried to find the error. The project was set up as a monorepo and it looked very intriguing because I wanted to try to set up a monorepo someday. I even wrote it down on my todo list, but I didn't have an opportunity where I needed to set up a monorepo. Anyway, I didn't find the error and went to bed. I woke up a couple of hours late. I was supposed to sleep. It was three in the morning. But I couldn't fall asleep again from thinking of the mono repo structure. After some minutes, I just got out of bed and started to work on setting up the mono repo using pnpm.

What I wanted to implement are the following:

• Creating two packages for UI components and Util functions that can be used from a separate React project.
• Creating a React project and using the two packages in the React project.
• Running testing for each project.
• Installing all dependencies, running the dev server, and testing for each workspace from the root directory.

As implementing those things is the main goal for this mono repo, common configurations, package.json, and small details were not considered.

There might be many things you should consider in the real world, and that could be also different depending on various factors.

I will be writing this post following the steps:

1. Root project
2. website
3. packages/utils
4. packages/ui
5. Using packages on the website
6. Wrap up

Additionally, I have recorded the process and uploaded it on my youtube channel. Since I started this channel to practice speaking English, considering my English proficiency, some I said might not sound unnatural. But still, I suggest watching the video if you would like to see the process in more detail. It's a very pure no-edit video where you can see all I did to set up a mono repo, like what I searched for, what problems I encountered, and how I solved them from scratch.

Okay, let's get started!

Root project

1. Create a folder and initialize pnpm

> mkdir monorepo
> cd monorepo
> pnpm init

2. Create pnpm-workspace.yaml file and set up the workspace paths

packages:
  - 'packages/*'
  - 'website'

website

1. Set up a React project using Vite

> pnpm create vite

2. Install packages

> pnpm install

Install the dependencies from the root directory.

It will detect the workspaces and create a pnpm-lock.yaml in the root directory. In the lock file, dependencies are written under the package name website.

3. Add a script to run the dev server from the root directory

//...
"scripts": {
  "dev": "pnpm --filter website dev"
},
//...

Add a script into the package.json file of the root directory.

The --filter option allows us to execute a script under the website workspace.

4. Run the dev command to see if the dev server is sucessfully started with the command

> pnpm run dev

Open the http://localhost:5173, and you will see the initial page.

packages/utils

1. Create the utils directory under the packages.

> mkdir -p packages/utils

2. Create package.json

{
  "name": "@mono/utils",
  "version": "0.0.1",
  "main": "src/index.ts",
  "scripts": {
  }
}

The package has been renamed with @mono/utils and set the main file path.

3. Set up typescript environment

> pnpm install -D typescript --filter utils
> pnpm exec tsc --init

4. Create a function in a file

Don't forget to export the function from the index.ts.

5. Set up vitest and write test code

>  pnpm install -D vitest --filter utils

[packages/utils/src/calc.test.ts]

import { test, expect } from 'vitest';
import { add } from './calc';

test('add(10, 20) should return 30', () => {
  expect(add(10, 20)).toBe(30);
});

6. Add a test script in the package.json files.

[packages/utils/package.json]

{
//...
  "scripts": {
    "test": "vitest run"
  },
//...
}

[package.json]

{
//...
  "scripts": {
    "dev": "pnpm --filter website dev",
    "test:all": "pnpm -r test"
  },
//...
}

The -r option will execute the test command for each workspace.

7. Test

> pnpm run test:all

packages/ui

1. Set up the ui package using Vite.

> cd packages
> pnpm create vite

As the ui package was created by Vite, unnecessary files that you may not need to implement UI components will come with it together. I used Vite to set it up quickly though, you can set the ui package up by yourself. That would be more appropriate as you can install specific dependencies and configures you need.

2. Delete unnecessary files

• All the files under the src dir
• index.html
• public dir

3. Install dependencies

> pnpm install

4. Create a component

[packages/ui/src/Button.tsx]

import { ComponentProps } from "react";

const Button = (props: ComponentProps<'button'>) => {
  return (
    <button {...props} />
  )
}

export default Button;

[packages/ui/src/index.ts]

export { default as Button } from './Button';

5. Set up test environment with vitest and react-testing-library.

> pnpm add -D --filter ui @testing-library/jest-dom vitest jsdom @testing-library/react

[packages/ui/vitest.config.ts]

import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react-swc';

export default defineConfig(({ mode }) => ({
  plugins: [react()],
  resolve: {
    conditions: mode === 'test' ? ['browser'] : [],
  },
  test: {
    environment: 'jsdom',
    setupFiles: ['./vitest-setup.js'],
  },
}));

[packages/ui/vitest-setup.js]

import '@testing-library/jest-dom/vitest';

[packages/ui/tsconfig.json]

{
//...
    "types": ["@testing-library/jest-dom"],
//...
}

import '@testing-library/jest-dom/vitest'; from the vitest-setup.js enables you to use jest-dom functions such as toBeInDocument with vitest.

Additionally, to see the proper types, you should add the jest-dom type in the types field.

6. Write test code

[src/packages/ui/Button.test.tsx]

import { test, expect} from 'vitest';
import { render, screen} from '@testing-library/react'
import Button from './Button';

test('Button shuold be rendered', () => {
  render(<Button>Hello</Button>);

  expect(screen.getByText(/Hello/)).toBeInTheDocument();
});

7. Add a test script

[src/packages/ui/package.json]

{
  "name": "@mono/ui",
  "main": "src/index.ts",
//...
  "scripts": {
    "test": "vitest run"
  },
//...
}

The package has been renamed with @mono/ui and set the main file path.

8. Run test:all

Using packages on the website

1. Add dependencies in package.json

[website/package.json]

{
//...
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "@mono/ui": "workspace:*",
    "@mono/utils": "workspace:*"
  },
//...
}

2. Install dependencies

pnpm install

3. Write code

[website/src/App.tsx]

import { ChangeEvent, useState } from 'react'
import { Button } from '@mono/ui';
import { add } from '@mono/utils';

function App() {
  const [nums, setNums] = useState({
   a: '',
   b: '', 
  })

  const handleNumChange = (key: keyof typeof nums) => (e: ChangeEvent<HTMLInputElement>) => {
    setNums(prevNums => ({
      ...prevNums,
      [key]: e.target.value,
    }));
  };


  return (
    <div>
      <input type='text' value={nums.a} onChange={handleNumChange('a')} />
      <input type='text' value={nums.b} onChange={handleNumChange('b')} />
      <Button onClick={() => {
        alert(add(Number(nums.a), Number(nums.b)));
      }}>Add</Button>
    </div>
  )
}

export default App

4. Result

Wrap up

Explore some mono repos, you will get an idea of how you should set your project. husky, common setting of tsconfig file, etc, there are many things you can set up with and also you need to consider such as versioning, dependencies, and so on.

I hope you found it helpful and Happy Coding!

Full Source Code