Development Overview

An introduction to the Nebutra-Sailor monorepo — what each app does, how the workspace is organized, and how to get started contributing.

What is Nebutra-Sailor?

Nebutra-Sailor is a Turborepo monorepo that ships a complete AI-native SaaS product as working code. It contains 7 deployable apps and 20+ shared packages, all typed end-to-end, sharing a common design system, API contract, and runtime token system.

The monorepo is the source of truth for nebutra.com, app.nebutra.com, auth.nebutra.com, api.nebutra.com, and nebutra.com/docs.

Apps at a glance

AppPortPurposeFramework
apps/web3000 / 3001Authenticated SaaS dashboardNext.js 16 (prod) + Vite optional
apps/auth3101Login center (auth.nebutra.com)Next.js 16 + Better Auth
backends/gateway3002REST API — auth, RBAC, billing, AI proxyHono + OpenAPI (@nebutra/gateway)
apps/landing3000-ishPublic marketing site (locales)Next.js 16 + next-intl
apps/sailor-docs—Public product documentation (this site)Next.js 16 + Fumadocs
apps/design-docs—Internal design system documentationNext.js 16 + Fumadocs
apps/storybook6006Component library playgroundStorybook
apps/studio3333Content managementSanity Studio

Prerequisites

Before you can run the monorepo locally you need the following tools installed on your machine.

ToolMinimum versionWhy
Node.js22.xRuntime for all apps and tooling
pnpm10.32+Workspace package manager
Docker24+Local PostgreSQL, Redis, and ClickHouse
Git2.40+Source control

The repo uses pnpm workspaces. Running npm install or yarn install will produce incorrect results and is not supported.

Quick start

git clone https://github.com/nebutra/nebutra-sailor.git
cd nebutra-sailor
pnpm install
pnpm infra:up

This starts PostgreSQL 16, Redis 7, and ClickHouse 24 via Docker Compose.

Copy the example env files and fill in your secrets:

cp apps/web/.env.example apps/web/.env.local
cp apps/auth/.env.example apps/auth/.env.local   # if present
cp backends/gateway/.env.example backends/gateway/.env.local
cp apps/landing/.env.example apps/landing/.env.local
# Prefer AUTH_PROVIDER=better-auth for local parity with production
pnpm db:generate   # generate Prisma client
pnpm db:migrate    # run all pending migrations
pnpm db:seed       # seed development data
pnpm dev           # start all apps in parallel

Or start only what you need:

pnpm dev:dashboard   # web + gateway (see root package.json scripts)
pnpm dev:marketing   # landing + studio

For a full walkthrough with environment variable descriptions, common issues, and port assignments, see the Local Development guide.

Key conventions

  • Package manager: pnpm 10.32+ with workspaces. Always run pnpm at the repo root.
  • Linter + formatter: Biome (replaces ESLint + Prettier). Run pnpm lint:fix to auto-fix.
  • Type checking: pnpm typecheck runs tsc --noEmit across all packages via Turbo.
  • Testing: Vitest for unit tests, Playwright for E2E. Run pnpm test and pnpm e2e.
  • Build system: Turborepo with Vercel Remote Cache. Tasks are defined in turbo.json.

Project Structure

Annotated directory tree and file naming conventions.

Local Development

Detailed setup guide with all environment variables documented.

Editor Setup

Recommended VS Code extensions and Biome configuration.

Updating

How to pull upstream changes and re-run generators.

How is this guide?

Edit on GitHub

Last updated on

On this page

What is Nebutra-Sailor?
Apps at a glance
Prerequisites
Quick start
Key conventions
Related