Setup Dependencies and PNPM Catalogs

The Next.js Drizzle SaaS Kit uses pnpm as its package manager. PNPM is faster and more efficient than npm or yarn, especially for monorepos.

We use PNPM Catalogs to manage dependencies. This means that we can use the same version of a dependency across all packages in the monorepo.

Versions are defined in the pnpm-workspace.yaml file - and are referenced by their name in the package.json files of each package, followed by catalog: as version specifier.

{
  "dependencies": {
    "react": "catalog:",
    "next": "catalog:"
  }
}

We highly recommend reading the PNPM Catalogs documentation to understand how they work and how to use them.

Install All Dependencies

From the project root directory:

pnpm install

This command will:

1. Read pnpm-workspace.yaml to identify all packages
2. Install dependencies for all apps and packages
3. Create symlinks between workspace packages
4. Run the postinstall script to fix monorepo configurations
5. Create a node_modules folder in root and each package

Installation time: Typically 30-90 seconds depending on your internet speed and machine.

Understanding What Gets Installed

The installation process installs dependencies for:

Root workspace:

• Turborepo for monorepo management
• Development tools (TypeScript, Prettier, ESLint configs)

apps/web (Main application):

• Next.js 16
• React 19
• Better Auth
• Drizzle ORM
• Tailwind CSS 4
• React Hook Form
• Zod validation
• All internal workspace packages

apps/e2e (Tests):

• Playwright for E2E testing
• Test utilities

packages/ (Shared code):*

• Each package has its own dependencies
• UI components (Shadcn)
• Database schema and migrations
• Authentication logic
• Utilities and configurations

Workspace Packages

The monorepo uses workspace protocol to link packages:

{
  "dependencies": {
    "@kit/auth": "workspace:*",
    "@kit/ui": "workspace:*",
    "@kit/database": "workspace:*"
  }
}

This means packages reference each other locally, not from npm.

Post-Install Scripts

After dependency installation, several scripts run automatically:

1. Requirements Check

Verifies you have the minimum Node.js version:

# Runs automatically via preinstall script
pnpm run --filter scripts requirements

What it checks:

• Node.js version >= 20.10.0
• Exits with error if version is too old

2. Manypkg Fix

Automatically fixes common monorepo issues:

# Runs automatically via postinstall script
manypkg fix

What it fixes:

• Ensures consistent dependency versions across packages
• Fixes workspace protocol issues
• Validates package.json files

Updating Dependencies

Update specific package

If you want to update a specific dependency across all packages, you can use the following command:

# Update Next.js across all packages
pnpm up next -r --latest
# Update in specific workspace
pnpm --filter web up next

Check for outdated packages

Sometimes, you may want to check for outdated dependencies across all packages. You can use the following command to do so:

pnpm outdated -r

Adding New Dependencies

Add to root workspace

This should be done rarely, but if you need to add a dependency to the root workspace, you can use the following command:

# Dev dependency in global scope (rarely needed in root workspace)
pnpm add -D -w <package-name>
# Production dependency in global scope (rarely needed in root workspace)
pnpm add -w <package-name>

Add to specific app/package

If you want to add a dependency to a specific app or package, you can use the following command:

# Add to web app
pnpm --filter web add <package-name>
# Add to @kit/ui package
pnpm --filter @kit/ui add <package-name>
# Add dev dependency
pnpm --filter web add -D <package-name>

Examples

# Add a UI library to web app
pnpm --filter web add framer-motion
# Add a dev tool to all packages
pnpm add -D -r eslint-plugin-custom
# Add to specific package
pnpm --filter @kit/auth add jose

Dependency Management Best Practices

1. Keep dependencies up to date

# Check for updates weekly
pnpm outdated -r

2. Use workspace protocol for internal packages

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

3. Pin versions for critical dependencies

{
  "dependencies": {
    "next": "16.0.0"
  }
}

4. Use catalog for shared dependencies

This project uses catalog versioning for consistent versions:

{
  "dependencies": {
    "react": "catalog:",
    "next": "catalog:"
  }
}

Versions are defined in pnpm-workspace.yaml file in the root of the project.

Next: Project Setup →