tessl/npm-gatsby-cli

Command-line interface for creating, developing, building and managing Gatsby static sites

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Build System

Name: tessl/npm-gatsby-cli
Author: tessl

Production build operations with optimization, bundling, profiling, and tracing capabilities for creating deployment-ready Gatsby sites.

Capabilities

Production Build

Compiles and optimizes the Gatsby site for production deployment with comprehensive bundling and optimization.

/**
 * 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
}

Usage Examples:

# 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 Support

Support for deploying Gatsby sites to subdirectories or CDN paths.

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

Configuration in gatsby-config.js:

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

Usage Examples:

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

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

Use Cases:

GitHub Pages deployment
Subdirectory hosting
CDN deployment with custom paths
Multi-site deployments

Build Optimization Control

Fine-grained control over build optimization and debugging options.

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

Usage Examples:

# 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

Optimization Details:

Minification: JavaScript and CSS compression
Tree Shaking: Removal of unused code
Code Splitting: Automatic chunk generation
Image Optimization: WebP conversion and responsive images
Critical CSS: Above-the-fold CSS inlining

Performance Profiling

React profiling integration for performance analysis and optimization.

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

Usage Examples:

# Build with React profiling
gatsby build --profile

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

Profiling Workflow:

Build with --profile flag
Serve the built site
Open React DevTools Profiler
Record user interactions
Analyze component render times
Identify performance bottlenecks

GraphQL Tracing

Detailed performance analysis of GraphQL queries and data layer operations.

/**
 * 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
}

Usage Examples:

# Enable GraphQL tracing
gatsby build --graphql-tracing

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

OpenTracing Configuration Example:

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

Tracing Benefits:

Identify slow GraphQL resolvers
Profile data fetching performance
Debug build-time data issues
Optimize query complexity
Monitor third-party data sources

Serverless Functions Support

Configuration for serverless function deployment platforms.

/**
 * 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)
}

Usage Examples:

# 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

Supported Platforms:

Netlify Functions
Vercel Functions
AWS Lambda
Cloudflare Workers
Custom adapters

Build Output Analysis

Understanding and analyzing the build output structure.

Standard Build Output:

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

Build Artifacts:

HTML Files: Pre-rendered static pages
JavaScript Bundles: Code-split application chunks
CSS Files: Optimized stylesheets with critical CSS
Static Assets: Images, fonts, and other resources
Page Data: JSON files for client-side routing
Service Worker: Offline functionality (if configured)

Build Performance Optimization

Strategies and options for optimizing build performance.

Build Environment Variables:

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
}

Usage Examples:

# 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

Performance Tips:

Use incremental builds for large sites
Optimize images during development
Implement proper caching strategies
Monitor build metrics and bundle sizes
Use webpack-bundle-analyzer for bundle analysis

Build Validation

The build process includes comprehensive validation and error checking:

Configuration Validation:

gatsby-config.js syntax and options
Plugin configuration correctness
GraphQL schema validation
Asset reference verification

Content Validation:

Markdown syntax checking
Image reference validation
Internal link verification
SEO meta tag validation

Performance Warnings:

Large bundle size alerts
Unused code detection
Image optimization suggestions
Performance metric reporting

Environment Variables

Build process respects these environment variables:

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
}