A monorepo is a repository containing multiple related resources managed from an individual repository. Using , we can build dynamic component libraries that numerous applications can consume, all retained in one version-controlled repository. NPM workspaces Introduction Monorepo's have been gaining traction over the years. Having worked with them for over a year in production environments, I can say one thing: ! they beat git submodules A typical monorepo will contain multiple packages and projects that are closely related. We can work more efficiently using a monorepo in a way that allows us to move away from: initializing git submodules (a repo within a repo) linking local packages from other locations on the disk that must be updated and installed. NPM supports , which effectively allows for a monorepo structure. You'll need to use NPM v7 and above to set up a Recently, I embarked on building a suite of components for a NextJS project. I wanted to ensure that I could actively develop components (facilitated by Storybook) so that my NextJS projects could consume those components. workspaces workspace. Historically, have always supported a folder. However, NextJS restricts this to the application itself. I aim to treat my component library like any other 3rd-party library I'd want to import into my projects. An architecture of this manner is easily achievable using a mono repo. NextJS projects components Initialise Project Structure Our first step is to set up a project structure supporting a monorepo. Create a folder where your monorepo can live: mkdir my-monorepo && cd my-monorepo Great. Our next step is to create a file. We can bootstrap one quickly by running the following: package.json npm init -y That should produce the following output: {
  "name": "my-monorepo",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
} Let's add some items to our before installing dependencies. We'll need to add a key. Doing so informs NPM where our projects and packages sit. package.json workspaces NPM comes with a nifty command for adding workspaces; run the below commands and follow the instruction wizard that each command outputs: npm init -w ./packages/component-library
npm init -w ./projects/monorepo-site Executing the above will run for you as well. npm install At this point, we will see our first fundamental differences between a traditional repo and a monorepo: A exists in the root and within every "workspace." You may notice that there is only one occurrence of and Now, all workspace dependencies get managed from the root folder. package.json node_modules package-lock.json. Next up, we'll look into how to install workspace-specific dependencies. Install dependencies When installing package or project dependencies, we can still leverage - however, this needs to be run from the root folder and requires that we pass a flag to the command. Let's run through . npm install -w installing NextJS npm install --save next react react-dom -w monorepo-site Run the command above from the of your project folder, where and the can be found. The only thing to call out here is that the value passed to must match the field of one of your or package.json. In this example, the field of is root node_modules package-lock.json -w name project packages name projects/monorepo-site/package.json monorepo-site. If all was successful, you should see the dependencies added to projects/monorepo-site/package.json. "dependencies": {
    "next": "^13.0.6",
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
} Repeat this process for any necessary dependencies in as well. packages/component-library Setup Components and StoryBook Please note that this is not a tutorial on how to get set up with Storybook. Let's take some steps to get Storybook set up correctly. We'll also create a dummy component to verify that our setup works. As StoryBook isn't a dependency of either or we can install it in the root of our monorepo: packages projects, npm install --save-dev @storybook/react @storybook/manager-webpack5 @storybook/builder-webpack5 @storybook/addon-postcss Let's also add the build commands to the root monorepo package.json: "storybook": "start-storybook -p 6006",
"build-storybook": "build-storybook" Next, we'll need to create the folder; let's do this and add it to the root of the monorepo. You'll want to add two files to this folder: .storybook main.js preview.js is where we configure StoryBook's settings: main.js module.exports = {
    "stories": [
        "../packages/component-library/**/*.stories.jsx",
    ],
    "addons": [
        {
            name: '@storybook/addon-postcss',
            options: {
                styleLoaderOptions: {},
                cssLoaderOptions: {
                    modules: true,
                    sourceMap: true,
                    importLoaders: 1,
                },
                postcssLoaderOptions: {
                    implementation: require('postcss'),
                },
            },
        }
    ],
    "framework": "@storybook/react",
    "core": {
        "builder": "@storybook/builder-webpack5"
    }
} In our file above - we tell StoryBook where to look for component stories. We also include the plugin that supports PostCSS. The extra options you see listed above enabled PostCSS Modules. The last two keys: and allow us to configure StoryBook to use Webpack v5. main.js @storybook/addon-postcss framework core, In add the following: preview.js, export const decorators = [
    (Story, context) => {
        return (
            <div style={{ padding: '1rem', display: 'flex', justifyContent: 'center' }}>
                <div>
                    <Story {...context} />
                </div>
            </div>
        );
    }
]; The file allows us to customize the appearance of stories without affecting the component logic itself. Hence, the name "decorator". I've just added some basic styling here to center the button. preview.js Next, we need to flesh out our component. In add a new folder called ; in that folder, add the following files: Button package/component-library, Button Button.module.css - handles the styling of the button Button.stories.jsx - handles the button story Button.jsx - the button component itself You can find the contents of these files in the repo. Great, we need to see if we can import our component into NextJS. Setup a NextJS project We need to return to NextJS quickly to tie everything together meaningfully. First, add a folder to the and the scripts needed in to build NextJS. pages NextJS site package.json To add the scripts, go to and replace the current field with: projects/monorepo-site/package.json scripts "scripts": {
	"dev": "next dev",
	"build": "next build",
	"start": "next start",
	"lint": "next lint"
} In the folder, add an file with the following contents: pages index.js const Home = () => {
	return (
		<main>
			<h1>Hello! This is a NextJS + StoryBook Monorepo</h1>
		</main>
	)
}

