Build System

/**
 * Build Gatsby site for production deployment
 * @param options - Build configuration and optimization options
 */
gatsby build [options]

interface BuildOptions {
  prefixPaths?: boolean;           // --prefix-paths use pathPrefix from config
  noUglify?: boolean;              // --no-uglify disable JavaScript minification
  profile?: boolean;               // --profile enable React profiling
  graphqlTracing?: boolean;        // --graphql-tracing trace GraphQL resolvers
  openTracingConfigFile?: string;  // --open-tracing-config-file OpenTracing config
  logPages?: boolean;              // --log-pages log changed pages (experimental)
  writeToFile?: boolean;           // --write-to-file save page logs (experimental)
  functionsArch?: string;          // --functions-arch serverless function architecture
  functionsPlatform?: string;      // --functions-platform serverless function platform
}

# Standard production build
gatsby build

# Build with path prefixing for subdirectory deployment
gatsby build --prefix-paths

# Build without minification for debugging
gatsby build --no-uglify

# Build with React profiling enabled
gatsby build --profile

# Build with comprehensive tracing
gatsby build --graphql-tracing --open-tracing-config-file ./tracing-config.json

# Serverless functions configuration
gatsby build --functions-platform netlify --functions-arch arm64

/**
 * Path prefix configuration for subdirectory deployment
 * Uses pathPrefix setting from gatsby-config.js
 */
interface PathPrefixConfig {
  prefixPaths: boolean;    // Enable path prefixing during build
}

module.exports = {
  pathPrefix: "/my-app",  // Deploy to example.com/my-app/
  // ... other config
};

# Build with path prefixing
gatsby build --prefix-paths

# Also works with serve command
gatsby serve --prefix-paths

/**
 * Build optimization configuration
 * Controls minification, bundling, and debugging features
 */
interface OptimizationConfig {
  noUglify?: boolean;      // Disable JavaScript minification
  profile?: boolean;       // Enable React profiling bundle
}

# Disable minification for debugging production issues
gatsby build --no-uglify

# Enable React profiling for performance analysis
gatsby build --profile

# Combined debugging build
gatsby build --no-uglify --profile

/**
 * React profiling configuration
 * Enables React DevTools Profiler for performance analysis
 */
interface ProfilingConfig {
  profile: boolean;    // Enable React profiling bundle
}

# Build with React profiling
gatsby build --profile

# Serve profiling build for analysis
gatsby build --profile && gatsby serve

/**
 * GraphQL tracing and performance monitoring
 * Provides detailed resolver timing and query analysis
 */
interface GraphQLTracingConfig {
  graphqlTracing: boolean;          // Enable GraphQL resolver tracing
  openTracingConfigFile: string;    // OpenTracing configuration file path
}

# Enable GraphQL tracing
gatsby build --graphql-tracing

# With custom OpenTracing configuration
gatsby build --graphql-tracing --open-tracing-config-file ./tracing.yaml

# tracing.yaml
serviceName: "gatsby-build"
sampler:
  type: const
  param: 1
reporter:
  logSpans: true

/**
 * Serverless functions deployment configuration  
 * Platform-specific optimizations for function deployment
 */
interface ServerlessFunctionsConfig {
  functionsPlatform?: string;    // Target platform (netlify, vercel, etc.)
  functionsArch?: string;        // Target architecture (x64, arm64)
}

# Netlify deployment
gatsby build --functions-platform netlify

# Vercel with ARM64 architecture
gatsby build --functions-platform vercel --functions-arch arm64

# AWS Lambda optimized
gatsby build --functions-platform aws --functions-arch x64

public/
├── index.html              # Home page
├── about/index.html        # Static pages  
├── blog/                   # Generated pages
├── static/                 # Static assets
├── chunk-map.json          # Webpack chunk mapping
├── webpack.stats.json      # Build statistics
└── page-data/              # Page data JSON files

interface BuildEnvironmentVariables {
  CI?: string;                    // Optimize for CI environment
  GATSBY_EXPERIMENTAL_PAGE_BUILD_ON_DATA_CHANGES?: string;  // Incremental builds
  GATSBY_CPU_COUNT?: string;      // Control build parallelization
  NODE_OPTIONS?: string;          // Node.js memory and performance options
}

# CI-optimized build
CI=true gatsby build

# Increase Node.js memory for large sites
NODE_OPTIONS="--max-old-space-size=4096" gatsby build

# Control CPU usage
GATSBY_CPU_COUNT=2 gatsby build

# Incremental builds (experimental)
GATSBY_EXPERIMENTAL_PAGE_BUILD_ON_DATA_CHANGES=true gatsby build

interface BuildEnvironmentVariables {
  NODE_ENV: string;              // Set to "production" automatically
  PREFIX_PATHS?: string;         // Enable path prefixing ("true"/"1")
  REACT_PROFILE?: string;        // Enable React profiling ("true"/"1")
  CI?: string;                   // CI environment optimization
  GATSBY_TELEMETRY_DISABLED?: string;  // Disable telemetry
}