Getting Started

Getting Started with OneApp

A production-ready pnpm monorepo for building scalable Next.js 16 applications with shared packages, team workspaces, and modern tooling.

Why OneApp?

Building modern web applications with shared code across teams is challenging:

• Scattered code — Teams duplicate components, utilities, and configurations across projects
• Version chaos — Different apps use conflicting dependency versions
• Slow setups — Starting new projects requires copying boilerplate and fixing broken dependencies
• Type mismatches — Shared types drift out of sync between applications
• Configuration hell — ESLint, TypeScript, and Prettier configs are copy-pasted and diverge

OneApp solves this by providing a structured monorepo with shared packages (@repo/*), team workspaces, and consistent tooling — so you can focus on building features, not managing infrastructure.

Production-ready with Next.js 16 (App Router, Turbopack), React 19, TypeScript 5 (strict mode), Tailwind CSS 4, pnpm 10+ (fast installs), Vercel AI SDK v6, Better Auth, Prisma ORM, and comprehensive testing (Vitest 4, Playwright).

Use cases

OneApp is ideal for:

• Multi-app products — Build multiple Next.js applications that share UI components, utilities, and types
• Team collaboration — Give each team isolated workspaces while consuming shared packages
• Rapid prototyping — Spin up new apps with all dependencies and configurations pre-configured
• Enterprise applications — Maintain consistent code quality with shared ESLint, TypeScript, and Prettier configs
• Design systems — Develop and test UI components in Storybook while using them across apps

How it works

OneApp organizes your code into logical workspaces using pnpm:

{
  "name": "web",
  "dependencies": {
    "@repo/ui": "workspace:*",        // Shared React components
    "@repo/utils": "workspace:*",     // Common utilities (cn, debounce, formatters)
    "@repo/types": "workspace:*",     // TypeScript utilities & branded types
    "next": "^16.0.0",
    "react": "^19.0.0"
  }
}

Your apps automatically get access to shared packages with workspace:* — no manual linking required.

Quick Start

Get up and running in 2 minutes

git clone https://github.com/OneDigital-Product/monorepo.git
cd monorepo
pnpm install

pnpm dev

# Run Storybook to see shared components
pnpm --filter=storybook dev

# Run OneApp microfrontend architecture
pnpm dev:oneapp

# Check code quality
pnpm lint && pnpm typecheck

pnpm build
pnpm start

That's it! You're now ready to build with OneApp.

Key technologies

What's included

OneApp provides everything you need to build modern applications:

Shared Packages

• @repo/ui — React components with Tailwind CSS and comprehensive tests
• @repo/utils — Common utilities: cn(), debounce(), formatDate(), validators
• @repo/types — Branded types (UserId, OrderId), AsyncResult<T>, API response types
• @repo/config — Shared ESLint, TypeScript, Prettier, and Stylelint configs

Team Workspaces

Each team gets isolated workspaces:

teams/
├── ai/{apps,packages,infra}/
├── istudio/{apps,packages,infra}/
└── engineering/{apps,packages,infra}/

Teams can create applications, share packages internally, and consume shared @repo/* packages.

Personal Workspaces

Individual developers get dedicated spaces for experimentation:

personal/
├── andy/{apps,packages,infra}/
├── torin/{apps,packages,infra}/
└── ...

Modern Tooling

• ESLint 9 — Flat config with presets for React, Next.js, Node, Expo, Storybook, tests
• Prettier 3 — Auto-formatting on pre-commit via Husky
• Vitest 4 — Unit and integration testing with @testing-library/react
• Playwright — End-to-end testing
• Stylelint — CSS quality checks
• Turborepo — Fast task orchestration with caching

CI/CD Pipeline

GitHub Actions workflows for:

• Linting — ESLint + Prettier checks
• Type checking — TypeScript across all packages
• Building — Production builds
• Testing — Vitest + Playwright
• Code review — CodeRabbit AI with security checks (ESLint, Gitleaks, Semgrep)

Learning paths

Choose your path based on your role:

New to OneApp

1. Prerequisites → — Ensure your environment is ready
2. Installation → — Set up the monorepo
3. Project Structure → — Understand the codebase
4. Commands → — Learn essential commands

Building Applications

1. Workspace Architecture → — Understand pnpm workspaces
2. Shared Packages → — Explore available packages
3. Platform Apps → — See example applications

Team Leads

1. Workspace Architecture → — Team workspace structure
2. Dependency Management → — Managing workspace dependencies
3. Type Safety → — TypeScript patterns