🛠️ @goobits/sveltekit-dev-tools

CLI and programmatic tools for SvelteKit + PostgreSQL development - process management, database operations, and testing utilities.

✨ Key Features

• 🎯 Auto-Detection - Discovers SvelteKit config, database type, and available ports
• 🔄 Process Management - PM2-based start/stop for web and API servers
• 🗄️ Database CLI - PostgreSQL operations (setup, migrate, backup, snapshots, seeding)
• ✅ Pre-Command Health Checks - Validate environment before expensive operations (NEW in v0.4.0)
• 🧪 Test Infrastructure - Pre-test health checks and service validation
• ⚙️ Interactive Setup - Preset-based configuration generator
• 📦 Modular API - Import only what you need for custom tooling

🚀 Quick Start

# Install
pnpm add -D @goobits/sveltekit-dev-tools

# Auto-detect and start (no config required)
npx devtools dev

# Or use interactive setup
npx devtools init --preset=postgres

Basic Commands

devtools dev               # Start all processes
devtools stop              # Stop all processes
devtools status            # Show dashboard (processes + database)
devtools logs              # View process logs
devtools logs --follow     # Stream logs in real-time

# Database operations
devtools db setup          # Initialize schema
devtools db migrate        # Run migrations
devtools db snapshot       # Create quick snapshot
devtools db restore        # Restore from snapshot
devtools db seed           # Populate with data

Configuration

Create devtools.config.ts:

import type { DevToolsConfig } from '@goobits/sveltekit-dev-tools/cli';

export default {
  appName: 'my-app',

  // Process management with PM2
  pm2: {
    processes: [
      {
        name: 'web',
        script: 'pnpm',
        args: 'dev',
        cwd: process.cwd(),
      },
    ],
  },

  // Database configuration
  database: {
    databaseUrlEnvVar: 'DATABASE_URL',
    schemaFile: './schema.sql',
    migrationScript: './migrate.ts',
    seedFile: './seed.ts', // Optional
  },
} satisfies DevToolsConfig;

📚 TypeScript API

Import modules for custom scripts and tooling:

PM2 Process Management

import { PM2Manager } from '@goobits/sveltekit-dev-tools/pm2';

const manager = new PM2Manager({
  processes: [
    { name: 'web', script: 'pnpm', args: 'dev' },
    { name: 'api', script: 'node', args: 'server.js' },
  ],
});

// Automatic connection lifecycle
await manager.withConnection(async () => {
  await manager.start({ restart: false });
  const status = await manager.status();
  console.log(status); // [{ name: 'web', running: true, pid: 1234 }]
});

Database CLI Framework

import { DatabaseCLI } from '@goobits/sveltekit-dev-tools/database';

const cli = new DatabaseCLI({
  databaseUrlEnvVar: 'DATABASE_URL',
  schemaFile: './schema.sql',
  migrationScript: './migrate.ts',
  customCommands: {
    'list-users': async (client) => {
      const result = await client.query('SELECT * FROM users');
      console.table(result.rows);
    },
  },
});

await cli.run(['list-users']); // Custom command

Pre-Command Health Checks (NEW in v0.4.0)

import {
  DatabaseCLI,
  createEnvVarCheck,
  createPortCheck,
  createDatabaseConnectionCheck
} from '@goobits/sveltekit-dev-tools/database';

const cli = new DatabaseCLI({
  databaseUrlEnvVar: 'DATABASE_URL',

  // Health checks run before expensive operations (migrate, reset, seed)
  preCommandChecks: [
    createEnvVarCheck('DATABASE_URL', 'PostgreSQL connection string'),
    createPortCheck(5432, 'PostgreSQL'),
    createDatabaseConnectionCheck(async () => pool.connect(), 'PostgreSQL')
  ],

  // Which commands trigger checks (default: migrate, reset, seed)
  preCheckCommands: ['migrate', 'reset', 'seed']
});

// Migrations now run health checks first - fail fast if environment is broken
await cli.run(['migrate']);

Pre-Test Health Checks

import { PreTestCheck, checkPort } from '@goobits/sveltekit-dev-tools/test';

const checker = new PreTestCheck({
  checks: [
    {
      name: 'Web Server',
      test: async () => ({
        name: 'Web Server',
        status: await checkPort(3000) ? 'ok' : 'error',
        message: 'Checking port 3000',
        required: true,
      }),
      required: true,
    },
  ],
});

const success = await checker.run();
if (!success) process.exit(1);

Auto-Detection

import { detectAll } from '@goobits/sveltekit-dev-tools/auto-detect';

