Package Architecture

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

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.

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,              │
│   @kit/organizations)                  │
└──────────────┬──────────────────────────┘
               │
               ↓
┌─────────────────────────────────────────┐
│     Feature Layer                       │
├─────────────────────────────────────────┤
│  @kit/billing-hooks                    │
│  @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.

Frequently Asked Questions

How do I import from a @kit package?

Use the package name directly: import { Button } from @kit/ui. The workspace protocol resolves it automatically. No npm publishing required.

What is the difference between @kit/auth and @kit/better-auth?

@kit/auth contains React components (sign-in forms, MFA UI). @kit/better-auth contains the Better Auth server configuration, session management, and auth utilities.

Can I add dependencies to a package?

Yes. Run pnpm add <package> --filter @kit/your-package. The dependency is scoped to that package only.

How do I check for circular dependencies?

Run pnpm typecheck. Circular imports cause TypeScript errors. You can also use madge --circular packages/ for a visual report.

Why are some packages split into -core, -ui, and -hooks?

For tree-shaking. If you only need core logic, you do not bundle React components. This keeps builds smaller.

Where is the Prisma schema?

The schema lives in packages/database/src/prisma/schema.prisma. Migrations are in the same directory. See the Database documentation.

Next: Configuration →