tessl/npm-vuepress

VuePress is a minimalistic Vue.js-based documentation generator with component layout system and extensive plugin architecture.

—

Pending

Overview

Eval results

Files

Plugin System

Name: tessl/npm-vuepress
Author: tessl

Comprehensive plugin architecture providing hooks for customizing every aspect of the VuePress build process, from markdown processing to webpack configuration.

Capabilities

PluginAPI Class

Core plugin management system that handles plugin registration, initialization, and option processing.

/**
 * Plugin management and execution system
 */
class PluginAPI {
  /**
   * Create a new PluginAPI instance
   * @param context - App instance context
   */
  constructor(context: App);
  
  /** Plugin collections */
  readonly enabledPlugins: Plugin[];
  readonly disabledPlugins: Plugin[];
  readonly options: { [optionName: string]: Option };
}

use Method

Registers a plugin with the plugin system.

/**
 * Register a plugin with optional configuration
 * @param pluginRaw - Plugin name, path, or object
 * @param pluginOptions - Plugin configuration options
 * @returns PluginAPI instance for chaining
 */
use(pluginRaw: string | Plugin | any, pluginOptions?: any): PluginAPI;

Usage Examples:

const { createApp } = require("vuepress");

const app = createApp({ sourceDir: "./docs" });

// Register plugins using string names
app.pluginAPI
  .use("@vuepress/plugin-blog")
  .use("@vuepress/plugin-google-analytics", { ga: "UA-12345678-1" })
  .use("@vuepress/plugin-pwa", {
    serviceWorker: true,
    updatePopup: true,
  });

// Register plugin using object
app.pluginAPI.use({
  name: "custom-plugin",
  ready() {
    console.log("Custom plugin is ready!");
  },
  generated() {
    console.log("Site generation complete!");
  },
});

// Chain multiple plugin registrations
app.pluginAPI
  .use("plugin-one")
  .use("plugin-two", { option: "value" })
  .use("plugin-three");

useByPluginsConfig Method

Registers multiple plugins using configuration array format.

/**
 * Register plugins using configuration array
 * @param pluginsConfig - Array of plugin configurations
 * @returns PluginAPI instance for chaining
 */
useByPluginsConfig(pluginsConfig: PluginConfig[]): PluginAPI;

type PluginConfig = 
  | string 
  | [string, any] 
  | Plugin 
  | [Plugin, any];

Usage Examples:

const pluginsConfig = [
  "@vuepress/plugin-blog",
  ["@vuepress/plugin-google-analytics", { ga: "UA-12345678-1" }],
  ["@vuepress/plugin-pwa", { 
    serviceWorker: true,
    updatePopup: {
      message: "New content is available.",
      buttonText: "Refresh"
    }
  }],
];

app.pluginAPI.useByPluginsConfig(pluginsConfig);

initialize Method

Initializes all registered plugins and prepares them for use.

/**
 * Initialize all registered plugins
 * Must be called after all plugins are registered
 * @returns void
 */
initialize(): void;

Usage Examples:

// Register all plugins first
app.pluginAPI
  .use("@vuepress/plugin-blog")
  .use("@vuepress/plugin-search");

// Then initialize the plugin system
app.pluginAPI.initialize();

// Access enabled plugins
console.log(`${app.pluginAPI.enabledPlugins.length} plugins enabled`);

applySyncOption Method

Applies a synchronous plugin option to all registered plugins.

/**
 * Apply synchronous plugin option
 * @param name - Option name
 * @param args - Arguments to pass to option handlers
 * @returns PluginAPI instance for chaining
 */
applySyncOption(name: string, ...args: any[]): PluginAPI;

Usage Examples:

// Apply chainWebpack option to modify webpack config
app.pluginAPI.applySyncOption("chainWebpack", webpackConfig, isServer);

// Apply extendMarkdown option to customize markdown processing
app.pluginAPI.applySyncOption("extendMarkdown", markdownIt);

applyAsyncOption Method

Applies an asynchronous plugin option to all registered plugins.

/**
 * Apply asynchronous plugin option
 * @param name - Option name
 * @param args - Arguments to pass to option handlers
 * @returns Promise that resolves when all handlers complete
 */
async applyAsyncOption(name: string, ...args: any[]): Promise<void>;

Usage Examples:

// Apply ready hook when app is ready
await app.pluginAPI.applyAsyncOption("ready");

// Apply generated hook after site generation
await app.pluginAPI.applyAsyncOption("generated", pages);

// Apply additionalPages to add dynamic pages
await app.pluginAPI.applyAsyncOption("additionalPages", app);

getOption Method

Retrieves a specific plugin option handler.

