# Package Architecture

> Understand the monorepo package structure and how to use @kit packages effectively.

*Canonical: https://makerkit.dev/docs/nextjs-prisma/project-structure/package-architecture*

---

Know which `@kit` packages exist, what they do, and how they depend on each other so you can import confidently and avoid circular dependency errors.

This page is part of the [Project Structure documentation](./overview).

The `packages/` directory contains reusable libraries prefixed with `@kit/`. Core packages like `@kit/database`, `@kit/rbac`, and `@kit/shared` sit at the foundation with zero dependencies on other `@kit` packages. Feature packages like `@kit/auth`, `@kit/billing-stripe`, and `@kit/organization-ui` build on top. Meta-packages group related functionality - `packages/organization/` contains `@kit/organization-core`, `@kit/organization-ui`, and `@kit/organization-hooks` as separate imports for tree-shaking.

A `@kit` package is a self-contained TypeScript library in the monorepo's `packages/` directory, imported via workspace protocol (e.g., `"@kit/ui": "workspace:*"`) and used across apps without npm publishing.

- **Create a new package when:** the code is used by multiple apps, has clear boundaries, and could benefit other developers. Run `pnpm turbo gen package` to scaffold it.
- **Avoid creating packages when:** the code is app-specific, used in only one place, or tightly coupled to a specific route. Keep it in `apps/web/` instead.
- **If unsure:** start in `apps/web/`. Extract to a package later if you find yourself duplicating code or needing it in another app.

## Package Overview

### Core Packages

**Foundation Layer**
- `@kit/database` - Prisma ORM, schema definitions, migrations
- `@kit/rbac` - Pure role/permission utilities (NO dependencies on other @kit packages)
- `@kit/shared` - Shared utilities and types
- `@kit/policies` - Authorization policies
- `@kit/action-middleware` - Server action middleware utilities

**Authentication & Authorization**
- `@kit/better-auth` - Better Auth configuration, auth utilities, server-side functions
- `@kit/auth` - Auth components and client-side utilities
- `@kit/otp` - One-time password generation and validation

**Organization Management** (nested packages in `packages/organization/`)
- `@kit/organization-core` - Organization lifecycle and helpers
- `@kit/organization-hooks` - Organization lifecycle hooks
- `@kit/organization-ui` - Organization settings UI components
- `@kit/organization-policies` - Organization authorization policies

**Account Management** (nested packages in `packages/account/`)
- `@kit/account-core` - Account management and switching
- `@kit/account-hooks` - Account lifecycle hooks
- `@kit/account-ui` - Account settings UI components

**UI & Styling**
- `@kit/ui` - Shadcn UI components, reusable UI primitives
- `@kit/i18n` - Internationalization and translations

**Billing** (nested packages in `packages/billing/`)
- `@kit/billing` - Billing types and utilities
- `@kit/billing-stripe` - Stripe integration
- `@kit/billing-polar` - Polar integration
- `@kit/web-billing-config` - Billing configuration

**Features**
- `@kit/storage` - File upload and storage providers
- `@kit/analytics` - Analytics integration
- `@kit/admin` - Admin dashboard and user management

**Monitoring** (nested packages in `packages/monitoring/`)
- `@kit/monitoring` - Monitoring core functions
- `@kit/sentry` - Sentry error tracking

**CMS** (nested packages in `packages/cms/`)
- `@kit/cms` - CMS client abstraction
- `@kit/cms-types` - CMS type definitions
- `@kit/keystatic` - Keystatic integration
- `@kit/wordpress` - WordPress integration

**Email** (nested packages in `packages/mailers/`)
- `@kit/mailers` - Email sending core utilities
- `@kit/nodemailer` - Nodemailer integration
- `@kit/resend` - Resend integration
- `@kit/email-templates` - React Email templates

## Package Dependency Flow

Understanding dependencies helps avoid circular dependency errors:

```
┌─────────────────────────────────────────┐
│     Pure Utilities (No Dependencies)   │
├─────────────────────────────────────────┤
│  @kit/rbac                             │
│  @kit/shared                           │
└──────────────┬──────────────────────────┘
               │
               ↓
┌─────────────────────────────────────────┐
│     Organization Layer                  │
├─────────────────────────────────────────┤
│  @kit/organization-*                   │
│  @kit/account-*                        │
│  (imports from @kit/rbac)              │
└──────────────┬──────────────────────────┘
               │
               ↓
┌─────────────────────────────────────────┐
│     Auth Layer                          │
├─────────────────────────────────────────┤
│  @kit/better-auth                      │
│  (imports from @kit/rbac and related   │
│   feature packages as needed)          │
└──────────────┬──────────────────────────┘
               │
               ↓
┌─────────────────────────────────────────┐
│     Feature Layer                       │
├─────────────────────────────────────────┤
│  @kit/billing-*                        │
│  @kit/storage                          │
│  @kit/policies                         │
└─────────────────────────────────────────┘
```

**Key Principle:** Lower layers cannot import from higher layers.

## Common Pitfalls

- **Importing from a higher layer**: If `@kit/rbac` tries to import from `@kit/auth`, you'll get circular dependency errors. Lower layers cannot depend on higher layers.
- **Exporting everything with `export *`**: This bloats bundles and exposes internal APIs. Export only public APIs from `src/index.ts`.
- **Mixing client and server code in one export**: Use separate entry points (`/client`, `/server`) in `package.json` exports to prevent server code leaking to the browser.
- **Forgetting to add the package to `pnpm-workspace.yaml`**: New packages must be registered or pnpm won't recognize them.
- **Using relative imports across packages**: Always use `@kit/package-name`, never `../../../packages/`. Relative imports break when packages move.
- **Creating packages for one-off code**: If code is used in one place, it belongs in `apps/web/`. Premature abstraction adds maintenance overhead.

{% faq
   title="Frequently Asked Questions"
   items=[
     {"question": "How do I import from a @kit package?", "answer": "Use the package name directly: import { Button } from @kit/ui. The workspace protocol resolves it automatically. No npm publishing required."},
     {"question": "What is the difference between @kit/auth and @kit/better-auth?", "answer": "@kit/auth contains React components (sign-in forms, MFA UI). @kit/better-auth contains the Better Auth server configuration, session management, and auth utilities."},
     {"question": "Can I add dependencies to a package?", "answer": "Yes. Run pnpm add <package> --filter @kit/your-package. The dependency is scoped to that package only."},
     {"question": "How do I check for circular dependencies?", "answer": "Run pnpm typecheck. Circular imports cause TypeScript errors. You can also use madge --circular packages/ for a visual report."},
     {"question": "Why are some packages split into -core, -ui, and -hooks?", "answer": "For tree-shaking. If you only need core logic, you do not bundle React components. This keeps builds smaller."},
     {"question": "Where is the Prisma schema?", "answer": "The schema lives in packages/database/src/prisma/schema.prisma. Migrations are in the same directory. See the Database documentation."}
   ]
/%}

---

**Next:** [Configuration →](../configuration/overview)