DEV Community: Dawid Nitka

Creating a scalable Monorepo for Vue - Nx

Dawid Nitka — Sun, 01 Jun 2025 13:00:02 +0000

As your codebase grows, so does the complexity of managing multiple apps and libraries. At this point Nx can help with its graph, but more importantly it can orchestrate all builds and tests in monorepo and keep you sane while managing dozens of packages.

In essence Nx is capable of running tasks in parallel based on what has changed from the previous commit. It also respects dependencies, ensuring that libraries needed by others are built first.

Key Features

Project Graph & Dependency Awareness
Nx automatically analyzes your workspace and builds a project graph, understanding how your apps and libraries depend on each other. This
allows you to build or test only what has changed and furthermore what is directly influenced by it, based on the changes between the current and the previous commit.
Code Generation
Nx provides some nice generators for scaffolding new apps, libraries,
etc. I found them to be decent for Vue, but if you like it your way you can of course just ignore them.
Advanced Caching
Nx caches build and test results, so repeated commands are lightning
fast. It can even share cache results across CI runs and between developers (Caution: sharing is a nice but paid feature - still very useful for enterprise clients).
Powerful CI/CD
Nx can run tasks in parallel, only for affected projects, and provides detailed output for CI pipelines.

How to Configure Nx in Your Monorepo

Install Nx

If you’re starting from scratch, you can create a new Nx workspace with:

pnpx create-nx-workspace

In an existing monorepo, install Nx as a dev dependency and run init:

pnpm add -D nx

nx init

Nx Workspace Structure

Nx expects some sub-directories with package.json or it's internal project.json file by default as a marker of a package. Sample structure can look like this:

/
├── apps/
│   └── app_1/
├── libs/
│   └── commons/
│   └── ui/
├── nx.json
├── workspace.json (or project.json or package.json files)
├── tsconfig.base.json
├── pnpm-workspace.yaml
└── package.json

apps/: Applications (SPA, SSR, etc.)
libs/: Reusable libraries (UI, utilities, etc.)
nx.json: Nx-specific configuration (project graph, tasks, etc.)
workspace.json: Project definitions (can be split into per-project project.json or package.json),
pnpm-workspace.yaml: Defines workspace packages for pnpm

Adding Nx Plugins

Nx supports plugins for frameworks and tools. For example, to add Vue support:

pnpm add -D @nx/vue

Or for Storybook:

pnpm add -D @nx/storybook

With the mentioned plugins you can run and utilize Nx commands for these frameworks, but also use them for scaffolding new projects.

To start with using commands as well as Nx packages I recommend the vscode plugin Nx Console. It’s a great tool for exploring available options and features.

Basic Nx Commands

Run a target:

  pnpm nx build:staging @monorepo/app_1
  pnpm nx lint @monorepo/commons

Run for affected (changed from the last commit) projects only:

  pnpm nx affected -t build:staging

Start the project graph:

  pnpm nx graph

List of installed and available plugins:

  pnpm nx list

graph

It helps you visualize the dependencies between your packages. If you want to categorize your packages correctly in this browser based tool, I recommend either generating workspace.json or a bunch of project.json files, or as in my case (the simplest one) just adding this to your package.json files:

{
    "name": "@monorepo/ui",
    "version": "1.0.0",
    // ...
    "nx": {
        "projectType": "library" // or "application"
    }
}

affected

Running locally the affected command will work with default settings only if creating branch and making some changes as it compares your branch to the main. But you can always explicitly compare the current state with a state from a couple of commits ago for test purposes.

# run lint for packages which changed 
# between the current state and the state from 5 commits ago
pnpm nx affected -t lint --base=HEAD~5 --head=HEAD

This is the result of running lint for all packages in my monorepo template.

Not very spectacular, I know, but imagine how much build time you can save with a big monorepo while running this command on your server and executing commands in parallel only for the changed parts!

This is the last article in this series. If you want to learn more about creation of monorepo with Vue, check out other tutorials. If you prefer starting with a solid foundation - try this template, where I’ve put all of this into practice.

