DEV Community: Ahmad

Setting Up a Monorepo Workspace with Turborepo: A Complete Guide

Ahmad — Sun, 05 Jul 2026 18:33:48 +0000

If you've ever worked on a project with multiple services — a frontend, a couple of backend services, and a shared database layer — you've probably felt the pain of managing them as separate repositories. Shared types drift out of sync, duplicated config everywhere, and running everything together for local development becomes a chore.

This is exactly the problem a monorepo solves, and Turborepo is one of the best tools for managing one in the JS/TS ecosystem. In this post, I'll walk through setting up a real-world Turborepo monorepo with:

A Next.js frontend (fe)
An Express-based agent backend (agent)
A Bun-based history service (history)
A shared Prisma database package (packages/db)

By the end, you'll have a working monorepo where all services share types, database access, and TypeScript config — and can be built, linted, and run with a single command.

Prerequisites

Node.js >= 18
A package manager — this guide uses pnpm for the initial scaffold and bun for running the actual services (you can adapt commands to your preferred manager)
Basic familiarity with npm/pnpm workspaces

Step 1: Scaffold the Turborepo

Turborepo ships with a generator that scaffolds a ready-to-go monorepo structure. Run:

npx create-turbo@latest

You'll be walked through a short setup wizard:

Need to install the following packages:
create-turbo@2.10.3
Ok to proceed? (y) y
✔ Where would you like to create your Turborepo? someg
✔ Which package manager do you want to use? pnpm

>>> Creating a new Turborepo with:

Application packages
 - apps/docs
 - apps/web

Library packages
 - packages/eslint-config
 - packages/typescript-config
 - packages/ui

Once it finishes, you'll have a directory that looks like this:

$ ls
apps  node_modules  package.json  packages  pnpm-lock.yaml  pnpm-workspace.yaml  README.md  turbo.json

$ ls -a
.  ..  apps  .git  .gitignore  node_modules  .npmrc  package.json  packages  pnpm-lock.yaml  pnpm-workspace.yaml  README.md  turbo.json

This default structure ships with two example apps (docs and web) and three shared packages (eslint-config, typescript-config, ui) — a great starting point, but not our actual target structure. Let's reshape it.

Step 2: Plan Your Real Workspace Structure

For this project we need three independent services and one shared package:

Folder	Purpose	Runtime
`fe`	Frontend	Next.js
`agent`	Agent backend	Node/Express (via Bun)
`history`	History backend	Bun native
`packages/db`	Shared Prisma client	Used by all three above

Delete or repurpose the default apps/* folders, and create your own top-level service folders (agent, history, fe) instead of nesting everything under apps/. Turborepo doesn't require services to live under apps/ — workspaces just need to be declared correctly in your root config, which we'll do next.

Step 3: Declare Workspaces in the Root `package.json`

This is the piece that actually tells your package manager (and Turborepo) which folders are workspace members. Since our services live at the root level rather than under apps/, we declare them explicitly:

"workspaces": [
  "packages/*",
  "agent",
  "history",
  "fe"
]

Here's the full root package.json:

{
  "name": "same.dev",
  "private": true,
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "lint": "turbo run lint",
    "format": "prettier --write \"**/*.{ts,tsx,md}\"",
    "check-types": "turbo run check-types",
    "generate:db": "cd packages/db && bunx prisma generate",
    "build:frontend": "cd fe && bun run build",
    "start:frontend": "cd fe && bun run dev",
    "start:agent": "cd agent && bun run dev",
    "start:history": "cd history && bun run dev",
    "start:everything": "bun generate:db && bun build:frontend && bun start:frontend && bun start:agent && bun start:history"
  },
  "devDependencies": {
    "prettier": "^3.6.0",
    "turbo": "^2.5.4",
    "typescript": "5.9.2"
  },
  "engines": {
    "node": ">=18"
  },
  "packageManager": "bun@1.2.11",
  "workspaces": [
    "packages/*",
    "agent",
    "history",
    "fe"
  ]
}

A few things worth calling out:

