26 KiB
NPM Commands Reference
Complete reference for all npm scripts in Changemaker Lite V2.
Overview
Changemaker Lite V2 uses npm scripts for development, building, testing, and database management. Scripts are defined in package.json files in two main directories:
- api/package.json - Backend API scripts (Express + Fastify)
- admin/package.json - Frontend GUI scripts (React + Vite)
This guide documents all available scripts, their usage, and common combinations.
API Scripts
Location: api/package.json
Development Scripts
npm run dev
Starts the Express API server in development mode with hot reload.
cd api
npm run dev
What it does:
- Runs
tsx watch src/server.ts - Auto-restarts on file changes (
.tsfiles) - Loads environment from
.env - Runs on port
API_PORT(default: 4000)
Output:
Server running on port 4000
Database connected
Redis connected
BullMQ worker started
Use when:
- Developing API endpoints
- Testing backend changes
- Debugging server code
npm run dev:media
Starts the Fastify Media API server in development mode.
cd api
npm run dev:media
What it does:
- Runs
tsx watch src/media-server.ts - Auto-restarts on file changes
- Runs on port
MEDIA_API_PORT(default: 4100)
Output:
Media API server running on port 4100
Database connected
Use when:
- Developing media features (video upload, reactions)
- Testing Media API endpoints
- Working on FFprobe integration
Build Scripts
npm run build
Compiles TypeScript to JavaScript for production.
cd api
npm run build
What it does:
- Runs
tsc --build - Outputs to
dist/directory - Type-checks all code
- Fails on type errors
Output:
dist/
├── server.js
├── media-server.js
└── modules/
├── auth/
├── users/
└── ...
Use when:
- Preparing for production deployment
- Verifying build succeeds
- Creating Docker images
npm run clean
Removes compiled JavaScript and build artifacts.
cd api
npm run clean
What it does:
- Deletes
dist/directory - Removes
*.tsbuildinfofiles
Use when:
- Starting fresh build
- Fixing build cache issues
- Cleaning up after development
Production Scripts
npm start
Runs the compiled API server (production mode).
cd api
npm start
What it does:
- Runs
node dist/server.js - Requires
npm run buildfirst - Uses production environment (
NODE_ENV=production)
Output:
Server running on port 4000
Database connected
Redis connected
Use when:
- Running in production (Docker)
- Testing production build locally
npm run start:media
Runs the compiled Media API server (production mode).
cd api
npm run start:media
What it does:
- Runs
node dist/media-server.js - Requires
npm run buildfirst
Use when:
- Running Media API in production
- Testing production Media API
Code Quality Scripts
npm run type-check
Type-checks TypeScript without emitting files.
cd api
npm run type-check
What it does:
- Runs
tsc --noEmit - Reports type errors
- Does NOT generate files
Output:
# Success (no output)
# Errors
src/modules/auth/auth.service.ts:45:12 - error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.
Use when:
- Before committing code
- In CI/CD pipeline
- Debugging type errors
npm run lint
Runs ESLint to check code style.
cd api
npm run lint
What it does:
- Runs
eslint src/ --ext .ts - Reports style violations
- Checks for common errors
Output:
# Success
✔ 150 files linted, 0 errors, 0 warnings
# Errors
src/modules/auth/auth.service.ts
45:12 error 'foo' is assigned a value but never used @typescript-eslint/no-unused-vars
Use when:
- Before committing code
- Enforcing code style
- Finding potential bugs
npm run lint:fix
Automatically fixes ESLint errors where possible.
cd api
npm run lint:fix
What it does:
- Runs
eslint src/ --ext .ts --fix - Auto-fixes style issues (formatting, imports, etc.)
- Reports unfixable errors
Use when:
- After writing new code
- Cleaning up formatting
- Before commit
npm run format
Formats code with Prettier.
cd api
npm run format
What it does:
- Runs
prettier --write "src/**/*.{ts,js,json}" - Formats all TypeScript, JavaScript, and JSON files
- Overwrites files in place
Use when:
- Standardizing code format
- After merge conflicts
- Team-wide formatting
npm run format:check
Checks if code is formatted correctly (CI).
cd api
npm run format:check
What it does:
- Runs
prettier --check "src/**/*.{ts,js,json}" - Reports unformatted files
- Does NOT modify files
Use when:
- In CI/CD pipeline
- Verifying format before commit
Database Scripts
npm run prisma:migrate
Creates and applies a new Prisma migration.
cd api
npm run prisma:migrate
# Or with name:
npx prisma migrate dev --name add_user_field
What it does:
- Prompts for migration name
- Generates SQL migration in
prisma/migrations/ - Applies migration to development database
- Regenerates Prisma Client
Output:
✔ Enter a name for the new migration: … add_user_field
Applying migration `20260213000000_add_user_field`
✔ Generated Prisma Client to ./node_modules/@prisma/client
Use when:
- Changing database schema
- Adding new models
- Modifying fields
npm run prisma:deploy
Applies pending migrations (production).
cd api
npm run prisma:deploy
What it does:
- Runs
prisma migrate deploy - Applies unapplied migrations only
- Does NOT create new migrations
- Safe for production
Output:
Environment variables loaded from .env
Datasource "db": PostgreSQL database "changemaker_v2_db"
2 migrations found in prisma/migrations
Applying migration `20260213000000_add_user_field`
All migrations have been successfully applied.
Use when:
- Deploying to production
- Applying migrations in Docker
- CI/CD deployment
npm run prisma:seed
Seeds database with initial data.
cd api
npm run prisma:seed
What it does:
- Runs
tsx prisma/seed.ts - Creates admin user
- Creates default settings
- Creates sample blocks
Output:
Running seed command `tsx prisma/seed.ts` ...
Seeding database...
Created default settings
Created admin user: admin@example.com
Created 10 sample blocks
Seed completed successfully
Use when:
- First-time setup
- After reset
- Populating test data
npm run prisma:studio
Opens Prisma Studio (database GUI).
cd api
npm run prisma:studio
What it does:
- Runs
prisma studio - Opens browser at http://localhost:5555
- Shows all tables and data
- Allows CRUD operations
Use when:
- Inspecting database
- Manual data editing
- Debugging data issues
npm run prisma:reset
Resets database (DESTRUCTIVE).
cd api
npm run prisma:reset
What it does:
- Drops all tables
- Re-applies all migrations
- Runs seed script
- DELETES ALL DATA
Output:
⚠️ You are about to drop the database 'changemaker_v2_db'
All data will be lost.
Do you want to continue? [y/N]: y
Database reset successful
Migrations applied
Seed completed
Use when:
- Starting fresh in development
- Fixing migration conflicts
- NEVER in production
npm run prisma:validate
Validates Prisma schema.
cd api
npm run prisma:validate
What it does:
- Runs
prisma validate - Checks schema syntax
- Verifies relations
- Does NOT touch database
Output:
# Success
The schema is valid ✔
# Errors
Error validating model "User": Field "foo" references unknown model "Bar"
Use when:
- After editing schema
- Before creating migration
- In CI/CD pipeline
npm run drizzle:push
Pushes Drizzle schema changes to database (Media API).
cd api
npm run drizzle:push
What it does:
- Runs
drizzle-kit push - Syncs
src/modules/media/db/schema.tsto database - Does NOT create migration files
- Direct schema sync
Output:
Reading config from drizzle.config.ts
Pushing schema to database...
✔ Schema pushed successfully
Use when:
- Changing Media API tables (videos, jobs, reactions)
- Rapid prototyping (no migrations)
- Development only
npm run drizzle:studio
Opens Drizzle Studio (database GUI for Media API).
cd api
npm run drizzle:studio
What it does:
- Runs
drizzle-kit studio - Opens browser at http://localhost:4983
- Shows Media API tables only
Use when:
- Inspecting media tables
- Debugging video data
- Manual media data editing
Testing Scripts
npm test
Runs all tests (when configured).
cd api
npm test
What it does:
- Runs Jest test suite
- Executes
*.test.tsfiles - Reports pass/fail
Note: Tests are part of Phase 15 (in progress).
npm run test:watch
Runs tests in watch mode.
cd api
npm run test:watch
What it does:
- Runs
jest --watch - Re-runs tests on file changes
npm run test:coverage
Runs tests with coverage report.
cd api
npm run test:coverage
What it does:
- Runs
jest --coverage - Generates coverage report in
coverage/
Utility Scripts
npm run env:validate
Validates required environment variables.
cd api
npm run env:validate
What it does:
- Checks
.envhas required vars - Uses Zod validation (from
config/env.ts) - Fails if vars missing/invalid
Output:
# Success
✔ Environment variables valid
# Errors
Error: Missing required environment variables:
- JWT_ACCESS_SECRET
- REDIS_PASSWORD
Use when:
- After editing .env
- Before deployment
- Debugging config issues
Admin Scripts
Location: admin/package.json
Development Scripts
npm run dev
Starts Vite development server with HMR.
cd admin
npm run dev
What it does:
- Runs
vite - Starts dev server on port
ADMIN_PORT(default: 3000) - Enables Hot Module Replacement (HMR)
- Proxies API requests to
VITE_API_URL
Output:
VITE v5.x.x ready in 500 ms
➜ Local: http://localhost:3000/
➜ Network: use --host to expose
Use when:
- Developing frontend components
- Testing UI changes
- Working on React code
Build Scripts
npm run build
Builds production-optimized bundle.
cd admin
npm run build
What it does:
- Runs
tsc --noEmit && vite build - Type-checks TypeScript
- Bundles JavaScript/CSS
- Optimizes assets (minify, tree-shake)
- Outputs to
dist/
Output:
vite v5.x.x building for production...
✓ 1245 modules transformed.
dist/index.html 0.45 kB
dist/assets/index-a1b2c3d4.js 245.67 kB │ gzip: 78.23 kB
dist/assets/index-e5f6g7h8.css 12.34 kB │ gzip: 3.45 kB
✓ built in 15.23s
Use when:
- Preparing for production deployment
- Creating Docker image
- Verifying build size
npm run preview
Previews production build locally.
cd admin
npm run preview
What it does:
- Runs
vite preview - Serves
dist/directory - Runs on port 4173 (Vite default)
Output:
➜ Local: http://localhost:4173/
➜ Network: use --host to expose
Use when:
- Testing production build
- Verifying optimizations
- Before deployment
Code Quality Scripts
npm run type-check
Type-checks TypeScript without emitting files.
cd admin
npm run type-check
What it does:
- Runs
tsc --noEmit - Reports type errors
- Checks all
.tsand.tsxfiles
Output:
# Success (no output)
# Errors
src/pages/UsersPage.tsx:123:45 - error TS2339: Property 'foo' does not exist on type 'User'.
Use when:
- Before committing code
- In CI/CD pipeline
- Debugging type errors
npm run lint
Runs ESLint to check code style.
cd admin
npm run lint
What it does:
- Runs
eslint src/ --ext .ts,.tsx - Reports style violations
- Checks React best practices
Output:
# Success
✔ 85 files linted, 0 errors, 0 warnings
# Errors
src/pages/UsersPage.tsx
123:45 error 'foo' is assigned a value but never used @typescript-eslint/no-unused-vars
200:10 warning Missing dependency in useEffect react-hooks/exhaustive-deps
Use when:
- Before committing code
- Enforcing code style
- Finding potential bugs
npm run lint:fix
Automatically fixes ESLint errors where possible.
cd admin
npm run lint:fix
What it does:
- Runs
eslint src/ --ext .ts,.tsx --fix - Auto-fixes style issues
- Reports unfixable errors
Use when:
- After writing new code
- Cleaning up formatting
- Before commit
npm run format
Formats code with Prettier.
cd admin
npm run format
What it does:
- Runs
prettier --write "src/**/*.{ts,tsx,css,json}" - Formats all source files
- Overwrites files in place
Use when:
- Standardizing code format
- After merge conflicts
- Team-wide formatting
npm run format:check
Checks if code is formatted correctly (CI).
cd admin
npm run format:check
What it does:
- Runs
prettier --check "src/**/*.{ts,tsx,css,json}" - Reports unformatted files
- Does NOT modify files
Use when:
- In CI/CD pipeline
- Verifying format before commit
Testing Scripts
npm test
Runs all tests (when configured).
cd admin
npm test
What it does:
- Runs Vitest test suite
- Executes
*.test.tsxand*.spec.tsxfiles - Reports pass/fail
Note: Tests are part of Phase 15 (in progress).
npm run test:watch
Runs tests in watch mode.
cd admin
npm run test:watch
What it does:
- Runs
vitest - Re-runs tests on file changes
npm run test:ui
Runs tests with UI (Vitest UI).
cd admin
npm run test:ui
What it does:
- Runs
vitest --ui - Opens browser with test UI
- Shows test results visually
npm run test:coverage
Runs tests with coverage report.
cd admin
npm run test:coverage
What it does:
- Runs
vitest --coverage - Generates coverage report in
coverage/
Utility Scripts
npm run clean
Removes build artifacts and cache.
cd admin
npm run clean
What it does:
- Deletes
dist/directory - Removes
node_modules/.vite/cache - Removes
tsconfig.tsbuildinfo
Use when:
- Starting fresh build
- Fixing build cache issues
- Cleaning up after development
Docker Commands
When running services in Docker, use docker compose exec to run npm scripts:
API in Docker
# Development server (already running via docker compose up)
docker compose logs -f api
# Type-check
docker compose exec api npm run type-check
# Prisma migrate
docker compose exec api npx prisma migrate dev --name add_field
# Prisma Studio
docker compose exec api npx prisma studio
# Prisma seed
docker compose exec api npx prisma db seed
# Drizzle push (Media API)
docker compose exec api npx drizzle-kit push
# Lint
docker compose exec api npm run lint
# Format
docker compose exec api npm run format
Admin in Docker
# Development server (already running via docker compose up)
docker compose logs -f admin
# Type-check
docker compose exec admin npm run type-check
# Lint
docker compose exec admin npm run lint
# Build
docker compose exec admin npm run build
Rebuild Containers
# Rebuild after package.json changes
docker compose build --no-cache api admin
# Restart services
docker compose restart api admin
Script Chaining
Sequential Execution (&&)
Run scripts in sequence, stop on first failure:
# Type-check, then build
cd api
npm run type-check && npm run build
# Lint, format, type-check
cd admin
npm run lint && npm run format && npm run type-check
# Full quality check before commit
cd api
npm run lint:fix && npm run format && npm run type-check && npm test
Parallel Execution (npm-run-all)
Install npm-run-all for parallel script execution:
# Install (project root)
npm install --save-dev npm-run-all
# Add to package.json
{
"scripts": {
"check": "npm-run-all --parallel type-check lint test"
}
}
# Run all checks in parallel
npm run check
Pre/Post Hooks
npm automatically runs pre* and post* scripts:
# package.json
{
"scripts": {
"prebuild": "npm run clean",
"build": "tsc --build",
"postbuild": "npm run copy-assets"
}
}
# Running npm run build executes:
# 1. npm run prebuild (clean)
# 2. npm run build (tsc)
# 3. npm run postbuild (copy-assets)
Common Script Combinations
Full Development Setup
# 1. Install dependencies
cd api && npm install && cd ..
cd admin && npm install && cd ..
# 2. Setup database
cd api
npx prisma migrate deploy
npx prisma db seed
cd ..
# 3. Start development servers
# Option A: Docker
docker compose up -d api admin
# Option B: Local
cd api && npm run dev # Terminal 1
cd admin && npm run dev # Terminal 2
Pre-Commit Quality Check
# API quality check
cd api
npm run lint:fix
npm run format
npm run type-check
# npm test # When tests available
cd ..
# Admin quality check
cd admin
npm run lint:fix
npm run format
npm run type-check
# npm test # When tests available
cd ..
# Commit if all pass
git add .
git commit -m "feat: add new feature"
Production Build
# Build API
cd api
npm run clean
npm run build
cd ..
# Build Admin
cd admin
npm run clean
npm run build
cd ..
# Build Docker images
docker compose build api admin
# Start production services
docker compose -f docker-compose.yml up -d api admin
Database Migration Workflow
# 1. Edit schema
cd api
vi prisma/schema.prisma
# 2. Validate schema
npx prisma validate
# 3. Create migration
npx prisma migrate dev --name add_user_field
# 4. Verify migration SQL
cat prisma/migrations/20260213000000_add_user_field/migration.sql
# 5. Test on clean database
npx prisma migrate reset # WARNING: Deletes data
npx prisma migrate deploy
npx prisma db seed
# 6. Commit migration
git add prisma/migrations/ prisma/schema.prisma
git commit -m "feat(db): add field to User model"
Database Inspection
# Prisma Studio (main API)
cd api
npx prisma studio
# Open http://localhost:5555
# Drizzle Studio (Media API)
cd api
npx drizzle-kit studio
# Open http://localhost:4983
# Direct PostgreSQL query
docker compose exec v2-postgres psql -U changemaker_v2 -d changemaker_v2_db
# Run SQL queries
Full Type Check
# Type-check both projects
cd api && npx tsc --noEmit && cd ..
cd admin && npx tsc --noEmit && cd ..
# Or create root script (package.json in project root)
{
"scripts": {
"type-check": "cd api && npm run type-check && cd ../admin && npm run type-check"
}
}
# Run from root
npm run type-check
CI/CD Integration
GitHub Actions Example
name: CI
on: [push, pull_request]
jobs:
api:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: '20'
- name: Install dependencies
working-directory: ./api
run: npm ci
- name: Type check
working-directory: ./api
run: npm run type-check
- name: Lint
working-directory: ./api
run: npm run lint
- name: Format check
working-directory: ./api
run: npm run format:check
- name: Test
working-directory: ./api
run: npm test
- name: Build
working-directory: ./api
run: npm run build
admin:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: '20'
- name: Install dependencies
working-directory: ./admin
run: npm ci
- name: Type check
working-directory: ./admin
run: npm run type-check
- name: Lint
working-directory: ./admin
run: npm run lint
- name: Format check
working-directory: ./admin
run: npm run format:check
- name: Test
working-directory: ./admin
run: npm test
- name: Build
working-directory: ./admin
run: npm run build
Troubleshooting
Script Not Found
Problem:
npm ERR! missing script: dev
Solution:
- Check
package.jsonhas the script defined - Verify you're in correct directory (
api/oradmin/) - Run
npm installto ensure dependencies installed
Permission Errors
Problem:
Error: EACCES: permission denied
Solution:
- Don't use
sudo npm(creates permission issues) - Fix npm permissions:
sudo chown -R $(whoami) ~/.npm - Or use nvm for user-level Node.js installation
Port Already in Use
Problem:
Error: listen EADDRINUSE: address already in use :::4000
Solution:
- Find and kill process using port:
lsof -ti:4000 | xargs kill -9 - Or change port in
.env:API_PORT=4002 - Or use Docker (isolated ports)
TypeScript Errors on Build
Problem:
src/modules/auth/auth.service.ts:45:12 - error TS2339
Solution:
- Fix type errors in code
- Or check
tsconfig.jsonis correct - Or update type definitions:
npm install --save-dev @types/node@latest
Prisma Migration Conflicts
Problem:
Error: P3005 The database schema is not in sync with the migration history
Solution:
- Development:
npx prisma migrate reset(DELETES DATA) - Production:
npx prisma migrate resolve --applied <migration_name> - Or create new migration to fix state
npm install Failures
Problem:
npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
Solution:
- Clear cache:
npm cache clean --force - Delete and reinstall:
rm -rf node_modules package-lock.json && npm install - Use
--legacy-peer-depsflag:npm install --legacy-peer-deps
Vite Build Errors
Problem:
Error: Could not resolve entry module (index.html)
Solution:
- Ensure
index.htmlexists inadmin/ - Check
vite.config.tshas correct root - Clear cache:
rm -rf node_modules/.vite && npm run dev
Best Practices
Script Naming Conventions
- dev - Development mode with hot reload
- build - Production build
- start - Run production build
- test - Run tests
- lint - Check code style
- lint:fix - Auto-fix code style
- format - Format code
- type-check - TypeScript validation
- clean - Remove build artifacts
Script Organization
Group related scripts:
{
"scripts": {
// Development
"dev": "tsx watch src/server.ts",
"dev:media": "tsx watch src/media-server.ts",
// Build
"build": "tsc --build",
"clean": "rm -rf dist",
// Quality
"type-check": "tsc --noEmit",
"lint": "eslint src/ --ext .ts",
"lint:fix": "eslint src/ --ext .ts --fix",
"format": "prettier --write \"src/**/*.ts\"",
// Database
"prisma:migrate": "prisma migrate dev",
"prisma:deploy": "prisma migrate deploy",
"prisma:seed": "tsx prisma/seed.ts"
}
}
Environment-Specific Scripts
Use cross-env for environment variables:
npm install --save-dev cross-env
{
"scripts": {
"dev": "cross-env NODE_ENV=development tsx watch src/server.ts",
"build": "cross-env NODE_ENV=production tsc --build",
"test": "cross-env NODE_ENV=test jest"
}
}
Script Documentation
Add comments in package.json:
{
"scripts": {
"// Development": "",
"dev": "tsx watch src/server.ts",
"// Build": "",
"build": "tsc --build",
"// Quality": "",
"type-check": "tsc --noEmit"
}
}
Quick Reference
API Scripts
npm run dev # Dev server (port 4000)
npm run dev:media # Media API dev (port 4100)
npm run build # Build for production
npm start # Run production server
npm run type-check # TypeScript validation
npm run lint # ESLint check
npm run lint:fix # ESLint auto-fix
npm run format # Prettier format
npx prisma migrate dev # Create migration
npx prisma migrate deploy # Apply migrations
npx prisma db seed # Seed database
npx prisma studio # Database GUI
npx drizzle-kit push # Push Media schema
Admin Scripts
npm run dev # Dev server (port 3000)
npm run build # Build for production
npm run preview # Preview production build
npm run type-check # TypeScript validation
npm run lint # ESLint check
npm run lint:fix # ESLint auto-fix
npm run format # Prettier format
npm test # Run tests
npm run test:ui # Test UI
Docker Scripts
docker compose exec api npm run type-check
docker compose exec api npx prisma migrate dev
docker compose exec admin npm run lint
docker compose build --no-cache api admin
Related Documentation
- Setup: Local Development Setup
- Workflow: Docker Workflow
- Database: Migrations Guide
- Testing: Testing Guide
- Code Style: Code Style Guide
- Debugging: Debugging Guide
Summary
You now know:
- ✅ All available npm scripts in API and Admin
- ✅ What each script does and when to use it
- ✅ How to run scripts in Docker containers
- ✅ How to chain scripts together
- ✅ Common script combinations for workflows
- ✅ How to troubleshoot script errors
- ✅ Best practices for script organization
Quick Start:
# Development
cd api && npm run dev
cd admin && npm run dev
# Pre-commit
cd api && npm run lint:fix && npm run type-check
cd admin && npm run lint:fix && npm run type-check
# Production build
cd api && npm run build
cd admin && npm run build