Creating a scalable Monorepo for Vue - Shared configs

Dawid Nitka — Sat, 22 Feb 2025 12:20:09 +0000

Now that we have in place all needed packages (libs and apps) and established connections between them, we have to take care of required configs like vite.config.ts, .eslint.cjs and postcss.config.cjs. We could add all of them multiple times, but as we have monorepo let's use it to our advantage.

You can create a global configs directory in the root of monorepo and add all common configs there, like: vite.application.ts, vite.service.ts, etc.

Later you can import them into apps and libs in the config files and refine them with some overwrites. Of course the overwriting or rather merging step can be a bit problematic. Luckily there are already tested solutions out there like this nice merge function made by John Hildenbiddle.

Merge sample

export default merge

/**
 * Recursively merges the specified object instances
 * @param instances Instances to merge, from left to right
 */
function merge(...instances) {
    let i = instances.length - 1
    while (i > 0) {
        instances[i - 1] = mergeWith(instances[i - 1], instances[i])
        i--
    }
    return instances[0]
}

/**
 * Merge an instance with another one
 * @param target Object to merge the custom values into
 * @param source Object with custom values
 * @author inspired by [jhildenbiddle](https://stackoverflow.com/a/48218209).
 */
function mergeWith(target, source) {
    const isObject = obj => obj && typeof obj === 'object'

    if (isObject(target) && isObject(source)) {
        Object.keys(source).forEach((key) => {
            const targetValue = target[key]
            const sourceValue = source[key]

            if (Array.isArray(targetValue) && Array.isArray(sourceValue)) {
                target[key] = targetValue.concat(sourceValue)
            }
            else if (isObject(targetValue) && isObject(sourceValue)) {
                target[key] = merge(Object.assign({}, targetValue), sourceValue)
            }
            else {
                target[key] = sourceValue
            }
        })
    }

    return target
}

With this you can add your vite.application.ts template:

import * as path from 'path'

import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin'
import vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'

export default defineConfig({
    root: process.cwd(),

    server: {
        host: 'localhost',
        open: true,
    },

    preview: {
        host: 'localhost',
    },

    plugins: [ vue(), nxViteTsPaths() ],

    // Uncomment this if you are using workers.
    // worker: {
    //     plugins: () => [ nxViteTsPaths() ],
    // },

    resolve: {
        alias: {
            '@': path.resolve(process.cwd(), './src'),
        },
    },

    build: {
        reportCompressedSize: true,
        commonjsOptions: {
            transformMixedEsModules: true,
        },
    },
})

and the index.ts file collecting all the configs:

import merge from './merge'
import getProxyConfiguration from './proxyConfig'
import applicationConfiguration from './vite.application'

import type { UserConfig } from 'vite'

export { getProxyConfiguration }

/**
 * Returns Vite build configuration for client applications,
 * optionally amended with the specified options
 * @param options Custom build options
 * @returns Vite build configuration
 */
export function getApplicationConfiguration(options: UserConfig = {}) {
    return getConfiguration(applicationConfiguration, options)
}

/**
 * Returns Vite build configuration amended with the specified options
 * @param configuration Default build options
 * @param options Custom build options
 * @returns Vite build configuration
 */
function getConfiguration(configuration: UserConfig, options: UserConfig = {}) {
    const result = merge(
        // Default configuration
        configuration,
        // Custom options to override the default configuration
        options
    )

    // Handy when you need to peek into that final build configuration
    // console.warn(JSON.stringify(result, null, 2))

    return result
}

Finally the usage of the whole template can look like this:

// eslint-disable-next-line
import { getApplicationConfiguration, getProxyConfiguration } from './../../config/vite'

export default getApplicationConfiguration({
    cacheDir: '../../node_modules/.vite/apps/app_1',

    server: {
        port: 5005,
        proxy: {
            // sample proxy configuration
            '/api': getProxyConfiguration('https://localhost:7148/'),
        },
    },

    preview: {
        port: 5005,
    },

    build: {
        outDir: '../../dist/apps/app_1',
    },
})