"packages/*" is a glob — it automatically picks up every folder inside packages/ as a workspace (so packages/db, packages/typescript-config, etc. don't need to be listed individually).
agent, history, and fe are listed explicitly because they live at the repo root, not inside a shared parent folder.
The packageManager field pins the exact Bun version, which keeps builds reproducible across machines and CI.
Top-level scripts like build, dev, and lint are simply proxies to turbo run <task> — Turborepo then figures out which workspaces have that script and runs them (in parallel, with caching) rather than you calling each service manually.

At this point, your repo root should look like:

$ ls -a
.   agent     docker              .dockerignore  fe    .github     history       .npmrc        packages   .turbo
..  bun.lock  docker-compose.yml  .env           .git  .gitignore  node_modules  package.json  README.md  turbo.json

Step 4: Set Up the Shared Database Package

Since all three services need database access, it makes sense to centralize Prisma into a single shared package rather than duplicating the schema and client in every service.

Create packages/db/package.json:

{
  "name": "@repo/db",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "exports": {
    "./client": "./src/index.ts"
  },
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "devDependencies": {
    "@repo/typescript-config": "workspace:*",
    "prisma": "^6.14.0"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "type": "commonjs",
  "dependencies": {
    "@prisma/client": "^6.14.0"
  }
}

The important part here is the exports field:

"exports": {
  "./client": "./src/index.ts"
}

This defines a named export path for the package. Instead of every service reaching into packages/db/src/index.ts with a relative path, they can simply do:

import { prisma } from "@repo/db/client";

This is the standard pattern for sharing code across a monorepo — internal packages get a @repo/* scoped name (unrelated to npm's public registry) and are consumed the same way an external dependency would be, but resolved locally via the workspace.

Its tsconfig.json just extends the shared base config:

{
  "extends": "@repo/typescript-config/base.json"
}

Step 5: Wire Up Each Service

`fe` (Frontend — Next.js)

fe/package.json:

{
  "name": "same.dev.fe",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "generate:db": "cd .. && cd packages/db && bunx prisma generate && cd ../.."
  },
  "dependencies": {
    "next": "15.3.5",
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  },
  "devDependencies": {
    "@repo/db": "workspace:*",
    "@types/node": "^24.2.0",
    "@types/react": "^19",
    "@types/react-dom": "^19",
    "eslint": "^9",
    "eslint-config-next": "15.3.5",
    "typescript": "^5.9.2"
  }
}

(Trimmed to the essentials above for readability — your real fe/package.json will also include UI libraries like Radix, Tailwind, and whatever else your frontend needs.)

The key line is:

"@repo/db": "workspace:*"

The workspace:* protocol tells your package manager: "don't fetch this from npm — link it directly to the local packages/db folder in this monorepo." Any change you make in packages/db is instantly reflected in fe without publishing or reinstalling anything.

`agent` (Backend — Express)

agent/package.json:

{
  "name": "agent",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "build": "tsc -b",
    "start": "node ./dist/index.js",
    "dev": "bun run build && bun start"
  },
  "devDependencies": {
    "@repo/typescript-config": "workspace:*",
    "@repo/db": "workspace:*"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "type": "commonjs",
  "dependencies": {
    "@google/generative-ai": "^0.24.1",
    "cors": "^2.8.5",
    "dotenv": "^17.2.0",
    "express": "^5.1.0",
    "express-rate-limit": "^8.1.0",
    "groq-sdk": "^0.27.0",
    "minimatch": "^10.0.3"
  }
}

agent/tsconfig.json:

{
  "extends": "@repo/typescript-config/base.json",
  "compilerOptions": {
    "rootDir": "./src",
    "outDir": "./dist",
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowJs": true
  }
}

Notice the pattern: every service's tsconfig.json extends the shared @repo/typescript-config/base.json, then overrides only what's specific to that service (like rootDir/outDir for the build output). This keeps compiler settings consistent across the whole monorepo while still letting each service customize its build.

`history` (Backend — Bun native)

history/package.json:

{
  "name": "history",
  "module": "index.ts",
  "type": "module",
  "private": true,
  "scripts": {
    "build": "bun build ./src/index.ts --outdir dist --target bun",
    "start": "bun run dist/index.js",
    "dev": "bun ./src/index.ts",
    "generate:db": "cd .. && cd packages/db && bunx prisma generate && cd ../.."
  },
  "devDependencies": {
    "@repo/typescript-config": "workspace:*",
    "@repo/db": "workspace:*"
  },
  "peerDependencies": {
    "typescript": "^5.9.2"
  },
  "dependencies": {
    "cors": "^2.8.5",
    "express": "^5.1.0"
  }
}

history/tsconfig.json:

{
  "extends": "@repo/typescript-config/base.json",
  "compilerOptions": {
    "rootDir": "./src",
    "outDir": "./dist",
    "allowJs": true
  }
}

Unlike agent, history runs directly on Bun (bun ./src/index.ts for dev) rather than compiling to CommonJS and running with Node — which is why its package.json uses "type": "module" and skips the tsc -b build step during development.

Step 6: The Fix Most People Miss

If you scaffold each service folder independently (rather than through a generator), it's easy to forget the one thing that actually makes the monorepo work as a monorepo: wiring the internal workspace dependencies.

Every service that needs the shared database client must declare it explicitly:

"devDependencies": {
  "@repo/typescript-config": "workspace:*",
  "@repo/db": "workspace:*"
}

This needs to be added in agent, history, and fe individually. Without this line, TypeScript won't resolve @repo/db/client, and your package manager won't create the symlink needed for the workspace package to be importable at all — even if the folder physically exists on disk.

Similarly, every service's tsconfig.json needs to extend the shared config:

{
  "extends": "@repo/typescript-config/base.json"
}

Skipping this means each service falls back to its own default TypeScript behavior, and you lose the whole point of centralizing compiler settings.

Step 7: Install and Run

Once every package.json and tsconfig.json is wired up, install once from the root:

bun install

This resolves and symlinks all workspace packages in one pass. Then generate your Prisma client and bring up all services:

bun generate:db
bun start:everything

Or, using Turborepo's own task runner (recommended once you outgrow manual scripts), just:

turbo run dev

Turborepo will detect the dev script across fe, agent, and history, run them in parallel, and cache task outputs so repeated runs are fast.

Final Structure Recap

same.dev/
├── agent/                  # Express backend
│   ├── package.json
│   └── tsconfig.json
├── history/                # Bun backend
│   ├── package.json
│   └── tsconfig.json
├── fe/                     # Next.js frontend
│   ├── package.json
│   └── tsconfig.json
├── packages/
│   ├── db/                 # Shared Prisma client
│   │   ├── package.json
│   │   └── tsconfig.json
│   ├── typescript-config/  # Shared tsconfig base
│   └── eslint-config/      # Shared lint rules
├── package.json            # Root — declares workspaces + turbo scripts
├── turbo.json
└── pnpm-workspace.yaml / bun.lock

Wrapping Up

The core ideas that make this setup work are worth remembering beyond just this project:

Declare every workspace member explicitly in the root package.json (workspaces array), whether it's a glob like packages/* or a named folder like agent.
Use workspace:* for any internal package dependency — it links locally instead of hitting npm.
Use exports in shared packages to define clean import paths (@repo/db/client instead of deep relative imports).
Extend a shared tsconfig.json in every service so compiler behavior stays consistent, and override only what's service-specific.
Let Turborepo's task runner (turbo run dev/build/lint) replace manually orchestrated shell scripts once your service count grows — it parallelizes and caches automatically.

With this in place, adding a fourth service later is mostly copy-paste: create the folder, add it to workspaces, wire up @repo/db and @repo/typescript-config, and you're done.

How I Broke My Dual Boot, Lost Both Windows and Linux, and Clawed My Way Back With Just a Terminal

Ahmad — Sun, 05 Jul 2026 18:10:02 +0000

The Setup

Like a lot of Linux users, I was running a dual-boot system — Windows on one partition, Linux on another, with GRUB handling the boot menu between them. It had worked fine for months. Then one day, I lost root access on my Linux install.

(Fill in here: how did you lose root? Did you forget the password? Did sudo stop working? Did you mess up /etc/sudoers? This detail matters a lot for the story — readers will want to know how it started.)

The Mistake That Made Everything Worse

Instead of trying to recover root access properly (booting into recovery mode, using a live USB to chroot in and reset the password, etc.), I decided to just get rid of the Linux partition entirely from Windows Disk Management.

That was the real mistake — and here's the technical reason why:

When you dual-boot Windows and Linux with GRUB, GRUB becomes the primary bootloader sitting in the disk's boot sector (or EFI partition), and it holds references to both operating systems' partitions. When I deleted the Linux partition from inside Windows:

The Linux OS files were gone, obviously.
But GRUB was still installed as the boot manager, and it still tried to load — except now it couldn't find the Linux partition it expected, and in many setups this leaves the system unable to boot into either OS cleanly, because the boot sector / EFI boot entries are now pointing at partitions that no longer exist or have shifted.
Windows Boot Manager (bootmgr) either got overwritten by GRUB earlier during Linux installation, or the boot configuration data (BCD) no longer matched the disk layout after the partition deletion.

The result: no GRUB menu, no Windows boot, just errors like grub rescue> or a black screen with no OS loading at all.

The Only Way In: Windows Recovery Environment

The only access I had left was a terminal — and this would have been the Windows Recovery Environment (WinRE) command prompt, reached by:

Booting from a Windows installation USB (or holding Shift + Restart if the machine could still partially boot)
Choosing Repair your computer → Troubleshoot → Advanced Options → Command Prompt

(Confirm: is this how you got your terminal? Or did you use a different rescue/live USB?)

From here, I had raw diskpart and command-line access to the disk — but no working OS to log into yet.

Step 1: Confirming the Damage

First, I used diskpart to check what the disk actually looked like now:

diskpart
list disk
select disk 0
list partition

This confirmed the Linux partition was gone and showed me the current partition layout — important for knowing whether my Windows partition (and its data) was still intact.

Step 2: Rebuilding the Windows Bootloader

With the partition table confirmed, the next job was to repair Windows' ability to boot at all. This is where the bootrec tool comes in — it repairs the Master Boot Record, boot sector, and Boot Configuration Data (BCD):

bootrec /fixmbr
bootrec /fixboot
bootrec /scanos
bootrec /rebuildbcd

/fixmbr writes a fresh, Windows-compatible Master Boot Record (this is what overwrites GRUB and hands control back to Windows).
/fixboot writes a new boot sector.
/scanos scans the disk for installed Windows OS instances.
/rebuildbcd rebuilds the Boot Configuration Data store so Windows Boot Manager knows where to find your Windows installation.

If /rebuildbcd doesn't find anything (common when BCD is severely corrupted), the fallback is manually rebuilding it against the Windows partition:

bcdboot C:\Windows

(assuming C: is your Windows partition letter, which you can confirm inside diskpart)

(Was this roughly your sequence, or did you need bcdedit as well to manually rebuild boot entries?)

Step 3: Getting Back Into an Actual User Account

Fixing the bootloader gets you to a Windows login screen — but you mentioned you'd also lost access and had to "attach" your username back. This is almost certainly done one of two ways from that same recovery command prompt, using the offline SAM database:

Option A — enable the hidden built-in Administrator account:

net user administrator /active:yes

This flips on the built-in admin account (disabled by default), letting you log in without a password and fix things from inside Windows.

Option B — reset your own account's password directly:

net user YourUsername NewPassword123

Once logged in through either method, if your original account had lost its admin rights or gotten decoupled somehow, you'd restore it with:

net localgroup administrators YourUsername /add

(This is the part I'm least sure about — do you remember if you enabled the built-in Administrator account, or reset your own account's password? That changes the exact commands in this section.)

Lessons Learned

Never delete a partition from the "other" OS without understanding the boot chain first. Deleting Linux from Windows Disk Management doesn't clean up GRUB — it just orphans it.
Always keep a live USB (Linux) and a Windows installation/recovery USB on hand. Both saved me here, or would have, sooner.
If root access is lost on Linux, the fix is almost always safe/recovery mode + single-user shell to reset the password — not nuking the partition.
Consider using Windows Boot Manager as the primary bootloader (with GRUB added as an entry via os-prober or manually) instead of the reverse — it tends to survive Windows updates and partition changes more gracefully.

If you've broken your dual boot in a different way, I'd love to hear how you recovered — drop it in the comments.