Installation

Get OneApp running on your local machine in under 5 minutes.

Why proper installation matters

Setting up a monorepo incorrectly leads to frustrating issues:

• Broken dependencies — Missing or incorrect packages cause cryptic errors
• Wrong versions — Conflicting dependency versions break builds
• Failed Git hooks — Pre-commit checks don't run, allowing bad code to be committed
• Environment mismatches — Missing environment variables cause runtime errors

OneApp's installation automates the setup process — cloning the repository, installing all workspace dependencies, linking internal packages, and configuring Git hooks — so you can start building immediately.

Quick Start

Get up and running in 3 steps:

# Clone via HTTPS
git clone https://github.com/OneDigital-Product/monorepo.git
cd monorepo

# Or via SSH (recommended for contributors)
git clone git@github.com:OneDigital-Product/monorepo.git
cd monorepo

pnpm install

pnpm dev

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

# Type check all packages
pnpm typecheck

# Lint all packages
pnpm lint

# Full quality check (recommended before first PR)
pnpm build && pnpm lint && pnpm typecheck

Alternative development commands

Explore different development modes:

Main web application

pnpm dev

Starts the Next.js 16 web app with:

• Hot reload — Changes reflect instantly
• Turbopack — Fast builds
• TypeScript — Real-time type checking
• Port: 3000

OneApp microfrontend architecture

pnpm dev:oneapp

Starts the complete OneApp ecosystem:

• oneapp-onstage — Main consumer app (port 3000)
• oneapp-backstage — AI workflow designer (port 3001)
• oneapp-api — REST API server (port 3002)

Storybook component library

pnpm --filter=storybook dev

Starts Storybook at http://localhost:6006 with:

• Component development — Build and test UI components in isolation
• 5-theme system — Test components across Light, Dark, Corporate, Marketing, Admin themes
• Accessibility testing — Built-in a11y checks

Production build

# Build for production
pnpm build

# Start production server
pnpm start

What was installed

After installation, you'll have:

Project structure

monorepo/
├── apps/web/              # Main Next.js 16 application
├── packages/
│   ├── ui/                # Shared React components (@repo/ui)
│   ├── types/             # TypeScript utilities (@repo/types)
│   ├── utils/             # Common functions (@repo/utils)
│   └── config/            # Shared configs (@repo/config)
├── teams/                 # Team workspaces (ai, istudio, engineering)
├── personal/              # Personal workspaces (andy, torin, michael, vinay, jeff)
├── platform/              # Platform apps (docs, oneapp-*, storybook, mobile-app, email)
└── node_modules/          # Shared dependencies

Key packages

Troubleshooting

Installation fails

# Try installing without lockfile constraints
pnpm install --no-frozen-lockfile

# Or clear pnpm cache and reinstall
pnpm store prune
pnpm install

Port 3000 already in use

# Use a different port
pnpm dev -- -p 3001

# Or kill the process using port 3000
lsof -ti:3000 | xargs kill -9

Node.js version mismatch

# Switch to Node.js 22
nvm use 22

# Or install if not available
nvm install 22

pnpm command not found

# Enable Corepack
corepack enable

# Or install pnpm globally
npm install -g pnpm@latest

Git hooks not working

# Reinstall Husky hooks
pnpm run prepare

# Or manually
npx husky install

Next steps

• Learn the structure: Project Structure →
• Master commands: Essential Commands →
• Understand workspaces: Workspace Architecture →