CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-gatsby-plugin-utils

Gatsby utils that help creating plugins

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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";
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/gatsby-plugin-utils@3.19.x
Publish Source
CLI
Badge
tessl/npm-gatsby-plugin-utils badge