doctor

The doctor command inspects your project and reports on its health. Think of it as a quick sanity check — it catches the most common setup mistakes so you don't have to debug them yourself.

Usage

npx stackkit doctor

Run this after creating a project, after adding a module, or whenever something isn't working and you're not sure why.

What it checks

• Node.js version — Ensures you're running a compatible version
• Package manager — Detects which one you're using
• Framework detection — Identifies your project type (Next.js, Express, or React)
• Installed modules — Checks which StackKit modules are present
• Configuration files — Verifies tsconfig.json, ESLint config, and other required files exist
• Git repository — Checks whether git is initialized
• Environment variables — Confirms that variables listed in .env.example are present in your .env or .env.local

Example output

╔══════════════════════════════╗
║    🔍 StackKit Doctor Report  ║
╚══════════════════════════════╝

Project
  Type: nextjs
  Root: /home/user/projects/my-app
  Package Manager: pnpm

Runtime
  ✓ Node.js: v20.10.0

Modules
  Auth: better-auth
  Database: prisma

Files
  ✓ .env.example found
  ✓ .env.local found
  ✓ Prisma schema found
  ✓ Auth routes configured
  ✓ tsconfig.json found
  ✓ ESLint config found
  ✓ Git repository initialized

Environment Variables
  ✓ DATABASE_URL
  ✓ BETTER_AUTH_SECRET
  ✓ BETTER_AUTH_URL

Summary
  Errors:   0
  Warnings: 0

Suggestions
  • stackkit list    — View available modules

A clean report means your project is configured correctly and ready for development.

Options

Common use cases

After creating a project:

npx stackkit@latest create my-app
cd my-app
npx stackkit doctor

After adding a module:

npx stackkit add
npx stackkit doctor

In a CI pipeline:

npx stackkit doctor --strict --json

What to do when doctor reports errors

Missing environment variables

You have variables in .env.example that aren't in your .env file. Copy the missing ones over and fill them in:

# Add any missing variables from .env.example to your .env
cp .env.example .env.missing && diff .env .env.missing

Missing configuration files

A required file (like prisma/schema.prisma or auth routes) wasn't found. This usually means a module didn't install correctly. Try running add again:

npx stackkit add

Node.js version incompatible

Update Node.js to version 20 or higher. We recommend using a version manager like nvm or fnm.

Solution:

cp .env.example .env
# Edit .env with your values

Outdated Dependencies

Problem: Package versions don't match requirements

Solution:

npm install

Prisma Client Not Generated

Problem: @prisma/client not found

Solution:

npx prisma generate

Next Steps

• Troubleshooting - Full issue guide