Guides

Step-by-step tutorials for common development tasks in the OneApp monorepo — including git workflows, package creation, error handling, testing strategies, and troubleshooting.

Why you need these guides

Working in a monorepo without proper guidance leads to:

• Inconsistent code — Every developer writes components, handles errors, names files differently
• Git conflicts — Teams don't know how to branch, commit, or merge properly
• Package chaos — Creating shared packages incorrectly breaks the monorepo
• Testing gaps — No clear strategy for testing packages vs apps
• Deployment confusion — Don't know how to deploy individual apps or the full stack
• Repeated mistakes — Same errors fixed multiple times by different developers

OneApp's guides provide battle-tested patterns for git workflows (conventional commits, PR templates, branch protection), package creation (proper setup, exports, peer dependencies), error handling (AsyncResult pattern, error boundaries, API errors), testing (Vitest configs, component tests, E2E), and troubleshooting (common issues with solutions) — ensuring consistency across all teams.

Production-ready with patterns used across 40+ apps, automated enforcement via ESLint/Prettier, git hooks for validation, comprehensive examples, and step-by-step instructions.

Use cases

Master these guides to:

• Maintain consistency — Everyone follows the same conventions for naming, structure, git
• Ship features faster — Clear patterns for common tasks (error handling, testing, package creation)
• Avoid common mistakes — Learn from documented solutions to frequent issues
• Onboard quickly — New developers have clear references for how to work
• Debug efficiently — Troubleshooting guides with solutions to common problems
• Scale teams — Established patterns prevent chaos as team grows

Quick reference

Most common guides

• Conventions → — Naming, file structure, code style
• Git Workflow → — Branching, commits, PRs, merging
• Creating Packages → — Build new shared packages
• Error Handling → — AsyncResult pattern, error boundaries
• Troubleshooting → — Common issues and fixes

Quick examples

Create a new package:

# 1. Create directory structure
mkdir -p packages/my-package/src

# 2. Create package.json with @repo/my-package name

# 3. Configure TypeScript, ESLint

# 4. Add to an app
pnpm --filter=web add @repo/my-package

Follow git workflow:

# 1. Create feature branch
git checkout -b feature/my-feature

# 2. Make changes and commit
git add .
git commit -m "feat: add new feature"

# 3. Push and create PR
git push -u origin feature/my-feature
gh pr create

Handle errors with AsyncResult:

// Define function with AsyncResult return type
async function fetchUser(id: string): Promise<AsyncResult<User>> {
  try {
    const user = await db.user.findUnique({ where: { id } });
    if (!user) {
      return { success: false, error: new Error("User not found") };
    }
    return { success: true, data: user };
  } catch (error) {
    return { success: false, error: error as Error };
  }
}

// Use in component
const result = await fetchUser("123");
if (!result.success) {
  return <div>Error: {result.error.message};
}
return <div>Welcome, {result.data.name};

Complete guide reference

All guides by category

Development Standards

Use when: Setting up your development environment, writing code, handling errors, using AI assistants

Package Development

Use when: Building reusable packages, setting up team workspaces, integrating APIs

Recipes & Patterns

Use when: Implementing common features, understanding system architecture

Testing & Quality

Use when: Writing tests, debugging issues, looking up quick reference

Guide categories explained

Development Standards

Ensure consistency across all code in the monorepo:

• Naming conventions — PascalCase components, camelCase functions, kebab-case files
• Import order — External → Internal → Relative → Types → Styles
• Git workflow — Feature branches, conventional commits, PR templates
• Error handling — AsyncResult pattern, error boundaries, standardized API errors
• AI assistance — Claude Code, GitHub Copilot, Cursor configured with OneApp-specific patterns and specialized agents

Why it matters: Consistency reduces cognitive load, makes code reviews faster, prevents bugs, and enables AI assistants to generate correct code automatically

Package Development

Build reusable packages that work across the entire monorepo:

• Package structure — Proper exports, TypeScript config, ESLint setup
• Peer dependencies — When to use, how to configure, testing patterns
• Team workspaces — Isolated development, shared infrastructure
• API integration — OneApp SDK patterns, type-safe requests

