or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-usage.mdconfiguration.mdfile-system-routes.mdindex.md
tile.json

index.mddocs/

Gatsby Plugin Page Creator

Gatsby plugin that automatically creates pages from React components in specified directories. This plugin is included by default in all Gatsby sites for creating pages from src/pages, and supports the File System Route API for programmatic page creation from data sources using collection routes and client-only routes.

Package Information

  • Package Name: gatsby-plugin-page-creator
  • Package Type: npm
  • Language: TypeScript/JavaScript
  • Installation: npm install gatsby-plugin-page-creator

Core Imports

This plugin is imported and configured in your Gatsby configuration file:

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-page-creator`,
      options: {
        path: `${__dirname}/src/pages`,
      },
    },
  ],
}

The plugin also provides GraphQL fields that can be used in components:

// In React components or page queries
export const query = graphql`
  query {
    allFile {
      nodes {
        id
        gatsbyPath(filePath: "/blog/{File.name}")
      }
    }
  }
`

Basic Usage

The plugin automatically converts React components in specified directories to pages:

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-page-creator`,
      options: {
        path: `${__dirname}/src/pages`,
        ignore: [`*.test.js`, `private-*.js`],
      },
    },
  ],
}
// src/pages/about.js - becomes /about/
import React from "react";

export default function About() {
  return <h1>About Page</h1>;
}

// src/pages/blog/index.js - becomes /blog/
export default function Blog() {
  return <h1>Blog Index</h1>;
}

Architecture

Gatsby Plugin Page Creator is built around several key components:

  • Gatsby Node API Integration: Hooks into Gatsby's build process via createPagesStatefully, onPluginInit, and setFieldsOnGraphQLNodeType
  • File System Watcher: Monitors directories for component file changes and automatically creates/updates/deletes pages
  • Route Type Detection: Automatically detects and handles different route types (static, collection routes with {}, client-only routes with [])
  • Path Generation: Converts file paths to URL paths with support for nested directories and dynamic segments
  • GraphQL Integration: Adds gatsbyPath field to GraphQL node types for programmatic path generation

Capabilities

Plugin Configuration

Core plugin configuration options for specifying directories, ignore patterns, and slugify options.

interface PluginOptions {
  path: string;
  pathCheck?: boolean;
  ignore?: IPathIgnoreOptions | string | Array<string> | null;
  slugify?: ISlugifyOptions;
}

Configuration

File System Routes

Advanced routing patterns including collection routes for data-driven pages and client-only routes for dynamic content.

// Collection route example: {Model.field} syntax
// File: src/pages/blog/{MarkdownRemark.frontmatter__slug}.js
// Creates: /blog/my-post/, /blog/another-post/, etc.

// Client-only route example: [param] syntax  
// File: src/pages/app/[...].js
// Creates: /app/* with client-side routing

File System Routes

Advanced Usage

Multiple plugin instances, programmatic page creation, and integration with Gatsby's createPages API.

// Multiple instances
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-page-creator`,
      options: { path: `${__dirname}/src/pages` },
    },
    {
      resolve: `gatsby-plugin-page-creator`, 
      options: { path: `${__dirname}/src/admin/pages` },
    },
  ],
}

Advanced Usage

Core Types

interface IOptions extends PluginOptions {
  path: string;
  pathCheck?: boolean;
  ignore?: IPathIgnoreOptions | string | Array<string> | null;
  slugify?: ISlugifyOptions;
}

interface IPathIgnoreOptions {
  patterns: string[];
  options?: {
    nocase?: boolean;
    [key: string]: any;
  };
}

interface ISlugifyOptions {
  separator?: string;
  lowercase?: boolean;
  decamelize?: boolean;
  customReplacements?: Array<[string, string]>;
  preserveLeadingUnderscore?: boolean;
  preserveTrailingDash?: boolean;
  [key: string]: any;
}

Gatsby Node API Functions

The plugin exports the following Gatsby Node API functions:

/**
 * Main page creation function called during Gatsby's createPages lifecycle
 * @param args - Standard Gatsby CreatePagesArgs with store, actions, reporter, graphql, emitter
 * @param pluginOptions - Plugin configuration options
 * @param doneCb - Callback function to signal completion
 */
function createPagesStatefully(
  args: CreatePagesArgs & { traceId: "initial-createPages" },
  pluginOptions: IOptions,
  doneCb: PluginCallback
): Promise<void>;

/**
 * Simple page creation function for synchronous page creation
 * @param args - Standard Gatsby CreatePagesArgs
 * @param pluginOptions - Plugin configuration options
 */
function createPages(args: CreatePagesArgs, pluginOptions: IOptions): void;

/**
 * Plugin initialization hook to set up error mapping and collection detection
 * @param args - Gatsby ParentSpanPluginArgs with reporter
 * @param options - Plugin options containing path configuration
 */
function onPluginInit(
  args: ParentSpanPluginArgs,
  options: IOptions
): Promise<void>;

/**
 * Adds gatsbyPath field to GraphQL node types for collection routes
 * @param args - Gatsby SetFieldsOnGraphQLNodeTypeArgs
 * @param options - Plugin options with slugify configuration
 * @returns GraphQL field definitions object
 */
function setFieldsOnGraphQLNodeType(
  args: SetFieldsOnGraphQLNodeTypeArgs,
  options: PluginOptions & { slugify: ISlugifyOptions }
): Record<string, unknown>;

Gatsby Core Types

interface CreatePagesArgs {
  store: Store;
  actions: Actions;
  reporter: Reporter;
  graphql: GraphQL;
  emitter: EventEmitter;
}

interface ParentSpanPluginArgs {
  reporter: Reporter;
  [key: string]: any;
}

interface SetFieldsOnGraphQLNodeTypeArgs {
  getNode: (id: string) => Node | undefined;
  type: GraphQLObjectType;
  store: Store;
  reporter: Reporter;
}

type PluginCallback = (error?: Error | null, result?: any) => void;

GraphQL Integration

The plugin automatically adds the gatsbyPath field to GraphQL node types when collection routes are detected during onPluginInit:

type File implements Node {
  # ... other fields
  gatsbyPath(filePath: String!): String
}

type MarkdownRemark implements Node {
  # ... other fields  
  gatsbyPath(filePath: String!): String
}

GatsbyPath Field Resolver

The gatsbyPath field resolver implementation:

/**
 * GraphQL field resolver for gatsbyPath
 * @param source - GraphQL node being resolved
 * @param args - Field arguments containing filePath
 * @param context - GraphQL context with nodeModel
 * @returns Generated URL path for the node
 */
interface GatsbyPathResolver {
  gatsbyPath: {
    type: GraphQLString;
    args: {
      filePath: {
        type: GraphQLString;
      };
    };
    resolve: (
      source: Record<string, unknown>,
      args: { filePath: string },
      context: GraphQLResolveInfo
    ) => Promise<string>;
  };
}

Collection Detection

Collection routes are detected during plugin initialization by scanning for files with {Model.field} syntax:

/**
 * Collection detection process during onPluginInit
 * Scans for files matching pattern **/**\{*\}**(/**)
 */
const pagesGlob = `**/**\\{*\\}**(/**)`; 

/**
 * Find all collection page files in the specified path
 * @param pagesPath - Directory path to scan for collection routes
 * @returns Array of relative file paths containing collection routes
 */
function findCollectionPageFiles(pagesPath: string): Promise<Array<string>>;