const detected = await detectAll(process.cwd());

console.log(detected.sveltekit.devPort);       // 5173
console.log(detected.database.databaseType);   // 'postgres'
console.log(detected.ports.available);         // [3000, 3001, ...]

CLI Utilities

import {
  printHeader,
  printSuccess,
  printError,
  colors,
} from '@goobits/sveltekit-dev-tools/cli';

printHeader('Build Script');
printSuccess('Build completed');
printError('Failed to compile');
console.log(`${colors.cyan}Custom output${colors.reset}`);

🔧 Advanced Usage

Full Configuration Example

import type { DevToolsConfig } from '@goobits/sveltekit-dev-tools/cli';

export default {
  appName: 'my-app',

  pm2: {
    processes: [
      {
        name: 'web',
        script: 'pnpm',
        args: ['run', 'dev'],
        env: { NODE_ENV: 'development' },
      },
      {
        name: 'worker',
        script: 'node',
        args: ['worker.js'],
      },
    ],
    logDir: '.dev/logs',
    tmpDir: '.dev/tmp',
  },

  database: {
    databaseUrlEnvVar: 'DATABASE_URL',
    schemaFile: './schema.sql',
    migrationScript: './migrate.ts',
    seedFile: './seed.ts',
  },

  setup: {
    envTemplate: '.env.example',
    requiredEnvVars: [
      { name: 'DATABASE_URL', required: true },
      { name: 'API_KEY', required: true },
    ],
    dependencies: [
      { name: 'Node.js', command: 'node --version', minVersion: '18.0.0' },
      { name: 'PostgreSQL', command: 'psql --version' },
    ],
  },

  test: {
    checks: [
      {
        name: 'Database Connection',
        test: async () => { /* check logic */ },
        required: true,
      },
    ],
  },
} satisfies DevToolsConfig;

Package.json Scripts

{
  "scripts": {
    "dev": "devtools dev",
    "stop": "devtools stop",
    "db:setup": "devtools db setup",
    "db:migrate": "devtools db migrate",
    "db:snapshot": "devtools db snapshot"
  }
}

Database Operations

# Setup and seeding
devtools db setup          # Create database + apply schema
devtools db seed           # Populate with development data

# Snapshots for testing
devtools db snapshot clean # Save current state
devtools db restore clean  # Restore to saved state

# Maintenance
devtools db backup         # Full pg_dump backup (.dev/backups/)
devtools db vacuum         # Optimize (VACUUM ANALYZE)
devtools db shell          # Interactive psql
devtools db diff           # Show pending migrations

⚙️ Module Exports

| Import Path | Exports | Use Case | |-------------|---------|----------| | @goobits/sveltekit-dev-tools/pm2 | PM2Manager | Process lifecycle management | | @goobits/sveltekit-dev-tools/database | DatabaseCLI | Database operations and custom commands | | @goobits/sveltekit-dev-tools/test | PreTestCheck, checkPort | Service validation before tests | | @goobits/sveltekit-dev-tools/cli | printHeader, colors | Terminal output formatting | | @goobits/sveltekit-dev-tools/setup | SetupManager | Environment and dependency setup | | @goobits/sveltekit-dev-tools/auto-detect | detectAll | Project configuration discovery | | @goobits/sveltekit-dev-tools/presets | sveltekitPostgres, listPresets, getPresetNames, applyPreset | Runtime preset configurations and discovery |

📖 Documentation

CLI Reference

• CLI Commands - All commands and options
• Database Commands - PostgreSQL operations reference
• Process Management - PM2 workflow guide
• Init Command - Interactive setup wizard

API Reference

• PM2 Manager - Process management API
• Database CLI - Database framework API
• Test Infrastructure - Health check API
• Setup Framework - Project setup API
• Auto-Detection - Detection API
• CLI Utilities - Terminal output API
• Presets - Runtime presets API

Guides

• Quick Start Guide - 30 seconds to 15 minutes
• Choosing Presets - Preset selection guide
• Architecture - Design decisions and structure
• Full Documentation Index - All documentation

🧪 Development

# Setup
pnpm add

# Build package
pnpm build

# Watch mode
pnpm dev

# Type checking
pnpm type-check

See CONTRIBUTING.md for development guidelines.

🔗 Related Projects

• @goobits/markdown-docs - Markdown documentation with code tabs
• @goobits/forms - SvelteKit form components

📝 License

MIT - see LICENSE for details

💡 Support

• Documentation: docs/README.md
• Examples: examples/
• Issues: GitHub Issues
• Changelog: CHANGELOG.md