or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

graphql-resolvers.mdimage-cdn-polyfill.mdindex.mdjoi-schemas.mdruntime-compatibility.mdschema-validation.md
tile.json

tessl/npm-gatsby-plugin-utils

Gatsby utils that help creating plugins

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

To install, run

npx @tessl/cli install tessl/npm-gatsby-plugin-utils@3.19.0

index.mddocs/

Gatsby Plugin Utils

Gatsby Plugin Utils provides essential utility functions for Gatsby plugin development, offering a comprehensive toolkit that enables developers to create robust and well-validated Gatsby plugins with proper schema validation, runtime compatibility checking, and feature detection.

Package Information

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

Core Imports

import { validateOptionsSchema, testPluginOptionsSchema, isGatsbyNodeLifecycleSupported, hasFeature } from "gatsby-plugin-utils";

For CommonJS:

const { validateOptionsSchema, testPluginOptionsSchema, isGatsbyNodeLifecycleSupported, hasFeature } = require("gatsby-plugin-utils");

For polyfill remote file functionality:

import { 
  addRemoteFilePolyfillInterface, 
  polyfillImageServiceDevRoutes,
  addImageRoutes,
  gatsbyImageResolver,
  resizeResolver,
  publicUrlResolver,
  getRemoteFileEnums,
  isImageCdnEnabled
} from "gatsby-plugin-utils/polyfill-remote-file";

Basic Usage

import { validateOptionsSchema, Joi } from "gatsby-plugin-utils";

// Define plugin options schema
const pluginOptionsSchema = ({ Joi }) =>
  Joi.object({
    apiKey: Joi.string().required(),
    timeout: Joi.number().default(5000),
    retries: Joi.number().min(0).default(3)
  });

// Validate plugin options
async function validateOptions(pluginOptions) {
  const result = await validateOptionsSchema(pluginOptionsSchema({ Joi }), pluginOptions);
  return result;
}

// Check for feature support
import { hasFeature, isGatsbyNodeLifecycleSupported } from "gatsby-plugin-utils";

if (hasFeature('image-cdn')) {
  // Use native image CDN features
} else {
  // Use polyfill functionality
}

if (isGatsbyNodeLifecycleSupported('createSchemaCustomization')) {
  // Use modern schema customization API
}

Architecture

Gatsby Plugin Utils is built around several key components:

  • Schema Validation: Joi-based validation system for plugin options with async support and detailed error reporting
  • Runtime Compatibility: Version detection for Gatsby node lifecycle APIs and features across different Gatsby versions
  • Image CDN Polyfill: Complete polyfill implementation for image CDN functionality in older Gatsby versions
  • Type Safety: Full TypeScript support with comprehensive type definitions for all APIs
  • GraphQL Integration: Schema builders and resolvers for remote file processing

Capabilities

Schema Validation

Plugin options validation system using Joi schemas with comprehensive error handling and async support.

function validateOptionsSchema(
  pluginSchema: ObjectSchema,
  pluginOptions: IPluginInfoOptions,
  options: {
    validateExternalRules?: boolean;
    returnWarnings?: boolean;
  } = {
    validateExternalRules: true,
    returnWarnings: true
  }
): Promise<{
  value: IPluginInfoOptions;
  warning: {
    message: string;
    details: Array<{
      message: string;
      path: Array<string>;
      type: string;
      context: Array<Record<string, unknown>>;
    }>;
  };
}>;

function testPluginOptionsSchema(
  pluginSchemaFunction: (args: { Joi: PluginOptionsSchemaJoi }) => ObjectSchema,
  pluginOptions: IPluginInfoOptions
): Promise<{
  errors: Array<string>;
  warnings: Array<string>;
  isValid: boolean;
  hasWarnings: boolean;
}>;

Schema Validation

Runtime Compatibility

Runtime detection system for Gatsby node lifecycle APIs and feature availability across different Gatsby versions.

function isGatsbyNodeLifecycleSupported(apiName: string): boolean;

function hasFeature(name: AvailableFeatures): boolean;

Runtime Compatibility

Joi Schema Types

Extended Joi validation library with Gatsby-specific extensions and complete TypeScript support.

const Joi: PluginOptionsSchemaJoi;

interface ObjectSchema {
  validateAsync(value: any, options?: ValidationOptions): Promise<any>;
  // Additional Joi ObjectSchema methods
}

Joi Schema Types

Image CDN Polyfill

Complete polyfill system for image CDN functionality, providing backward compatibility for remote file processing in older Gatsby versions.

function addRemoteFilePolyfillInterface<T>(
  type: T,
  config: {
    schema: SchemaBuilder;
    actions: Actions;
    store: Store;
  }
): T;

function polyfillImageServiceDevRoutes(
  app: Application,
  store?: Store
): void;

function addImageRoutes(
  app: Application,
  store?: Store
): Application;

Image CDN Polyfill

GraphQL Resolvers

GraphQL field resolvers for remote file processing, image transformation, and URL generation.

function gatsbyImageResolver(
  source: IRemoteImageNode,
  args: GatsbyImageArgs
): Promise<IGatsbyImageData>;

function resizeResolver(
  source: IRemoteImageNode,
  args: ResizeArgs
): Promise<IRemoteFileResize>;

function publicUrlResolver(
  source: IRemoteFileNode
): Promise<string>;

GraphQL Resolvers

Core Types

interface IPluginInfoOptions {
  plugins?: Array<IPluginInfo>;
  path?: string;
  [option: string]: unknown;
}

interface IPluginInfo {
  id: string;
  resolve: string;
  name: string;
  version: string;
  pluginOptions?: IPluginInfoOptions;
  module?: any;
  modulePath?: string;
}

interface IRemoteFileNode extends Node {
  url: string;
  mimeType: string;
  filename: string;
  filesize?: number;
}

interface IRemoteImageNode extends IRemoteFileNode {
  width: number;
  height: number;
  placeholderUrl?: string;
}

type SchemaBuilder = Parameters<
  NonNullable<GatsbyNode["createSchemaCustomization"]>
>[0]["schema"];

type ImageFormat = "jpg" | "png" | "webp" | "avif" | "auto";
type ImageLayout = "fixed" | "constrained" | "fullWidth";
type ImageCropFocus = "center" | "top" | "right" | "bottom" | "left" | "entropy" | "edges" | "faces";

enum PlaceholderType {
  BLURRED = "blurred",
  DOMINANT_COLOR = "dominantColor", 
  TRACED_SVG = "tracedSVG"
}

type AvailableFeatures = "image-cdn" | string;

interface WidthOrHeight {
  width?: number;
  height?: number;
}

interface CalculateImageSizesArgs extends WidthOrHeight {
  fit: ImageFit;
  layout: ImageLayout;
  outputPixelDensities: Array<number>;
  breakpoints?: Array<number>;
  aspectRatio?: number;
}

type ImageFit = "cover" | "contain" | "fill" | "inside" | "outside";