Skip to main content
ZeroStarter follows a clean monorepo architecture powered by Turborepo and Bun workspaces. This structure provides separation of concerns, code reusability, and efficient build orchestration.

​
Overview

The project is organized into three main directories: 
.
├── api/           # Backend services
├── web/           # Frontend applications
└── packages/      # Shared packages and libraries

​
Directory Structure

​
Workspace Configuration

The root package.json defines workspace packages:
package.json
{
  "workspaces": [
    "api/*",
    "packages/*",
    "web/*"
  ]
}

​
Import Aliases

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
Use @/ for local imports within each workspace package: 
// Instead of: import { something } from "../../lib/something"
import { something } from "@/lib/something"

​
Adding New Packages

1

Create package directory

mkdir -p packages/my-package/src
cd packages/my-package
2

Initialize package.json

packages/my-package/package.json
{
  "name": "@packages/my-package",
  "version": "0.0.1",
  "private": true,
  "type": "module",
  "exports": "./dist/index.mjs",
  "scripts": {
    "build": "tsdown",
    "check-types": "tsc --noEmit"
  },
  "dependencies": {},
  "devDependencies": {
    "@packages/tsconfig": "workspace:*",
    "tsdown": "catalog:",
    "typescript": "catalog:"
  }
}
3

Create source files

packages/my-package/src/index.ts
export const myFunction = () => {
  return "Hello from my package!"
}
4

Add to workspace dependencies

api/hono/package.json
{
  "dependencies": {
    "@packages/my-package": "workspace:*"
  }
}
5

Install and use

bun install
api/hono/src/index.ts
import { myFunction } from "@packages/my-package"

console.log(myFunction())

​
Build System

ZeroStarter uses Turborepo for efficient build orchestration:
  • Caching: Builds are cached and only rebuilt when necessary
  • Parallel execution: Tasks run in parallel when possible
  • Dependency graph: Automatically determines build order
# Build all packages in correct order
bun run build

# Run dev mode for all workspaces
bun dev
See the turbo.json for pipeline configuration.

​
Best Practices

Avoid circular dependencies: Packages should not depend on each other in a circular manner. The dependency flow should be:api/web → packages/auth → packages/db → packages/env
Workspace protocol: Always use workspace:* for internal dependencies to ensure proper linking.
Catalog versions: Use catalog: in dependencies to share versions across the monorepo. Version definitions are in the root package.json under catalog.

Build docs developers (and LLMs) love

Get started for freeTalk to us