Netlify Plugin TypeScript types

INetlifyEvent.d.ts

import { INetlifyPluginOptions } from "./INetlifyPluginOptions";

export type INetlifyEvent = (options: INetlifyPluginOptions) => void;

INetlifyPlugin.d.ts

import { INetlifyEvent } from "./INetlifyEvent";

type NetlifyPluginLifecycle = "onPreBuild" | "onBuild" | "onPostBuild" | "onBuild" | "onSuccess" | "onError" | "onEnd";

export type NetlifyPlugin = Partial<Record<NetlifyPluginLifecycle, INetlifyEvent>>;

INetlifyPluginOptions.d.ts

export type INetlifyPluginOptions = {
  constants: {
    CONFIG_PATH: string | undefined;
    PUBLISH_DIR: string;
    FUNCTIONS_SRC: string | undefined;
    FUNCTIONS_DIST: string;
    EDGE_HANDLERS_SRC: string | undefined;
    IS_LOCAL: boolean;
    NETLIFY_BUILD_VERSION: string;
    SITE_ID: string;
  };
  inputs: Partial<Record<string, string>>;
  packageJson: string;
  utils: NetlifyPluginUtils;
};

interface NetlifyPluginUtils {
  build: NetlifyPluginBuildUtil;
  status: NetlifyPluginStatusUtil;
  cache: NetlifyPluginCacheUtil;
  run: NetlifyPluginRunUtil;
  git: NetlifyPluginGitUtil;
}

type NetlifyPluginBuildUtil = Record<
  "failBuild" | "failPlugin" | "cancelBuild",
  (
    message: string,
    options?: {
      error: Error;
    },
  ) => void
>;

type NetlifyPluginCacheUtil = {
  save(
    path: string | readonly string[],
    options?: {
      ttl?: number;
      digests?: string[];
      /**
       * @default `process.cwd()`
       */
      cwd: string;
    },
  ): Promise<boolean>;
  list(options: {
    /**
     * @default `process.cwd()`
     */
    cwd?: string;
    /**
     * @default 1
     */
    depth?: number;
  }): Promise<string[]>;
} & Record<
  "restore" | "remove" | "has",
  (
    path: string | readonly string[],
    options?: {
      /**
       * @default `process.cwd()`
       */
      cwd?: string;
    },
  ) => Promise<boolean>
>;

interface NetlifyPluginStatusUtil {
  /**
   * Only one status is shown per plugin.
   * Calling `utils.status.show()` twice overrides the previous status.
   */
  show(options: {
    /**
     * Default to the plugin's name followed by a generic title.
     */
    title?: string;
    /**
     * Message below the title
     */
    summary: string;
    /**
     * Detailed information shown in a collapsible section.
     * @default ""
     */
    text?: string;
  });
}

interface NetlifyPluginRunUtilOptions {
  env?: Record<string, string>;
}

interface NetlifyPluginRunUtilResult {
  stdout: string;
  stderr: string;
  exitCode: number;
}

/**
 * @see https://github.com/netlify/build/blob/master/packages/run-utils/README.md
 */
interface NetlifyPluginRunUtil {
  (file: string, arguments: string[], options?: NetlifyPluginRunUtilOptions): Promise<NetlifyPluginRunUtilResult>;
  command(command: string, options?: NetlifyPluginRunUtilOptions): Promise<NetlifyPluginRunUtilResult>;
}

/**
 * @see https://github.com/netlify/build/blob/master/packages/git-utils/README.md
 */
interface NetlifyPluginGitUtil {
  fileMatch(globPattern: string): string[];
  /**
   * Array of all modified files.
   */
  modifiedFiles: string[];
  /**
   * Array of all created files.
   */
  createdFiles: string[];
  /**
   * Array of all deleted files.
   */
  deletedFiles: string[];
  /**
   * Array of commits with details.
   */
  commits: Array<{
    sha: string;
    parents: string;
    author: {
      name: string;
      email: string;
      date: string;
    };
    committer: {
      name: string;
      email: string;
      date: string;
    };
    message: string;
  }>;
  /**
   * How many lines of code have changed
   */
  linesOfCode(): Promise<number>;
}