/**
 * Get existing plugin option
 * @param name - Option name
 * @returns Option instance
 */
getOption(name: string): Option;

interface Option {
  /** Option name */
  name: string;
  /** Registered handlers */
  items: OptionItem[];
  /** Applied values from handlers */
  appliedValues: any[];
  /** Apply option to all handlers */
  apply(...args: any[]): any;
}

Usage Examples:

// Get chainWebpack option
const chainWebpackOption = app.pluginAPI.getOption("chainWebpack");
console.log(`${chainWebpackOption.items.length} chainWebpack handlers`);

// Get enhanceAppFiles option
const enhanceOption = app.pluginAPI.getOption("enhanceAppFiles");
enhanceOption.appliedValues.forEach(file => {
  console.log(`Enhance app file: ${file}`);
});

Plugin Options

Lifecycle Hooks

interface LifecycleHooks {
  /** Called when app is ready */
  ready?: () => void | Promise<void>;
  
  /** Called after compilation */
  compiled?: () => void | Promise<void>;
  
  /** Called when files are updated (dev mode) */
  updated?: () => void | Promise<void>;
  
  /** Called after site generation */
  generated?: (pages: Page[]) => void | Promise<void>;
}

Build Configuration Options

interface BuildOptions {
  /** Modify webpack configuration */
  chainWebpack?: (config: WebpackChainConfig, isServer: boolean) => void;
  
  /** Extend markdown processor */
  extendMarkdown?: (md: MarkdownIt) => void;
  
  /** Chain markdown configuration */
  chainMarkdown?: (config: any) => void;
  
  /** Global constants definition */
  define?: { [key: string]: any };
  
  /** Module aliases */
  alias?: { [key: string]: string };
}

Client-Side Options

interface ClientOptions {
  /** Client app enhancement files */
  enhanceAppFiles?: string[] | (() => string[] | Promise<string[]>);
  
  /** Client-side dynamic modules */
  clientDynamicModules?: () => string | Promise<string>;
  
  /** Client root mixin */
  clientRootMixin?: string;
  
  /** Global UI components */
  globalUIComponents?: string[] | string;
}

Content Options

interface ContentOptions {
  /** Additional pages to generate */
  additionalPages?: PageOptions[] | (() => PageOptions[] | Promise<PageOptions[]>);
  
  /** Extend page data */
  extendPageData?: (page: Page) => void | Promise<void>;
  
  /** Output files */
  outFiles?: { [path: string]: string };
}

Development Options

interface DevelopmentOptions {
  /** Before dev server setup */
  beforeDevServer?: (app: any, server: any) => void;
  
  /** After dev server setup */
  afterDevServer?: (app: any, server: any) => void;
  
  /** Extend CLI commands */
  extendCli?: (cli: any) => void;
}

Plugin Development

Basic Plugin Structure

interface Plugin {
  /** Plugin name */
  name?: string;
  
  /** Allow multiple instances */
  multiple?: boolean;
  
  /** Child plugins */
  plugins?: PluginConfig[];
  
  /** Lifecycle hooks */
  ready?: () => void | Promise<void>;
  compiled?: () => void | Promise<void>;
  updated?: () => void | Promise<void>;
  generated?: (pages: Page[]) => void | Promise<void>;
  
  /** Build options */
  chainWebpack?: (config: any, isServer: boolean) => void;
  extendMarkdown?: (md: any) => void;
  define?: { [key: string]: any };
  alias?: { [key: string]: string };
  
  /** Content options */
  additionalPages?: any;
  extendPageData?: (page: Page) => void | Promise<void>;
  
  /** Client-side options */
  enhanceAppFiles?: string[] | (() => string[] | Promise<string[]>);
  clientDynamicModules?: () => string | Promise<string>;
  clientRootMixin?: string;
  globalUIComponents?: string[] | string;
  
  /** Development options */
  beforeDevServer?: (app: any, server: any) => void;
  afterDevServer?: (app: any, server: any) => void;
  
  /** Advanced hooks */
  chainMarkdown?: (config: any) => void;
  outFiles?: { [path: string]: string };
  
  /** Other custom options */
  [key: string]: any;
}

Usage Examples:

// Simple plugin example
const myPlugin = {
  name: "my-custom-plugin",
  ready() {
    console.log("Plugin ready!");
  },
  extendMarkdown(md) {
    md.use(require("markdown-it-footnote"));
  },
  chainWebpack(config, isServer) {
    if (!isServer) {
      config.plugin("my-webpack-plugin")
        .use(require("my-webpack-plugin"));
    }
  },
};

app.pluginAPI.use(myPlugin);

Install with Tessl CLI