Notice that instead of standard export default { … } we are using the getApplicationConfiguration(…). It allows us to use the predefined template and overwrite some specific parts.

Check out the implementation in the sample repo. Usage sample can be found in the app.

Eslint, postcss, etc

The same applies to other repeatable configs like eslint. No matter if you are using the old syntax (8.x.x) or the newer one using export default (9.x.x) - you can still add a bunch of custom configs like I did here to import them as needed in the apps and libs (sample)

Generally speaking, in monorepo you can make your life easier by reusing many common configs by sharing them. After a bit of initial cost, adding yet another app or lib will be much easier.

If you want to learn more about creation of monorepo with Vue, check out other tutorials in the series. If you prefer starting with a solid foundation - try this template, where I’ve put all of this into practice.

In the next one, we will talk about builds and parallelization with Nx.

Creating a scalable Monorepo for Vue - Libs vs Apps

Dawid Nitka — Sat, 25 Jan 2025 18:00:12 +0000

One of the steps in creating a monorepo is splitting apps and libraries. But how to take them apart? What is a library and do you have to publish it somewhere?

The simplest answer is that a library is reusable code. To name a few, it can be your UI library, API files that will be reused, or even some library with useful functions—our well-known: helperThis, helperThat, ... In the case of Vue, it can also include a bunch of compostables (ex. useSomething). There's no need to publish them anywhere. They will be used directly from your libraries.

Setting up the consumer (app)

Let's assume you already have a couple of candidates to put them outside your app and reuse them. The next question is how to connect them.

In the previous post I mentioned adding libraries to the package.json (sample below) file, but it's only one side of the story.

{
    "name": "@monorepo/app_1",
    "version": "1.0.0",
    "type": "module",
    "scripts": {
        // ...
    },
    "dependencies": {
        "@monorepo/commons": "workspace:*",
        "@monorepo/ui": "workspace:*"
    },
    // ...
}

Setting up the provider (library)

The other side which is the library has to define all files that should be approachable from outside. Of course, it can be just some index file, but it could be a sub-directory as well - there's no need to set every file independently. All this has to be put in the library's package.json file.

{
    "name": "@monorepo/commons",
    "version": "1.0.0",
    "type": "module",
    "exports": {
        ".": "./src/index.ts",
        "./composables/*": "./src/composables/*"
    },
    "scripts": {
        // ...
    },
    "dependencies": {}
}

Typescript and intellisense

The sample above should give you already an idea of how to connect things. To use it you can just:

import someHelper from "@monorepo/commons/composables/analytics"

You will still notice that TypeScript running in the background cannot recognize imported libraries. To solve this add explicit such paths to the project's tsconfig.json file (section paths).

{
    "compilerOptions": {
        "paths": {
            "@monorepo/commons": [
                "../../libs/commons/src/*"
            ],
        },
    },
    // ...
}

The first part is what you want to use during the import and the second is a direct path to the file or directory.

As a bonus it also makes Vue components show you all expected parameters in the form of intellisense as if they were added directly to your project.

Setting up custom paths

I explicitly set @monorepo/commons to point to the library's /src directory. If the /src directory is exported in the library's package.json, it's enough to make it work.

You can also define your own, so-to-say, "nicknames". This practice is often used to create paths that are shorter and thus easier to use and remember.

For example, instead of using:

import someHelper from "@monorepo/commons/composables/analytics"

you could use

import someHelper from "@monorepo/commons/analytics"

To achieve this, define such a shortcut in the library's package.json:

{
    "name": "@monorepo/commons",
    // ...
    "exports": {
        ".": "./src/index.ts",
        "./composables/*": "./src/composables/*",
        "./analytics/*": "./src/composables/analytics/*",
    },
}

and also add it to the app's tsconfig.json file:

{
    "compilerOptions": {
        "paths": {
            "@monorepo/commons": [
                "../../libs/commons/src/*"
            ],
            "@monorepo/commons/composables/*": [
                "../../libs/commons/src/composables/*"
            ],
            "@monorepo/commons/analytics": [
                "../../libs/commons/src/composables/analytics/*"
            ],
        },
    },
    // ...
}

