Monorepo structure:

Business modules (Apps):

Directory	Description
./apps/main	Main app monorepo example
./apps/widget	Another app widget monorepo example

Packages:

Directory	Package Name	Description
./packages/eslint-config	@monorepo-example/eslint-config	Common ESLint config for monorepo example
./packages/helpers	@monorepo-example/helpers	Helper utility functions for monorepo example
./packages/jest-config	@monorepo-example/jest-config	Jest config and setup for monorepo example
./packages/tsconfig	@monorepo-example/tsconfig	Common Typescript config for monorepo-example
./packages/ui	@monorepo-example/ui	Common UI components for apps

⚠️ Requirements ⚠️

• node.js - install version 20.12.2 (LTS). This is required to run the builder. You can check the installed version by typing the command node -v in the terminal/console.
• npm - it should be installed along with node.js. It is required for installing modules and running scripts. You can check the installed version by typing the command npm -v in the terminal/console, it should be 10.5.0.
• git

Installation

1. Clone (requires git) or download the repository:

git clone https://github.com/whoisYeshua/monorepo-example.git

2. Navigate to the folder

cd monorepo-example

3. Install dependencies via npm:

npm i

Commands

Start the dev server for all business modules with proxying requests to the DEV environment:

npm run dev

Start the dev server for the main microfrontend with proxying requests to the DEV environment:

npm run dev:main

Start the dev server for the widget microfrontend with proxying requests to the DEV environment:

npm run dev:widget

⭐ Start the dev server for the main microfrontend on local mocks using msw:

npm run dev:mock:main

Start the dev server for the main microfrontend for presentation on local BE:

npm run dev:local:main

Production build for all business modules:

npm run build

Production build for the main microfrontend:

npm run build:main

Production build for the widget microfrontend:

npm run build:widget

• Linter, formatting, and test commands

  running scripts in all monorepo packages

  Run format:eslint & format:prettier:

  npm run format

  Check the project with ESLint and fix code sections available for auto-fix:

  npm run format:eslint

  Format files according to the prettier config:

  npm run format:prettier

  ⭐ Run lint:eslint & lint:prettier & lint:typescript:

  npm run lint

  Check the project with ESLint for non-compliance with the config rules. Will not change the checked files:

  npm run lint:eslint

  Check the project with ESLint for non-compliance with the config rules (⚠️ for CI environment, where warnings are considered errors). Will not change the checked files:

  npm run lint:eslint:ci

  Check the project with prettier for non-compliance with the config rules. Will not change the checked files:

  npm run lint:prettier

  Check the project with Typescript for type errors. Will not change the checked files:

  npm run lint:ts

  Check the project with publint for non-compliance with the package.json rules. Will not change the checked files:

  npm run lint:package

  ⭐ Run unit tests on the project:

  npm run test

  Run unit tests on the project (⚠️ for CI environment):

  npm run test:ci

⭐ Clean node_modules, dist, and cache

npm run clean

⭐ Check the project with Knip for unused code

npm run knip

Clean the project from unused code

npm run knip:fix

⭐ Generate components, pages, API, transactions, and functions:

npm run generate

⭐ Start preview and test environment for components from the package (@monorepo-example/ui):

npm run storybook

Start Turborepo devtools for visualizing task execution and dependency graphs (debugging):

npm run devtools

NPM Updating dependencies tips

To run changes only in package-lock.json (without installing in node_modules), you can use the argument: npm i --package-lock-only

In @monorepo-example/ui

Simply installing a new version in the package.json of the UI package and then running npm i started leading to moving dependencies from the global space (flat location - node_modules/@tiptap/extension-placeholder) to the package space (packages/ui/node_modules/@tiptap/extension-placeholder). This leads to duplication of dependencies and bloating of node_modules if the library is used in a single instance for the entire monorepo. To solve this, you can try the following path:

1. In the root of the monorepo, type in the terminal npm i package@version -w @monorepo-example/ui --include-workspace-root to update. For example, with @tiptap packages:

npm i @tiptap/extension-placeholder@2.11.0 @tiptap/pm@2.11.0 @tiptap/react@2.11.0 @tiptap/starter-kit@2.11.0 -w @monorepo-example/ui --include-workspace-root

2. Clean the root package.json from these dependencies;
3. Run npm i to also clean package-lock.json from them.

In any module

1. Remove the packages to be updated from all package.json files
2. npm run clean
3. npm i package@version -w=module_location --legacy-peer-deps

npm i -w=apps/main  -w=packages/ui react@latest --legacy-peer-deps
npm i -w=apps/main -w=apps/widget -w=packages/helpers react@latest --legacy-peer-deps

4. npm run clean
5. npm i

Optional: Skills and MCP setup

Use these commands to add project-level AI tooling:

npx mcp-add --name chakra-ui --type stdio --command "npx -y @chakra-ui/react-mcp" --scope project
npx mcp-add --name storybook-mcp --type http --url "http://localhost:4123/mcp" --scope project
npx skills add https://github.com/vercel/turborepo --skill turborepo

Notes:

• Keep Storybook running before using storybook-mcp, otherwise the HTTP MCP endpoint is unavailable.
• If your Storybook MCP endpoint runs on a different port, update the url value accordingly.