SerpentRace/Documentations/BUILD.md

SerpentRace Backend Build System

Overview

This document describes the comprehensive build system for the SerpentRace backend application. The build system handles TypeScript compilation, database migrations, asset management, testing, and deployment.

Quick Start

# Development build
npm run build

# Production build with full validation
npm run build:production

# Advanced build with migrations and tests
npm run build:advanced:prod

# Development server with hot reload
npm run dev

Build Scripts

Basic Build Commands

Command	Description
npm run build	Standard build: clean → compile → copy assets
npm run build:clean	Clean the dist directory
npm run build:compile	Compile TypeScript to JavaScript
npm run build:copy-assets	Copy non-TS files to dist directory
npm run build:docker	Build for Docker (no tests/migrations)

Production Build Commands

Command	Description
npm run build:production	Full production build with linting, tests, and migrations
npm run build:advanced	Advanced build script with custom options
npm run build:advanced:prod	Advanced production build with all validations
npm run build:advanced:ci	CI/CD friendly build (skips linting)

Development Commands

Command	Description
npm run dev	Start development server with hot reload
npm run watch	Watch mode TypeScript compilation
npm run typecheck	Type checking without code generation

Database Commands

Command	Description
npm run migration:run	Run pending database migrations
npm run migration:show	Show migration status
npm run migration:generate <name>	Generate new migration
npm run migration:create <name>	Create empty migration
npm run migration:revert	Revert last migration
npm run migration:full <name>	Create, generate, and run migration

Testing Commands

Command	Description
npm test	Run all tests
npm run test:watch	Run tests in watch mode
npm run test:coverage	Run tests with coverage report
npm run test:redis	Run Redis-specific tests

Deployment Commands

Command	Description
npm run deploy:prod	Build for production deployment
scripts/deploy.sh	Full Linux/Mac deployment script
scripts/deploy.bat	Full Windows deployment script

Advanced Build Script

The advanced build script (scripts/build.ts) supports various options:

# Basic advanced build
npm run build:advanced

# Production build with migrations and tests
npm run build:advanced:prod

# CI/CD build (skips linting, includes tests and migrations)
npm run build:advanced:ci

Build Options

• --migrations: Run database migrations during build
• --test: Run tests during build
• --skip-lint: Skip linting step
• --production: Enable production mode (strict validation)

Deployment Scripts

Linux/Mac Deployment

./scripts/deploy.sh [deploy|build-only|test-connections]

Options:

• deploy (default): Full deployment with validation
• build-only: Build without connection testing
• test-connections: Test database and Redis connections only

Windows Deployment

scripts\deploy.bat [deploy|build-only|test-connections]

Same options as Linux/Mac version.

Required Environment Variables

The deployment scripts require these environment variables:

DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=your_password
DB_NAME=serpentrace
JWT_SECRET=your_jwt_secret
REDIS_HOST=localhost
REDIS_PORT=6379

Build Process Flow

Standard Build (npm run build)

1. Clean - Remove previous build artifacts
2. Lint - Code quality checks (if configured)
3. Compile - TypeScript compilation
4. Copy Assets - Copy non-TS files to dist
5. Post-build - Validation and cleanup

Production Build (npm run build:production)

1. Clean - Remove previous build artifacts
2. Lint - Code quality checks
3. Test - Run test suite
4. Migrations - Apply database migrations
5. Compile - TypeScript compilation
6. Copy Assets - Copy non-TS files to dist
7. Validate - Ensure build integrity

Advanced Build (npm run build:advanced)

Provides fine-grained control over the build process with comprehensive logging and error handling.

Asset Management

The build system automatically copies these file types to the dist directory:

• .json files (configuration, data)
• .html files (templates)
• .css files (stylesheets)
• Image files (.png, .jpg, .jpeg, .gif, .svg, .ico)
• Font files (.woff, .woff2, .ttf, .eot)

Excluded directories:

• node_modules
• .git
• tests
• __tests__

TypeScript Configuration

The build system uses the following TypeScript settings:

• Target: ES2020
• Module: CommonJS
• Output Directory: ./dist
• Source Maps: Enabled
• Declarations: Enabled for type definitions
• Strict Mode: Enabled for type safety

Migration Management

Creating Migrations

# Create empty migration
npm run migration:create AddNewTable

# Generate migration from entity changes
npm run migration:generate AddNewTable

# Full migration workflow (create + generate + run)
npm run migration:full AddNewTable

Migration Best Practices

1. Always backup database before running migrations in production
2. Test migrations in development environment first
3. Use descriptive migration names
4. Review generated migrations before running them

Docker Integration

The build system is optimized for Docker deployments:

# Use build:docker for container builds
RUN npm run build:docker

# Or use production build for full validation
RUN npm run build:production

Troubleshooting

Common Issues

1. Build fails with "Cannot find module"

   • Run npm ci to ensure all dependencies are installed
   • Check TypeScript paths configuration

2. Migration errors during build

   • Verify database connection parameters
   • Ensure database exists and is accessible
   • Check migration files for syntax errors

3. Asset copying fails

   • Verify file permissions
   • Check disk space availability
   • Ensure source files exist

4. TypeScript compilation errors

   • Run npm run typecheck for detailed error messages
   • Check tsconfig.json configuration
   • Verify all type definitions are installed

Debug Mode

Enable verbose logging by setting the environment variable:

export DEBUG=serpentrace:*
npm run build:advanced

Performance Optimization

Build Performance Tips

1. Use npm ci instead of npm install in CI/CD
2. Enable TypeScript incremental compilation for development
3. Use --skip-lint in CI if linting is handled separately
4. Cache node_modules in CI/CD pipelines

Runtime Performance

The build system optimizes the output for production:

• Source maps for debugging (can be disabled in production)
• Type declarations for library usage
• Compressed and optimized JavaScript output

Monitoring and Logging

Build logs include:

• Timestamps for each build step
• Error details with stack traces
• Performance metrics (build duration)
• Validation results

Production builds create detailed logs in the logs/ directory.

Contributing

When modifying the build system:

1. Test changes with both development and production builds
2. Update this documentation for any new scripts or options
3. Ensure backward compatibility
4. Add appropriate error handling and logging

Support

For build system issues:

1. Check this documentation
2. Review error logs in the console
3. Verify environment variables are set correctly
4. Test with a clean node_modules installation