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

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Gatsby Plugin Utils

Name: tessl/npm-gatsby-plugin-utils
Author: tessl

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";