Published on · Updated on: · By Suyash Tiwari
- 11 min read
How to Deploy a Monorepo to Production (Next.js + Node.js)
Deploying a monorepo to production means getting multiple services live from a single repository. Most platforms were built for single-app repos, so they require you to manually configure root directories, build commands, and environment variables for every service separately. With Kuberns, you connect your repository once, select each app, and both your Next.js frontend and Node.js backend are running in production without writing a single config file.
If you have already built a full stack app with AI and organized it as a monorepo, this guide covers exactly how to get it live.
What Is a Monorepo and Why Deployment Gets Complicated
A monorepo is a single Git repository that contains multiple applications and shared packages managed together. Instead of maintaining separate repos for your frontend, backend, and shared UI library, everything lives in one place.
The most common structure looks like this:
my-app/
├── apps/
│ ├── web/ # Next.js frontend
│ └── api/ # Node.js backend
├── packages/
│ ├── ui/ # Shared component library
│ └── utils/ # Shared utilities
├── turbo.json
└── package.jsonPopular tools for managing this include Turborepo, Nx, pnpm workspaces, and Yarn workspaces. The appeal is real: share code across apps, make atomic commits that touch both frontend and backend at once, and run a single lint or test command across the entire codebase.
The deployment problem shows up immediately. Most platforms expect a repository to be a single deployable unit. They run install and build from the repo root and expect one start command that launches one service. A monorepo breaks every one of those assumptions.
There are two types of monorepos and they behave differently at deploy time. An isolated monorepo contains apps that share no code. Each app is self-contained in its directory and can be deployed by simply pointing the platform at that subdirectory. A shared monorepo uses workspaces so apps import from a shared packages/ folder. The build must run from the repo root for those shared packages to resolve, which is where most platforms fall short.
Teams adopting monorepos for the first time hit a wall at deployment. The same structure that makes development seamless makes deploying a SaaS app significantly harder on platforms that were not designed for it.
How Monorepo Deployment Actually Works
Before touching any platform, it helps to understand the mechanics of what has to happen for a monorepo to deploy correctly.
Per-service deployment model: Each application in your monorepo deploys as its own independent service. Your Next.js frontend is one service. Your Node.js backend is another. They run separately, have their own URLs, and scale independently.
Root directory scoping: Every deployment platform lets you set a root directory for a service. This tells the platform where your app lives inside the repository. If you set it to apps/web, the platform only looks at files in that folder. The problem is that apps/web imports from packages/ui, which lives outside that folder. Most platforms never see those shared packages and the build fails.
Build command scope: Your build command needs to run from a place where shared packages are visible. For a Turborepo setup, the correct build command is turbo run build --filter=web executed from the repo root, not from apps/web. Most platforms default to running the build from whatever root directory you set, which is wrong for shared monorepos.
Shared package resolution: When your frontend imports @repo/ui, Node.js looks for that package in node_modules. If the platform only installed dependencies inside apps/web, the package is not there. The build runs fine locally because your local install happened at the repo root and hoisted everything. CI platforms that do not replicate that behavior produce a broken build.
Environment variable scoping: In a split-platform setup where your frontend is on Vercel and your backend is on Railway, environment variables are managed in two different dashboards, two different secrets stores, and two different deployment pipelines. Keeping them in sync becomes its own operational problem.
Understanding why monorepo deployments break on traditional platforms is the first step. See how teams are eliminating manual steps in their CI/CD workflow to cut this overhead entirely.
How to Deploy a Next.js and Node.js Monorepo on Kuberns
Kuberns reads your repository structure and surfaces each app inside apps/ as a deployable service. You do not write root directory configs, custom build commands, or YAML files. Here is the full flow.
Step 1: Connect your GitHub repository
Open the Kuberns dashboard, create a new project, and connect your GitHub account. Select the repository that contains your monorepo.
Step 2: Deploy the Next.js frontend
Kuberns detects the apps in your repository. Select apps/web. Kuberns identifies it as a Next.js app, sets the correct build command, and runs the install from the repo root so shared packages from packages/ are available. Add your environment variables in the dashboard and click deploy.
Step 3: Deploy the Node.js backend
Inside the same Kuberns project, add a second service. Select apps/api. Kuberns identifies it as a Node.js app and applies the same root-level install behavior. Your backend is live in a few minutes alongside your frontend, both visible in the same project dashboard.
Step 4: Connect your domains
Both services are now running. Attach custom domains to each directly from the Kuberns dashboard. SSL is provisioned automatically. For a full walkthrough on this step, see how to add a custom domain to your deployed app.
Step 5: Push to deploy
From this point, every push to your linked branch triggers a redeploy of the affected service. You do not configure webhooks or per-service pipelines. Kuberns handles it at the project level.
Most teams spend hours configuring platforms to handle a monorepo. With Kuberns, the same setup that takes a day on Railway takes under ten minutes. See what else you can auto-deploy from GitHub in one click.
Why Kuberns Is the Best Way to Deploy a Monorepo
Vercel, Railway, and Render all support monorepos to varying degrees. None of them handle a full-stack monorepo with the same simplicity Kuberns does.
Vercel works well for frontend-only monorepos. If your monorepo is multiple Next.js apps with no backend, Vercel is a reasonable choice. The moment you add a persistent Node.js backend, Vercel cannot run it. Vercel is a serverless platform. Your apps/api would have to be rewritten as serverless functions, or you deploy the backend elsewhere and manage two platforms simultaneously.
Railway supports full-stack monorepos but requires you to create a service for each app manually, set the root directory for each, and write custom build commands that invoke Turborepo from the right working directory. If your shared packages are not hoisted correctly, you will spend time debugging package resolution failures with no guidance from the platform. Railway also has no native monorepo detection.
Render follows a similar pattern. You create one service per app, set root directories and build filters, and manage everything across separate service settings pages. Autodeploy behavior per service requires build filter configuration that is easy to get wrong.
Kuberns detects your repository structure, deploys each app as a service under the same project, installs from the monorepo root by default, and surfaces everything in one dashboard. There is no YAML to write and no per-service build command configuration.
| Platform | Monorepo Detection | Frontend and Backend Together | Manual Config Required | Shared Package Resolution |
|---|---|---|---|---|
| Kuberns | Automatic | Yes | No | Handled automatically |
| Vercel | Partial | Frontend only | Yes | Manual |
| Railway | None | Yes | Yes | Manual |
| Render | None | Yes | Yes | Manual |
For teams already evaluating where to host their backend, this comparison is covered in more depth in the best tools to deploy backend apps breakdown.
Vercel locks you into a frontend-only workflow. If your app has a backend, you will end up managing two platforms before your first real user. Here is why Vercel’s GitHub integration breaks for full-stack teams and what to use instead.
Common Monorepo Deployment Errors and How Kuberns Handles Them
These are the errors developers hit when deploying monorepos on traditional platforms, and how Kuberns resolves each one in its deployment workflow.
Shared package not found during build
On Railway and Render, setting a service root directory to apps/web means the platform only installs dependencies inside that folder. Imports from packages/ui or packages/utils break immediately. Kuberns installs dependencies from the repository root by default, mirroring your local development environment so shared packages are always available to every service.
Build passes locally but fails in CI
This happens when the platform skips workspace root installation and only installs in the app subdirectory. Your local machine has the full workspace installed, CI does not. Kuberns runs the install step from the repo root for every service in a monorepo project, eliminating this class of failure entirely.
Environment variables not reaching a service
In a split-platform setup, environment variables set in Vercel do not exist on Railway, and vice versa. Teams end up duplicating secrets across multiple dashboards and debugging broken API connections in production. With Kuberns, all services in a project share one environment variable panel. Set a variable once and it is accessible to every service in the project.
Wrong start command path
On Render, if your root directory is set to apps/api, the start command node dist/index.js works. If you accidentally leave the root directory at the repo root, the same command looks for dist/index.js in the wrong place and the service crashes on boot. Kuberns infers the correct start command based on the detected framework in each app directory, so this error does not reach production.
Build tool not found
If turbo is listed in the devDependencies of a sub-app but not at the workspace root, platforms that install only in the subdirectory cannot find it. Kuberns flags this as a configuration warning during the setup step rather than letting the build fail silently after deployment starts.
Avoiding these errors manually is part of why teams switch to a platform that handles monorepo specifics out of the box. If you want to understand what goes wrong at a deeper level, the breakdown of why software deployments fail covers the root causes in detail.
Every error above is a problem you can entirely avoid. See how teams are setting up zero downtime deploys to make every push to production completely safe.
Deploy Your Monorepo on Kuberns
Most teams spend days fighting platform configs before their first service is live. With Kuberns, your entire monorepo is running in production in under ten minutes.
Connect your GitHub repo, select each app from your apps/ directory, and Kuberns handles the rest. Root installs, build commands, shared package resolution, environment variables, SSL, and custom domains are all managed for you. Your frontend and backend run together under one project with a single dashboard, unified logs, and automatic redeploys on every push.
No split platforms. No YAML. No per-service pipeline setup. Just your code, deployed.
Frequently Asked Questions
Can I deploy a Turborepo monorepo without using Vercel?
Yes. Turborepo is a build tool and is completely platform-agnostic. You can deploy a Turborepo monorepo to Kuberns, Railway, Render, or any platform that supports custom build commands. Kuberns is the simplest option because it detects your monorepo structure automatically and deploys all services without manual configuration.
How do I deploy both a Next.js frontend and a Node.js backend from the same monorepo?
Connect your monorepo to Kuberns, select apps/web for the Next.js frontend and apps/api for the Node.js backend, and deploy both as services under the same project. Kuberns handles shared package resolution, environment variables, and build commands automatically. Both services are live in the same dashboard.
Why do shared packages fail when deploying a monorepo to production?
Most platforms run npm install or pnpm install only in the subdirectory set as the service root. This skips the workspace root, so packages inside packages/ui or packages/utils are never installed. Kuberns installs dependencies from the monorepo root by default, so shared packages resolve correctly for every service without extra configuration.
Does Kuberns support Nx monorepos as well as Turborepo?
Yes. Kuberns supports any monorepo structure including Turborepo, Nx, pnpm workspaces, Yarn workspaces, and npm workspaces. As long as your apps are organized in subdirectories, Kuberns can deploy each one as an independent service from the same repository.
Do I need separate CI/CD pipelines for each service in a monorepo?
Not with Kuberns. Kuberns connects to your GitHub repo at the project level and triggers redeploys automatically on every push. You do not configure per-service CI/CD pipelines. On Railway or Render, each service has its own webhook and its own deployment trigger, which means maintaining multiple pipelines as your monorepo grows.
What is the difference between an isolated monorepo and a shared monorepo for deployment?
An isolated monorepo contains completely independent apps that share no code. Each can be deployed by setting a root directory on any platform. A shared monorepo uses workspaces so apps import from a common packages/ folder. Shared monorepos are harder to deploy because the build must run from the repository root for shared packages to resolve correctly.