Project Structure

A typical aidimension project uses a monorepo layout. This guide shows the recommended structure for teams building production apps.

For single apps#

If you're building one app, a flat structure works fine:

my-app/
├── app/                  # Next.js app router
│   ├── (marketing)/     # Public pages (landing, pricing, blog)
│   │   └── page.tsx
│   ├── (dashboard)/     # Authed app (admin, settings)
│   │   └── dashboard/
│   │       └── page.tsx
│   ├── api/             # Route handlers
│   ├── layout.tsx
│   ├── page.tsx
│   └── globals.css
├── components/
│   ├── ui/              # aidimension components (Button, Card, etc.)
│   ├── marketing/       # Marketing-specific components
│   └── dashboard/       # Dashboard-specific components
├── lib/
│   ├── utils.ts         # cn() helper
│   └── api.ts           # API client
├── content/             # MDX content (if docs site)
├── public/
├── package.json
├── tailwind.config.ts
└── tsconfig.json

For monorepos (recommended for teams)#

Use pnpm workspaces, Turborepo, or Nx:

aidimension-monorepo/
├── apps/
│   ├── web/             # Marketing site
│   ├── app/             # Authed product
│   ├── docs/            # Documentation site
│   └── api/             # Backend (Hono, Express, etc.)
├── packages/
│   ├── ui/              # Shared components (aidimension/ui re-exports)
│   ├── config/          # Shared tsconfig, eslint, tailwind presets
│   ├── database/        # Drizzle/Prisma client
│   ├── email/           # React Email templates
│   ├── analytics/       # PostHog, Plausible
│   └── typescript-config/
├── tooling/
│   ├── eslint-config/
│   ├── tailwind-preset/
│   └── tsconfig/
├── turbo.json
├── pnpm-workspace.yaml
└── package.json

Where to put aidimension#

There are three common patterns:

Pattern 1 — Direct dependency#

apps/web and apps/app both depend on @aidimension/ui:

{
  "dependencies": {
    "@aidimension/ui": "workspace:*"
  }
}

Pros: simple, no extra code Cons: can't customize per app without forking

Pattern 2 — Shared ui package#

Create packages/ui that re-exports aidimension + your customizations:

// packages/ui/src/index.ts
export * from "@aidimension/ui";
export { Button } from "./button";   // your override

Pros: customize once, use everywhere Cons: more code to maintain

Pattern 3 — Copy in#

Each app copies components it needs via the CLI:

cd apps/web && npx @aidimension/cli@latest add button card dialog
cd apps/app && npx @aidimension/cli@latest add button card dialog sheet

Pros: full ownership per app Cons: updates are manual

File naming#

aidimension follows the Next.js / Vercel conventions:

• kebab-case.tsx for files (user-menu.tsx)
• PascalCase.tsx for components (UserMenu.tsx) — actually the file is user-menu.tsx, the component inside is UserMenu
• _components/ for private folders (Next.js convention)
• (group)/ for route groups that don't affect URL

Component organization#

Inside components/ui/, keep one component per file:

components/
├── ui/
│   ├── button.tsx
│   ├── card.tsx
│   ├── dialog.tsx
│   ├── input.tsx
│   └── ...
├── forms/
│   ├── login-form.tsx
│   └── signup-form.tsx
└── layout/
    ├── header.tsx
    └── footer.tsx

If a component needs multiple internal files, use a folder:

components/
└── ui/
    ├── button/
    │   ├── button.tsx       # main component
    │   ├── button.test.tsx
    │   ├── button.stories.tsx
    │   └── index.ts
    └── card/
        └── ...

Next steps#

• Installation — three ways to add aidimension
• UI Kit overview — what's in the kit
• Quick Start — back to the 5-minute guide