export default Home Add the Component to NextJS Now, it's time to import our component into NextJS. Let's import the button into : projects/monorepo-site/pages/index.js import Button from '../../../packages/component-library/Button/Button.jsx' When you run , you'll likely run into an error. NextJS does not transpile ES6 JavaScript from or any other local folder outside its reach. npm run dev node_modules To get around this problem, configure a property in called : next.config.js transpileModules export const nextConfig = {
	transpileModules: ['component-library']
} Note that the name, is passed, not the path to the folder on the disk. You'll need to restart your dev server. workspace component-library, Your custom Button component now lives in NextJS and StoryBook and can be iterated upon and tracked in the repo! You may run into trouble with NextJS asking for React v18 if you use NextJS 13. This tutorial was written using NextJS v12 and React v17.0.2 Additional Scripts for Convenience To run our build commands, we'd have to into every or . Doing so can be time-consuming, so let's add the following to the found in the root: cd project package scripts package.json "scripts": {
	"build": "npm run build --workspaces --if-present",
	"dev:monorepo-site": "npm run dev -w monorepo-site",
} Let's run through these two commands as they differ slightly. Running in the root will allow us to fire off individual scripts in all workspaces. If the task isn't in a or package.json, it will simply skip it. npm run build build build package project If, at some point, this particular example scaled to have three production sites, all with a command, we could run from the root, and for each workspace, the build task will execute. Pretty nifty! build npm run build is slightly different - this command targets one workspace and fires off the defined within that workspace (as long as it exists). Doing so allows us to spin up the server for from the root without navigating to the folder. npm run dev:monorepo-site script dev monorepo-site Conclusion Let's review where we're at: We initialized a monorepo structure using in NPM workspaces Set up a component library and production site with StoryBook and NextJS. Added scripts that will make our developer experience more accessible to manage. All our dependencies get managed from the top level, and we do not have to pull in other repos or git submodules. At this point, we could easily add a new site project or extend our component library. We could also add other that may deal with custom server functionality, CMS integrations, or API support. The possibilities are endless. Now it's time for you to try! packages Also published . here

Walkthroughs, tutorials, guides, and tips. This story will teach you how to do something new or how to do something better.

Mastering Monorepos: Organizing Component NextJS Libraries & Projects with NPM Workspaces

Too Long; Didn't Read

@dainemawer

Credibility

RELATED STORIES