gatsby-plugin-create-client-paths

Note: This plugin became obsolete in recent versions of Gatsby. Modern Gatsby applications should use the File System Route API with catch-all routes ([...].js) instead.

Gatsby plugin for creating "hybrid" applications that combine statically rendered pages with client-only routes. These client-only paths exist on the client side and do not correspond to physical HTML files in the built assets, enabling dynamic application sections alongside static content.

Package Information

• Package Name: gatsby-plugin-create-client-paths
• Package Type: npm
• Language: JavaScript
• Installation: npm install gatsby-plugin-create-client-paths
• Gatsby Version: Requires Gatsby ^4.0.0-next (peer dependency)

Core Usage

This plugin is configured in gatsby-config.js and works through Gatsby's plugin system. There are no direct imports or API calls - the plugin operates through Gatsby's build-time lifecycle hooks, specifically onCreatePage, which is called for every page Gatsby discovers during the build process.

Plugin Configuration:

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-create-client-paths',
      options: { 
        prefixes: ['/app/*', '/dashboard/*', '/profile/*'] 
      }
    }
  ]
}

Basic Usage

// gatsby-config.js - Single client path
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-create-client-paths',
      options: { 
        prefixes: ['/app/*'] 
      }
    }
  ]
}

With this configuration:

• All paths starting with /app/ become client-only routes
• The page at src/pages/app.js handles all /app/* paths
• Client-side routing manages navigation within the /app/* space
• Static pages continue to work normally outside the client-only prefixes

Architecture

This plugin integrates with Gatsby's build-time page creation process through the onCreatePage lifecycle hook:

• Plugin Registration: Configured in gatsby-config.js with path prefix patterns
• Page Processing: During build, Gatsby calls onCreatePage for each discovered page
• Path Matching: Plugin compares page paths against configured prefixes using regex patterns
• Client Route Creation: Matching pages get matchPath property set, enabling client-side routing
• Build Output: Final build includes both static HTML files and client-only route configurations

The plugin operates entirely at build time - there's no runtime JavaScript added to the client bundle. It modifies Gatsby's internal page objects during the build process to enable client-side routing for specified path patterns.

Capabilities

Plugin Options Configuration

Configures the plugin through Gatsby's plugin system with path prefix patterns.

/**
 * Plugin options configuration object
 */
interface PluginOptions {
  /** Array of path prefix patterns for client-only routes. Must be glob patterns ending with '/*' */
  prefixes: string[];
}

Prefix Pattern Requirements:

• Must start with / (forward slash)
• Must end with /* (glob pattern)
• Examples: '/app/*', '/dashboard/*', '/auth/*'
• Invalid: 'app/*', '/app', '/app/**'

Gatsby Plugin Implementation

The plugin implements Gatsby's onCreatePage lifecycle hook to process pages and configure client-only routing.

/**
 * Gatsby onCreatePage lifecycle hook implementation
 * Processes pages to set up client-only routing for matching prefixes
 * @param pluginArgs - Gatsby page creation context
 * @param pluginOptions - Plugin configuration options
 */
function onCreatePage(
  pluginArgs: {
    page: {
      path: string;
      matchPath?: string;
    };
    actions: {
      createPage: (page: object) => void;
    };
  },
  pluginOptions: PluginOptions
): void;

Error Handling

The plugin validates prefix patterns during execution and throws errors for invalid patterns:

/**
 * Validation error thrown for invalid prefix patterns
 * Thrown when prefix doesn't match required format: /path/*
 */
class Error {
  constructor(message: string);
}

Common Validation Errors:

• Prefix doesn't start with /: "app/*" → Invalid

  Error: Plugin "gatsby-plugin-create-client-paths" found invalid prefix pattern: app/*

• Prefix doesn't end with /*: "/app" → Invalid

  Error: Plugin "gatsby-plugin-create-client-paths" found invalid prefix pattern: /app

• Missing glob pattern: "/app/path" → Invalid

  Error: Plugin "gatsby-plugin-create-client-paths" found invalid prefix pattern: /app/path

• Empty prefix: "" → Invalid
• Multiple glob patterns: "/app/*/*" → Invalid

Troubleshooting:

• Ensure each prefix follows the exact pattern: /path/*
• Remove any trailing characters after the /*
• Check for typos in the plugin configuration
• Verify the plugin is correctly registered in gatsby-config.js

Migration to Modern Gatsby

Legacy (this plugin):

// gatsby-config.js
{
  resolve: 'gatsby-plugin-create-client-paths',
  options: { prefixes: ['/app/*'] }
}

Modern Gatsby (File System Route API):

/src
  /pages
    /app
      [...].js  // Handles all /app/* routes

The modern approach eliminates the need for this plugin by providing native support for client-only routes through the file system.

Usage Examples

Multiple Client Paths:

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-create-client-paths',
      options: { 
        prefixes: [
          '/app/*',      // Main application
          '/admin/*',    // Admin panel  
          '/dashboard/*' // User dashboard
        ] 
      }
    }
  ]
}

E-commerce Example:

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-create-client-paths',
      options: { 
        prefixes: [
          '/account/*',  // User account pages
          '/checkout/*', // Checkout flow
          '/cart/*'      // Shopping cart
        ] 
      }
    }
  ]
}

Each prefix requires a corresponding page component at src/pages/[prefix-name].js to handle the client-only routing.