Creating a scalable Monorepo for Vue - Workspaces

Dawid Nitka — Tue, 14 Jan 2025 21:56:28 +0000

In the previous post, I mentioned so-called workspaces. This is a good starting point which also will show how to structure your future and existing projects. The first one (starting without any projects) is easy, the second (existing ones) requires a bit more work but with a bit of luck, everything should run smoothly.

The below steps describe how to do this with pnpm. You could also use yarn berry or yarn classic. In such case this approach works slightly differently by adding such structure description to the package.json file. The rest is quite similar.

Wait, but why not npm? I've heard that it also has workspaces.

AFAIK it's still not monorepo-ready due to serious problems with hoisting and the lack of ability to solve such dependencies. A good explanation of the struggle with npm caveats is provided in this article ;)

If you want to know more about creating a monorepo check out other tutorials in the series. If you prefer testing things on your own - try this template, where I put all of this into work.

Let's get to the work

Install pnpm if you don't have it yet:

npm install --global pnpm
#or
npm install --global corepack@latest
corepack enable pnpm
corepack use pnpm@latest-10

or you can follow the other options from the pnpm installation guide.

Create a new directory with a package.json file structured as follows:

{
    "name": "your_company_or_so",
    "version": "1.0.0",
    "private": true,
    "dependencies": {
        // all repeating dependencies
    }
    // ...
}

Add a pnpm-workspace.yaml file in the root directory to define your workspace structure:
```
packages:
  - 'apps/*'
  - 'libs/*'
  - 'whatever_else/*'
```
Add a bunch of sub-directories like apps, libs, etc. as defined in your workspace file.
Put your projects into the mentioned directories and/or create new ones.
Cut out the repeating dependencies and devDependencies from your projects' package.json files in the sub-directories and place them in the root package.json file. These are now connected to all your projects - exceptions are possible (read below).
Delete all your node_modules in the sub-directories if you copied them.

As mentioned in the previous post, you can directly connect your libraries to the projects by modifying the app's package.json file like so (more on this in the next article):

{
    "name": "@monorepo/app_1",
    "version": "1.0.0",
    "type": "module",
    "scripts": {
        // ...
    },
    "dependencies": {
        "@monorepo/commons": "workspace:*",
        "@monorepo/ui": "workspace:*"
    },
    // ...
}

Go to the root directory and install dependencies for all the projects at once:
```
pnpm i
```

FAQ

What about the dependencies that are not identical?

First consider bringing them to the same version, preferably the newer ones.

It's too time-consuming right now.

I get it—deadlines, and so on. You can just leave them where they are. I would still strongly recommend having only one version of Vue, React, Typescript, etc., because the more packages tied to the same version, the easier it is to update all your projects at once and deal with refactors after updating all the projects in one go.

Fine, I updated what I could, but there are still some dependencies requiring different versions.

It's fine, there is nothing wrong with it. Decide which version is more common and move this one to the root package.json. The less common version will stay in the package.json file of the project that is using it. This way, you signal your package manager that you need that specific version in a particular project, and it will be installed independently.

What about dependencies that are used only once? Should I move them as well?

It's up to you. If you assume that they will be used more often, sure, move them. Are they used only once for this specific project, and it's highly unlikely that it will change? Nah, you don't have to move it and pollute the root package.json.

Adding new dependencies

If you need to add something new to your monorepo you have two options:

Install a package for the entire workspace - run it in the root directory

# for dependencies 
pnpm add <package-name> -w

# for devDependencies
pnpm add <package-name> -Dw

Install it only for one of the apps / libs - run it in the app / lib directory

# for dependencies
pnpm add <package-name>

# for devDependencies
pnpm add <package-name> -D

Troubleshooting

I have some problems with dependencies with different versions.

You can try omitting this one migration to the root package.json file and keeping it in the projects' package.json files instead.

Creating a scalable Monorepo for Vue - Intro

Dawid Nitka — Tue, 14 Jan 2025 21:29:45 +0000

Hello world,

