gatsby-plugin-preact

gatsby-plugin-preact is a Gatsby plugin that provides seamless replacement of React with Preact in Gatsby applications. It automatically configures webpack aliases, enables fast refresh development experience, and optimizes bundle splitting for reduced JavaScript bundle size (~30kb savings).

Package Information

• Package Name: gatsby-plugin-preact
• Package Type: npm (Gatsby plugin)
• Language: JavaScript
• Installation: npm install gatsby-plugin-preact preact preact-render-to-string

Core Imports

This plugin is not directly imported. It exports Gatsby API hooks that are automatically called by Gatsby. The main entry point (index.js) contains only a no-op comment:

// Not imported directly - used via gatsby-config.js
plugins: ['gatsby-plugin-preact'];

// Main entry point exports no-op
// noop

Basic Usage

// gatsby-config.js
module.exports = {
  plugins: [
    'gatsby-plugin-preact'
  ]
};

Once installed and configured, the plugin automatically:

• Replaces React imports with Preact equivalents
• Sets up fast refresh for development
• Optimizes framework bundles for production
• Enables Preact debugging in development

Architecture

The plugin implements Gatsby's plugin API through three main hooks:

• Node API: Configures webpack and Babel during build process
• Browser API: Sets up development-time debugging and fast refresh
• Fast Refresh System: Custom error handling and hot module replacement integration

Capabilities

Plugin Configuration

The plugin requires no configuration options and works automatically once added to gatsby-config.js.

// gatsby-config.js usage
plugins: ['gatsby-plugin-preact'];

Gatsby Node API Hook: onCreateBabelConfig

Configures Babel to use Prefresh plugin for fast refresh during development.

/**
 * Gatsby Node API hook for Babel configuration
 * @param {Object} params - Gatsby hook parameters
 * @param {Object} params.actions - Gatsby actions object with setBabelPlugin method
 * @param {string} params.stage - Build stage identifier ('develop', 'build-javascript', etc.)
 */
export function onCreateBabelConfig({ actions, stage }): void;

Internal Implementation Details:

• Only active during 'develop' stage
• Adds @prefresh/babel-plugin for React hooks compatibility
• Enables hot reloading of Preact components

Gatsby Node API Hook: onCreateWebpackConfig

Configures webpack to alias React imports to Preact and optimize bundles.

/**
 * Gatsby Node API hook for webpack configuration
 * @param {Object} params - Gatsby hook parameters
 * @param {string} params.stage - Build stage identifier
 * @param {Object} params.actions - Gatsby actions object with setWebpackConfig and replaceWebpackConfig methods
 * @param {Function} params.getConfig - Function returning current webpack configuration object
 */
export function onCreateWebpackConfig({ stage, actions, getConfig }): void;

Key Configuration Changes:

• Removes existing react and react-dom aliases from webpack config
• Maps react → preact/compat
• Maps react-dom → preact/compat
• Maps react-dom/test-utils → preact/test-utils
• Maps react/jsx-runtime → preact/jsx-runtime
• Configures framework bundle optimization with Preact libraries
• Removes React refresh plugin in favor of Prefresh (develop stage only)

Gatsby Browser API Hook: onClientEntry

Sets up Preact debugging and fast refresh integration in the browser.

/**
 * Gatsby Browser API hook for client-side initialization
 * Sets up Preact debug mode and fast refresh in non-production environments
 */
export function onClientEntry(): void;

Functionality:

• Enables preact/debug in non-production environments
• Initializes fast refresh error handling system
• Sets up runtime error capture and display

Fast Refresh Integration

Internal fast refresh setup function for development experience.

/**
 * Sets up Prefresh error handling and hot module replacement
 * Called by onClientEntry hook, exported as module.exports from prefreshGlueCode.js
 * Requires preact/debug in non-production environments
 * Sets up error event listeners and webpack hot middleware integration
 */
function setupPrefresh(): void;

Features:

• Custom error overlay integration
• Runtime error handling for unhandled exceptions
• Webpack compilation error formatting
• Integration with Gatsby's hot middleware

Error Formatting Utility

Formats webpack compilation errors for better developer experience.

/**
 * Formats webpack compilation errors into readable messages
 * @param {Array<string|WebpackErrorObj>} errors - Array of webpack error objects or strings  
 * @returns {string[]} Array of formatted error messages
 */
function formatWebpackErrors(errors: Array<string | WebpackErrorObj>): string[];

Message Handler Integration

Internal message handler function used by setupPrefresh for webpack compilation events.

/**
 * Handles webpack hot middleware messages and updates error display
 * @param {Object} message - Message object with type and optional data
 * @param {string} message.type - Message type ('ok', 'still-ok', 'warnings', 'errors')
 * @param {Array} message.data - Optional error data for 'errors' type messages
 */
function messageHandler(message): void;

Types

/**
 * Webpack error object structure for compilation errors
 * @typedef {Object} WebpackErrorObj
 * @property {string} moduleIdentifier - Module identifier path
 * @property {string} moduleName - Human-readable module name  
 * @property {string} message - Error message content
 */
interface WebpackErrorObj {
  moduleIdentifier: string;
  moduleName: string;
  message: string;
}

/**
 * Plugin dependencies from package.json
 * @typedef {Object} Dependencies
 */
interface Dependencies {
  "@babel/runtime": "^7.20.13";
  "@gatsbyjs/webpack-hot-middleware": "^2.25.3";
  "@prefresh/babel-plugin": "^0.4.3";
  "@prefresh/webpack": "^3.3.4";
}

Framework Bundle Configuration

The plugin automatically configures webpack to optimize framework bundles:

// Internal constants used for bundle optimization
const FRAMEWORK_BUNDLES_PREACT: string[] = [
  'preact',
  'react', 
  'react-dom',
  'scheduler',
  'prop-types'
];

const FRAMEWORK_BUNDLES_REGEX_PREACT: RegExp;

Build Stages

The plugin handles different Gatsby build stages with specific behaviors:

• develop: Enables fast refresh via PreactRefreshPlugin, adds Prefresh Babel plugin, removes React refresh plugin, adds webpack-hot-middleware/client to commons entry, and configures framework bundle optimization
• develop-html: Sets webpack aliases for React → Preact mappings only (no refresh plugins)
• build-javascript: Configures framework bundle optimization with Preact libraries and sets webpack aliases
• build-html: Sets webpack aliases for React → Preact mappings only (no refresh plugins or optimizations)

Peer Dependencies

Required peer dependencies that must be installed:

interface PeerDependencies {
  gatsby: "^5.0.0-next";
  preact: "^10.3.4";
  "preact-render-to-string": "^5.1.8";
}

Error Handling

The plugin includes comprehensive error handling:

• Syntax Error Detection: Identifies and prioritizes syntax errors
• Runtime Error Capture: Handles unhandled exceptions and promise rejections
• Compilation Error Formatting: Cleans up webpack error messages
• Development Overlay: Custom error display integration

Compatibility Notes

• Requires Gatsby v5.0.0 or higher
• Requires Preact v10.3.4 or higher (Preact X)
• Uses preact/compat for React compatibility layer
• Supports modern development features like fast refresh
• Compatible with existing React components through preact/compat