Gatsby Plugin Styletron

Gatsby Plugin Styletron is a Gatsby plugin that integrates Styletron CSS-in-JS library with built-in server-side rendering support. It provides seamless setup for using Styletron styled components in Gatsby applications with proper style hydration and SSR support.

Package Information

• Package Name: gatsby-plugin-styletron
• Package Type: npm (Gatsby Plugin)
• Language: JavaScript/TypeScript
• Installation: npm install gatsby-plugin-styletron styletron-react styletron-engine-atomic

Core Imports

This is a Gatsby plugin that does not export APIs for direct import. It provides functionality through Gatsby's plugin system.

Basic Usage

Configure the plugin in your gatsby-config.js:

module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-styletron`,
      options: {
        // Optional CSS class prefix for Styletron
        prefix: "_", 
        // Optional debug mode, defaults to true in development, false in production
        debug: false,
      },
    },
  ],
}

Once configured, use Styletron components in your React components:

import React from "react";
import { styled, useStyletron } from "styletron-react";

// Statically styled component
const RedAnchor = styled("a", { color: "red" });

// Dynamically styled component
const BigAnchor = styled("a", ({ $size }) => ({ fontSize: `${$size}px` }));

const IndexPage = () => {
  // Hook-based API
  const [css] = useStyletron();
  return (
    <div>
      <RedAnchor>Red Anchor</RedAnchor>
      <BigAnchor $size={64}>Big Anchor</BigAnchor>
      <p className={css({ color: "blue" })}>blue text</p>
    </div>
  );
};

Architecture

The plugin integrates Styletron into Gatsby through two main components:

• Browser Context: Handles client-side hydration of server-rendered styles
• SSR Context: Generates and injects CSS during server-side rendering
• Style Hydration: Ensures styles are properly transferred from server to client without flash of unstyled content

Capabilities

Plugin Configuration

Configuration options for customizing Styletron behavior in Gatsby applications.

// Plugin options interface
interface PluginOptions {
  /** CSS class prefix for Styletron styles (optional) */
  prefix?: string;
  /** Enable debug mode in development (optional, defaults to true in development, false in production) */
  debug?: boolean;
}

Browser-Side Root Element Wrapping

Wraps the root React element with Styletron Provider for client-side hydration.

/**
 * Gatsby Browser API - wraps root element with Styletron Provider for client hydration
 * @param element - The root React element from Gatsby
 * @param prefix - CSS class prefix for Styletron styles (optional)
 * @param debug - Enable debug mode in development (optional, defaults to true in development, false in production)
 * @returns React element wrapped with Styletron Provider
 */
export function wrapRootElement({ element }, { prefix, debug }): React.ReactElement;

Server-Side Root Element Wrapping

Wraps the root React element with Styletron Provider for server-side rendering.

/**
 * Gatsby SSR API - wraps root element with Styletron Provider for server rendering
 * @param element - The root React element from Gatsby
 * @param options - Plugin configuration options containing prefix and debug settings
 * @returns React element wrapped with Styletron Provider
 */
export function wrapRootElement({ element }, options): React.ReactElement;

Style Injection During SSR

Injects generated Styletron stylesheets into the HTML head during server-side rendering.

/**
 * Gatsby SSR API - injects generated CSS into HTML head during server rendering
 * @param setHeadComponents - Gatsby function to set HTML head components
 * @returns void
 */
export function onRenderBody({ setHeadComponents }): void;

Dependencies

Runtime Dependencies

• @babel/runtime: ^7.20.13

Peer Dependencies

• gatsby: ^5.0.0-next
• react: ^18.0.0 || ^0.0.0
• styletron-engine-atomic: ^1.4.8
• styletron-react: ^5.2.7 || ^6.0.0

Integration Points

This plugin integrates with Gatsby's plugin architecture through:

1. gatsby-browser.js: Provides wrapRootElement hook for client-side setup
2. gatsby-ssr.js: Provides wrapRootElement and onRenderBody hooks for server-side rendering
3. Styletron Engine: Uses styletron-engine-atomic for CSS generation
4. Styletron React: Uses styletron-react Provider and DebugEngine

The plugin ensures that:

• Styles generated during SSR are properly hydrated on the client
• Debug mode is available in development for style inspection
• CSS classes can be prefixed to avoid conflicts
• Styletron context is available throughout the Gatsby application