Monorepo Architecture for FlatWP Projects

FlatWP uses a monorepo to keep Next.js and WordPress plugin development in sync. Here’s why and how it works.

Why Monorepo?

In a headless setup, you’re maintaining:

• Next.js frontend
• WordPress plugin for webhooks/admin
• Shared TypeScript types
• Configuration files

Keeping these in separate repos means:

• Types get out of sync
• Changes require coordinating multiple PRs
• Testing becomes complicated
• New developers need to clone multiple repos

A monorepo solves all of this.

Our Structure

flatwp/
├── apps/
│   ├── web/           # Next.js app
│   └── wp-plugin/     # WordPress plugin
├── packages/
│   ├── types/         # Shared TS types
│   └── config/        # ESLint, TS configs
├── package.json
└── pnpm-workspace.yaml

Shared Types in Action

When you generate GraphQL types, both the Next.js app and WordPress plugin admin UI access them:

// packages/types/src/wordpress.ts
export interface Post {
  id: string;
  title: string;
  slug: string;
}

// Used in apps/web
import { Post } from '@flatwp/types';

// Used in apps/wp-plugin admin UI
import { Post } from '@flatwp/types';

One source of truth, no duplication.

pnpm Workspaces

We use pnpm for fast, efficient dependency management:

# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'

Run commands across all workspaces:

pnpm dev          # Start all apps in dev mode
pnpm build        # Build all apps
pnpm type-check   # Type check everything

Turborepo for Speed

Turborepo caches builds and runs tasks in parallel:

// turbo.json
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "build/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

Second builds are near-instant thanks to caching.

Benefits We’ve Seen

• Faster onboarding: One clone, one install
• Atomic changes: Update types + usage in one commit
• Better CI: Test everything together
• Shared tooling: One ESLint config, one Prettier config

When NOT to Monorepo

If you’re just starting and want to move fast, skip the monorepo initially. Build the Next.js app first, add the WordPress plugin later.

But once you’re serious about shipping, the monorepo pays dividends.