Development Environment

Set up your ShipKit development environment

Development Environment Setup

Get your ShipKit development environment up and running quickly with these setup instructions.

Prerequisites

Node.js

Node.js 20.x or later required

PNPM

Fast, disk space efficient package manager

Quick Start

# Clone the repository
git clone https://github.com/your-username/shipkit.git
cd shipkit

# Install dependencies
pnpm install

# Set up environment variables
cp .env.example .env.local

# Start the development server
pnpm dev

Environment Variables

Create a .env.local file with these variables:

# App
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Authentication
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-development-secret

# Database
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/shipkit

# Email
RESEND_API_KEY=re_development_key

# Content Management
BUILDER_PUBLIC_KEY=your-builder-key
PAYLOAD_SECRET=your-payload-secret

Database Setup

ShipKit uses PostgreSQL as its primary database:

# Start PostgreSQL with Docker
docker compose up db -d

# Run migrations
pnpm db:migrate

# Seed the database (optional)
pnpm db:seed

Development Tools

VS Code Extensions

We recommend these extensions for the best development experience:

  • ESLint
  • Prettier
  • Tailwind CSS IntelliSense
  • TypeScript Vue Plugin
  • GitLens

Configuration

Add this to your VS Code settings:

{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib"
}

Local Services

ShipKit requires these services for full functionality:

# Start all services
docker compose up -d

# Or start individual services
docker compose up db -d    # PostgreSQL
docker compose up redis -d # Redis (for caching)
docker compose up s3 -d    # MinIO (S3-compatible storage)

Development Commands

# Start development server
pnpm dev

# Type checking
pnpm type-check

# Linting
pnpm lint

# Testing
pnpm test
pnpm test:e2e

# Build
pnpm build

# Clean
pnpm clean

Git Hooks

We use Husky for Git hooks:

  • Pre-commit: Runs linting and type checking
  • Pre-push: Runs tests
# Install Husky
pnpm prepare

Troubleshooting

Common issues and solutions:

  1. Database Connection Issues

    # Reset database
docker compose down -v
docker compose up db -d
pnpm db:migrate

  2. Port Conflicts

    # Check ports in use
lsof -i :3000
lsof -i :5432

  3. Cache Issues

    # Clear all caches
pnpm clean
pnpm install

Best Practices

  • Keep dependencies up to date
  • Follow the coding style guide
  • Write tests for new features
  • Use conventional commits
  • Document new features
  • Keep the development environment clean
  • Regular dependency updates
  • Use feature branches