Monorepo Starter
Note - this starter is still a work in progress and some features described below have not been set up yet
An example setup of how to do a monorepo, used in our Monorepo Getting Started Guide
Usable as a template from github as a fully setup monorepo - we configure the monorepo tooling so you can configure the rest however you want
Using this Starter
- Clone this repository, or click the
use this template
button on Github. - Delete packages you do not need, and add your own packages in the folder that makes most sense.
- Run
yarn
- Start the server using
yarn start:server
- Start the website using
yarn start:next
- Visit
http://localhost:3000/
to see it running๐
You are now ready to start developing within the monorepo!
If you are interested in how to further configure your project, or want more information on why it is set up like this, check out our Monorepo Style Guide
There is als a readme in each folder, to help explain why we have placed this folder there.
Working in a monorepo
We have a working in monorepos section in our style guide with advice on how to work with this monorepo.
What is included in this starter
Packages set up
We have set up three different folders to put packages, based on their needs, each of which can include new packages. Here is what you have to start:
- packages/
- button
- apps/
- next-app
- services/
- graphql-api
- websites/
To determine where to place a new package:
- If it is designed to be consumed by other packages, and not run on its own, put it in the
/packages
folder. These may be published to npm, but can also include private packages. - If it is a user-facing app or website, it should live in the
/apps
folder - If it is a back-end service or node app, it should live in the
/services
folder
The website/
directory should be used for a documentation website, or other repository-wide website.
We recommend deleting any of these folders that you don't intend to use in your project
Tools we set up
- Yarn Workspaces
- Preconstruct
- Manypkg
- Changesets
- Babel
- Jest
- Eslint (but there are no rules yet)
Each of these tools have configuration specific to their usage in a monorepo, which has been configured for you. See our style guide for more information on the configuration for each tool.
If you plan to use any of the following, please see the style guide for how to set them up:
Installing new packages
When you install new packages, you will need to determine if they are intended to be used by the monorepo as a whole, or by an individual package.
If it is intended for use by the monorepo as a whole, add the package to the root package.json
and run yarn
to install.
If it is intended for use by an individual package, add it to that's package.json
and run yarn
to install.
Within a monorepo, all of your packages must use the same version of external packages. yarn manypkg check
will tell you if you have any problems. yarn manypkgs fix
will fix all problems. You can find out more about these rules in the manypkg docs
Quick Start Guide for some other tools
Next.js
- Use the existing
/website
folder, or create a folder for a new website in/apps/your-app-name
- Follow the normal Next.js setup instructions
- where the guide asks you to perform terminal commands (such as installing packages), run them from your app's folder, not from the repository root.
- Done.
We also have additional guides to using next.js with monorepos
Gatsby
TypeScript
TypeScript configuration in monorepos works best with common tsconfig
configurations. Reference Configuration inheritance with extends
-
Create a base
tsconfig.base.json
file in the project root.{ "compilerOptions": { "module": "esnext", "target": "es5", "moduleResolution": "node", "esModuleInterop": true, "lib": ["dom", "esnext"], "importHelpers": true, "rootDir": "./", "sourceMap": true, "declaration": true, "baseUrl": "./" } }
-
Create a base React
tsconfig.react.json
in the project root to add custom React settings.{ "extends": "./tsconfig.base.json", "compilerOptions": { "jsx": "react" } }
-
Then in your React components in your packages (eg.
./packages/button/
), add yourtsconfig.json
to extend your basetsconfig.react.json
.{ "extends": "../../tsconfig.react.json", "include": ["src"] }
Workflows set up
- Install: run
yarn
- This uses yarn workspaces to manage installation of dependencies for all your packages.
- This also runs a
postinstall
hook that will validate your monorepo setup (usingManykpkg
), and set your packages up for dev (usingPreconstruct
)
- Test: run
yarn test
, which will run Jest tests. - Build: run
yarn build
- This uses Preconstruct to build
dist
files from the source of all packages in/packages
and/apps
. - For any build work you want done outside of Preconstruct building dists, you will need to add to this script.
- This uses Preconstruct to build
- Release: run
yarn release
- this will run the build command, and then run
changeset publish
- this will run the build command, and then run
- Clean: run
yarn clean
- this uses
Manypkg
to remove thenode_modules
anddist
folders from each package in the repository, as well as from the root. It can be used to 'clean out' installed/built files to ensure runningyarn
orbuild
gets you fresh information.
- this uses
We strongly recommend using Changesets for versioning as well, here is a base explanation of the workflow