which means that this is my first article — first of many — as I intend to write a series on creating a monorepo structure for Vue.

What problem are we trying to solve?

Vue has become quite popular over the years, and more mid-size companies — and even some big names like Nintendo, Adobe, or Gitlab to name a few — are adopting it. Sometimes, they even choose it as the primary Framework for their products. That's why growing codebases containing many Vue packages are becoming common.

Juggling with projects and packages, publishing, updating, and dealing with the consequences of postponing the last step longer than we intended, due to fast-paced workflows. Many of us were already there, or are right now. This raises the question:

Is there a good alternative and what are the trade-offs?

In this series, I'll try to deliver some answers, as well as provide one of the solutions which you can see complete in this template. Feel free to use it as a base to kickstart your project or simply try it out.

If you have any questions, feel free to leave a comment or add a suggestion in the sample repo.

Monorepo

There is at least one good option on which we will focus as it's definitely a mature and battle-proven one - monorepo.

In contrary to microservices, which have a bunch of additional complexity this one embraces strengths of a monolith structure. I recommend a very good article on that matter from Maxi Ferreira - May I Interest You In a Modular Monolith?

The simple explanation is that we put everything into one directory. That's it? Well... not exactly. There are many additional possibilities, but let's start with the easy stuff.

One repo, but not much more

In the simplest form, it means that we create one repository with a bunch of sub-directories for our projects and libraries (packages) and that's it. The rest stays as it is: pushing to the origin, publishing with npm or Lerna. Maybe even with semantic-release if you've already made some optimization of the process.

Pros:

Many projects in one place -> less opened windows
Better overview of your team's work

Cons:

More branches -> potential chaos in the git tree

Add workspace

But what about managing external dependencies and consuming your libraries (packages)?

If you don't want to go to every project and update dependencies manually you should consider so-called workspaces. More about them in the next article in the series. In short, they will allow you to update more, maybe even all dependencies at once, and still keep full control over your projects, when some more granular interference will be required.

Sample workspace configuration with pnpm

To enable workspace features in pnpm, you need a pnpm-workspace.yaml file at the root of your repository.

packages:
  - 'apps/*'
  - 'libs/*'

This file will tell pnpm to treat all projects in the apps and libs directories as workspace packages.

More about it in the pnpm workspace docs.

With pnpm, you can manage workspaces and dependencies across all your projects in monorepo.
A couple of basic commands:

# Add a dependency to all projects in the workspace
pnpm add <package-name> -w

# Add a devDependency to all projects in the workspace
pnpm add <package-name> -Dw

# Add a dependency to a specific project
cd apps/app_1
pnpm add <package-name>

# Add a devDependency to a specific project
cd apps/app_1
pnpm add <package-name> -D

# Update all dependencies in the workspace to their latest versions
pnpm update --latest

Pros:

Faster update of dependencies for many projects at once
Less juggling with versions

Cons:

Requires updating more projects at once if they are tied to the same dependency in the root directory. They can still be split but it's somehow contrary to the goal

Add direct connection of dependencies

The workspaces are allowing us to manage external and internal dependencies way more easily. But what if I told you that you can directly use your other projects without even building them, not even mentioning publishing? With correct typescript configuration, you can even have types and intellisense still working. That is what you can achieve by connecting other of your libraries (previously packages) in your package.json like this:

{
    "name": "@monorepo/app_1",
    "version": "1.0.0",
    "type": "module",
    "scripts": {
        // ...
    },
    "dependencies": {
        "@monorepo/commons": "workspace:*",
        "@monorepo/ui": "workspace:*"
    },
    // ...
}

Notice the asterisks instead of version numbers. These mean that we are using whatever version is the newest. In our case, it's always the local one.

Pros:

Always the current version (also while developing in branches)
No need to publish libraries as packages and reinstall them
No local linking required to try out new library versions

Cons:

After a merge, dependencies might differ, potentially causing problems

This caveat can be mitigated with good test coverage and TypeScript running automatically through the complete codebase on the server before every build (which I highly recommend, regardless; ex. on the dev branch). This can be easily automated with husky.