or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-gatsby-plugin-typography

Gatsby plugin to setup server rendering of Typography.js' CSS

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/gatsby-plugin-typography@5.15.x

To install, run

npx @tessl/cli install tessl/npm-gatsby-plugin-typography@5.15.0

index.mddocs/

gatsby-plugin-typography

gatsby-plugin-typography seamlessly integrates Typography.js with Gatsby applications, providing server-side rendering support for typography styles and automatic Google Font loading. It handles the complete typography setup by taking a configuration file path and automatically injecting generated styles into the document head during build time.

Package Information

  • Package Name: gatsby-plugin-typography
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install gatsby-plugin-typography react-typography typography

Core Imports

This is a Gatsby plugin, so it doesn't export functions directly. Instead, it's configured in gatsby-config.js:

// In gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: "gatsby-plugin-typography",
      options: {
        pathToConfigModule: "src/utils/typography",
        omitGoogleFont: false,
      },
    },
  ],
};

Basic Usage

// 1. Install dependencies
// npm install gatsby-plugin-typography react-typography typography

// 2. Create typography configuration file (src/utils/typography.js)
import Typography from "typography";
import grandViewTheme from "typography-theme-grand-view";

const typography = new Typography(grandViewTheme);

// Export helper functions
export const { scale, rhythm, options } = typography;
export default typography;

// 3. Configure plugin in gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: "gatsby-plugin-typography",
      options: {
        pathToConfigModule: "src/utils/typography",
      },
    },
  ],
};

Architecture

gatsby-plugin-typography operates through Gatsby's plugin system using lifecycle hooks:

  • Build-time Setup: Creates cached typography configuration and webpack aliases
  • Server-side Rendering: Injects typography styles and Google Font links into document head
  • Development Hot Reloading: Updates typography styles and fonts during development
  • CSS Precedence: Ensures typography styles load first to act as a proper CSS reset

Capabilities

Plugin Configuration

Configuration options for the gatsby-plugin-typography plugin.

interface PluginOptions {
  /** Path to the file that exports your typography configuration */
  pathToConfigModule?: string;
  /** Skip automatic Google Font loading when true */
  omitGoogleFont?: boolean;
}

Configuration Examples:

// Basic configuration
{
  resolve: "gatsby-plugin-typography",
  options: {
    pathToConfigModule: "src/utils/typography",
  },
}

// Skip Google Font loading
{
  resolve: "gatsby-plugin-typography",
  options: {
    pathToConfigModule: "src/utils/typography",  
    omitGoogleFont: true,
  },
}

// Default configuration (creates basic Typography instance)
{
  resolve: "gatsby-plugin-typography",
  options: {},
}

Typography Configuration File

The typography configuration file referenced by pathToConfigModule should export a Typography.js instance.

/**
 * Typography configuration file structure
 * Should export a Typography instance as default export
 */
interface TypographyConfig {
  /** Default export: Typography instance */
  default: Typography;
  /** Optional: Export typography helper functions */
  scale?: Function;
  rhythm?: Function; 
  options?: object;
}

Typography Config Examples:

// With theme
import Typography from "typography";
import grandViewTheme from "typography-theme-grand-view";

const typography = new Typography(grandViewTheme);
export const { scale, rhythm, options } = typography;
export default typography;

// Custom configuration
import Typography from "typography";

const typography = new Typography({
  baseFontSize: "18px",
  baseLineHeight: 1.666,
  headerFontFamily: ["Avenir Next", "Helvetica Neue", "sans-serif"],
  bodyFontFamily: ["Georgia", "serif"],
  googleFonts: [
    {
      name: "Montserrat",
      styles: ["400", "700"],
    },
    {
      name: "Merriweather", 
      styles: ["400", "400i", "700", "700i"],
    },
  ],
});

export default typography;

Gatsby Node API Integration

Build-time hooks that set up typography configuration and webpack aliases.

/**
 * Creates typography cache file in .cache directory during build
 * Executed before Gatsby bootstrap process
 */
function onPreBootstrap(
  api: { store: GatsbyStore; cache: GatsbyCache },
  pluginOptions: PluginOptions
): void;

/**
 * Sets up webpack alias for typography cache endpoint
 * Allows importing typography config via "typography-plugin-cache-endpoint"
 */
function onCreateWebpackConfig(
  api: { actions: { setWebpackConfig: Function }; cache: GatsbyCache }
): void;

Gatsby SSR API Integration

Server-side rendering hooks that inject typography styles into the document head.

/**
 * Injects typography styles and Google Fonts into document head during SSR
 * Adds TypographyStyle component and conditionally adds GoogleFont component
 */
function onRenderBody(
  api: { setHeadComponents: (components: React.ReactElement[]) => void },
  pluginOptions: PluginOptions
): void;

/**
 * Reorders head components to prioritize typography styles
 * Moves TypographyStyle to beginning for proper CSS cascade
 */
function onPreRenderHTML(
  api: {
    getHeadComponents: () => React.ReactElement[];
    replaceHeadComponents: (components: React.ReactElement[]) => void;
  }
): void;

Gatsby Browser API Integration

Client-side development hooks for hot reloading typography changes.

/**
 * Handles hot reloading of typography styles and Google Fonts in development
 * Only active when BUILD_STAGE === 'develop'
 * Injects styles and manages Google Font link elements
 */
function onClientEntry(
  api: any,
  pluginOptions: PluginOptions
): void;

Development Behavior:

  • Automatically injects typography styles via typography.injectStyles()
  • Hot reloads Google Font links when typography config changes
  • Respects omitGoogleFont option to skip Google Font loading
  • Uses DOMParser to manage Google Font <link> elements with data-gatsby-typography attribute

Types

interface PluginOptions {
  /** Path to typography configuration file (relative or absolute) */
  pathToConfigModule?: string;
  /** Skip Google Font loading when true (default: false) */
  omitGoogleFont?: boolean;
}

interface GatsbyStore {
  getState(): { program: { directory: string } };
}

interface GatsbyCache {
  directory: string;
}

interface Typography {
  /** Inject typography styles into document */
  injectStyles(): void;
  /** Typography configuration options */
  options: {
    googleFonts: Array<{ name: string; styles: string[] }>;
  };
}

Error Handling

The plugin handles several common error scenarios:

  • Missing typography config: Creates default Typography instance if pathToConfigModule not provided
  • Invalid config path: Uses absolute path resolution and handles Windows path separators
  • Development hot reload failures: Gracefully handles missing DOM elements and invalid configurations
  • Google Font loading: Safely removes and replaces Google Font link elements during hot reload

Peer Dependencies

Required peer dependencies that must be installed alongside the plugin:

{
  "gatsby": "^5.0.0-next",
  "react": "^18.0.0",
  "react-dom": "^18.0.0", 
  "react-typography": "^0.16.1 || ^1.0.0-alpha.0",
  "typography": "^0.16.0 || ^1.0.0-alpha.0"
}