Why it matters: Shared packages are the foundation of the monorepo. Done wrong, they break everything.

Recipes & Patterns

Implement common features quickly with proven patterns:

• Forms — React Hook Form + Zod validation
• Authentication — Better Auth patterns for web and mobile
• Data fetching — Server Components, streaming, error handling
• File uploads — Vercel Blob integration, progress tracking

Why it matters: Don't reinvent the wheel. Use battle-tested patterns.

Testing & Quality

Ensure code quality with comprehensive testing:

• Unit tests — Vitest for functions and utilities
• Component tests — React Testing Library patterns
• E2E tests — Playwright for critical user flows
• Troubleshooting — Common issues with proven solutions

Why it matters: Tests catch bugs before production. Troubleshooting guides save hours.

How to use these guides

For new developers

1. Start with Conventions — Learn naming, file structure, code style
2. Follow Git Workflow — Understand branching, commits, PRs
3. Practice with Recipes — Build common features using proven patterns
4. Reference Troubleshooting — When stuck, check for solutions

For experienced developers

1. Quick Reference — Lookup commands and patterns quickly
2. Architecture Diagrams — Understand system design and data flow
3. Creating Packages — Build new shared infrastructure
4. Testing & QA — Write comprehensive tests for new features

For team leads

1. Team Workspaces — Set up isolated development spaces
2. Conventions — Enforce standards across the team
3. Git Workflow — Establish PR review process
4. Architecture Diagrams — Plan system changes

Next steps

• Learn core concepts: Core Concepts →
• Explore packages: Shared Packages →
• Browse commands: Essential Commands →

---
title: "Guide Title"

description: "Brief description for SEO"
---

# Guide Title

**One-sentence benefit statement.**

<Callout type="info" title="Quick navigation">
[Skip to examples →](#examples)
</Callout>

## Why this matters

Pain points section with bullets.

**Solution statement with pattern.**

**Production-ready** with features.

## Use cases

When to use this guide.

## Quick Start

Step-by-step tutorial.

## Examples

Code examples with explanations.

## Next steps

Links to related guides.

<details>
<summary>For Developers: Advanced topics</summary>

Advanced content here.

</details>

import { something } from "@repo/package";

// Show complete, working examples
export function myFunction() {
  // With comments explaining why
  return something();
}

# 1. Build docs locally
pnpm --filter=docs build

# 2. Preview locally
pnpm --filter=docs start

# 3. Check for broken links
# (Use Docusaurus link checker)

# 4. Verify code examples
# Copy-paste and test all code

# Search for related content
grep -r "keyword" platform/apps/docs/content/

# Check if guide already exists
ls platform/apps/docs/content/400-guides/

# Create new guide file
touch platform/apps/docs/content/400-guides/120-my-guide.mdx

# Follow guide structure template
# Include examples, links, troubleshooting

# Create changeset
pnpm changeset
# Select: @repo/docs - patch
# Summary: "Add guide for [topic]"

# Commit with conventional format
git add .
git commit -m "docs: add guide for [topic]"

# Create PR
gh pr create --title "docs: add guide for [topic]"

# H1 - Page title only (one per page)

## H2 - Major sections

### H3 - Subsections

<h3 id="custom-id">H3 with custom anchor</h3>

\`\`\`typescript title="path/to/file.ts" // Code here \`\`\`

\`\`\`bash title="Terminal"

# Commands here

\`\`\`

<Callout type="info" title="Helpful tip">
Content here.
</Callout>

<Callout type="warning" title="Important warning">
Content here.
</Callout>

<Callout type="error" title="Critical warning">
Content here.
</Callout>

[Internal link](/docs/core-concepts/workspace-architecture) [External link](https://example.com)
[Relative link](./other-guide)

| Column 1 | Column 2 |
| -------- | -------- |
| Value 1  | Value 2  |

# 1. Update content
# Edit the guide file

# 2. Test examples
# Verify all code still works

# 3. Update version date
# Add "Last updated: YYYY-MM-DD" to frontmatter

# 4. Create changeset
pnpm changeset

# 5. Submit PR
gh pr create