or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

build-system.md cloud-authentication.md configuration-management.md development-server.md index.md plugin-management.md project-management.md

tile.json

Project Management

Core commands for creating, building, and managing Gatsby projects throughout their lifecycle, from initial scaffolding to production deployment.

Capabilities

New Project Creation

Creates a new Gatsby project with interactive prompts or from a starter template.

/**
 * Create a new Gatsby project
 * @param rootPath - Directory name for the new project (optional)
 * @param starter - GitHub URL or name of starter template (optional)
 */
gatsby new [rootPath] [starter]

Usage Examples:

# Interactive creation with prompts for CMS, styling, plugins
gatsby new

# Create from default starter
gatsby new my-blog

# Create from specific starter
gatsby new my-site https://github.com/gatsbyjs/gatsby-starter-blog

# Create from GitHub shorthand
gatsby new my-site gatsbyjs/gatsby-starter-blog

Interactive Prompts Include:

Project name and directory
CMS integration (Contentful, WordPress, etc.)
Styling system (CSS, Sass, styled-components, etc.)
Additional plugins and features

Development Server

Starts a development server with hot reloading, file watching, and GraphQL explorer.

/**
 * Start development server with hot reloading
 * @param options - Development server configuration
 */
gatsby develop [options]

interface DevelopOptions {
  host?: string;        // -H, --host (default: localhost or env.GATSBY_HOST)
  port?: string;        // -p, --port (default: 8000 or env.PORT)
  open?: boolean;       // -o, --open browser automatically
  https?: boolean;      // -S, --https enable HTTPS (or env.HTTPS)
  certFile?: string;    // -c, --cert-file custom HTTPS cert
  keyFile?: string;     // -k, --key-file custom HTTPS key
  caFile?: string;      // --ca-file custom CA certificate
  graphqlTracing?: boolean;        // --graphql-tracing
  openTracingConfigFile?: string;  // --open-tracing-config-file
  inspect?: number;     // --inspect debugging port (default: 9229)
  inspectBrk?: number;  // --inspect-brk debugging with break
}

Usage Examples:

# Standard development server
gatsby develop

# Custom host and port
gatsby develop -H 0.0.0.0 -p 3000

# Enable HTTPS with custom certificates
gatsby develop --https --cert-file ./cert.pem --key-file ./key.pem

# Open browser automatically and enable debugging
gatsby develop --open --inspect

# Network access for testing on other devices
gatsby develop -H 0.0.0.0

Development Features:

Hot module replacement for instant updates
GraphQL explorer at /__graphql
Network access for cross-device testing
HTTPS support for secure contexts
Node.js debugging integration

Environment Variable Support:

The development server respects these environment variables:

interface EnvironmentVariables {
  GATSBY_HOST?: string;     // Default host (overrides localhost)
  PORT?: string;            // Default port (overrides 8000)
  HTTPS?: string;           // Enable HTTPS if "true"
  NODE_ENV?: string;        // Set to "development" automatically
}

Environment Variable Examples:

# Set via environment
export GATSBY_HOST=0.0.0.0
export PORT=3000
gatsby develop

# Inline environment variables
GATSBY_HOST=0.0.0.0 PORT=3000 gatsby develop

# Enable HTTPS via environment
HTTPS=true gatsby develop

Production Build

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

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

interface BuildOptions {
  prefixPaths?: boolean;           // --prefix-paths (use pathPrefix from config)
  noUglify?: boolean;              // --no-uglify (disable JS minification)
  profile?: boolean;               // --profile (React profiling)
  graphqlTracing?: boolean;        // --graphql-tracing
  openTracingConfigFile?: string;  // --open-tracing-config-file
  logPages?: boolean;              // --log-pages (hidden, experimental)
  writeToFile?: boolean;           // --write-to-file (hidden, experimental)
  functionsArch?: string;          // --functions-arch (serverless functions)
  functionsPlatform?: string;      // --functions-platform (serverless functions)
}

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 for performance analysis
gatsby build --profile

# Build with GraphQL tracing enabled
gatsby build --graphql-tracing

Build Output:

Static HTML files for all pages
Optimized JavaScript bundles with code splitting
CSS files with critical CSS inlining
Static assets (images, fonts, etc.) with optimization
Service worker for offline functionality (if configured)

Serve Production Build

Serves the production build locally for testing before deployment.

/**
 * Serve production build locally
 * @param options - Serve configuration options
 */
gatsby serve [options]

interface ServeOptions {
  host?: string;        // -H, --host (default: localhost)
  port?: string;        // -p, --port (default: 9000)
  open?: boolean;       // -o, --open browser automatically
  prefixPaths?: boolean; // --prefix-paths (use pathPrefix)
  openTracingConfigFile?: string; // --open-tracing-config-file
}

Usage Examples:

# Serve production build
gatsby serve

# Custom host and port
gatsby serve -H 0.0.0.0 -p 8080

# Open browser automatically
gatsby serve --open

# Serve with path prefixing
gatsby serve --prefix-paths

Clean Cache and Build Artifacts

Removes cached data and build artifacts to resolve development issues.

/**
 * Clean Gatsby cache and build artifacts
 * Removes .cache and public directories
 */
gatsby clean

Usage Examples:

# Clean all cache and build files
gatsby clean

Files Removed:

.cache/ directory (Gatsby's internal cache)
public/ directory (build output)
Webpack compilation cache
GraphQL schema cache

Common Use Cases:

Stale data not refreshing
GraphQL schema errors
Plugin or dependency issues
Cryptic build errors

REPL (Read-Eval-Print Loop)

Opens a Node.js REPL with Gatsby environment context for debugging and exploration.

/**
 * Open Node.js REPL with Gatsby context
 * Provides access to site data, configuration, and internal APIs
 */
gatsby repl

Usage Examples:

# Open Gatsby REPL
gatsby repl

Available Context:

babelrc - Babel configuration
components - Site components
dataPaths - Data layer paths
getNodes() - Access to GraphQL nodes
nodes - All GraphQL nodes
pages - Site pages
schema - GraphQL schema
siteConfig - Site configuration
staticQueries - Static queries

REPL Commands:

.exit - Exit the REPL
.help - Show available REPL commands
Ctrl+C (twice) - Exit the REPL
Ctrl+D - Exit the REPL

Example Usage:

// Explore all available nodes
nodes

// Get specific node types
getNodes().filter(node => node.internal.type === 'MarkdownRemark')

// Examine site configuration
siteConfig

// Inspect GraphQL schema
schema.getType('Site')

// View all pages
pages

Global Options

All project management commands support these global options:

interface GlobalOptions {
  verbose?: boolean;    // --verbose (detailed output)
  noColor?: boolean;    // --no-color, --no-colors (disable colored output)
  json?: boolean;       // --json (JSON logger output)
  help?: boolean;       // -h, --help (show command help)
  version?: boolean;    // -v, --version (show version information)
}

Usage Examples:

# Verbose output for debugging
gatsby develop --verbose
gatsby build --verbose

# Disable colored output (useful for CI/CD)
gatsby build --no-color

# JSON formatted output (for programmatic usage)
gatsby build --json

# Show help for specific commands
gatsby develop --help
gatsby build --help

# Show version information
gatsby --version

Error Handling

All project management commands include comprehensive error handling:

Configuration Errors: Invalid gatsby-config.js files
Dependency Issues: Missing or incompatible packages
Build Failures: Compilation and bundling errors
Network Issues: Problems connecting to external services
File System Errors: Permission and access issues

Error messages include:

Clear problem descriptions
Suggested solutions
Links to documentation
Stack traces in verbose mode

Version

Tile

Files