VuePress EcosystemVuePress Ecosystem
  • Theme Guidelines
  • theme-default
  • Hope Theme
  • Plume Theme
  • Reco Theme
  • Feature Plugins
  • Markdown Plugins
  • Search Plugins
  • Blog Plugins
  • PWA Plugins
  • Analytics Plugins
  • SEO Plugins
  • Development Plugins
  • Tool Plugins
  • AI Plugins
  • @vuepress/helper
  • English
  • 简体中文
GitHub
  • Theme Guidelines
  • theme-default
  • Hope Theme
  • Plume Theme
  • Reco Theme
  • Feature Plugins
  • Markdown Plugins
  • Search Plugins
  • Blog Plugins
  • PWA Plugins
  • Analytics Plugins
  • SEO Plugins
  • Development Plugins
  • Tool Plugins
  • AI Plugins
  • @vuepress/helper
  • English
  • 简体中文
GitHub
  • @vuepress/helper
    • Node

      • Bundler Related
      • Locales Related
      • Page Related
    • Client Related
    • Shared Methods
    • Styles

Bundler Related

Bundler functions for appending or modifying bundler options in theme and plugins.

These functions are only available via @vuepress/helper.

Tips

All functions should be called in extendsBundlerOptions lifecycle hook.

We are omitting that in examples. The actual code should be like this:

// import functions you need
import { addCustomElement } from '@vuepress/helper'

export const yourPlugin = {
  // ...
  extendsBundlerOptions: (bundlerOptions, app) => {
    // add them here
    addCustomElement(bundlerOptions, app, 'my-custom-element')
  },
}

Common methods

getBundlerName

Get current bundler name.

export const getBundlerName: (app: App) => string
Example
// @vuepress/bundler-vite
getBundleName(app) === 'vite' // true
// @vuepress/bundler-webpack
getBundleName(app) === 'webpack' // true

addCustomElement

Add a custom element declaration to the current bundler.

/**
 * Add tags as customElement
 *
 * @param bundlerOptions VuePress Bundler config
 * @param app VuePress Node App
 * @param customElements tags recognized as custom element
 */
export const addCustomElement: (
  bundlerOptions: unknown,
  app: App,
  customElement: RegExp | string[] | string,
) => void
Example
import { addCustomElement } from '@vuepress/helper'

addCustomElement(bundlerConfig, app, 'my-custom-element')
addCustomElement(bundlerOptions, app, [
  'custom-element1',
  'custom-element2',
  // all tags start with `math-`
  /^math-/,
])

customizeDevServer

Provides contents for specific path in dev server.

export interface DevServerOptions {
  /**
   * Path to be responded
   */
  path: string
  /**
   * Respond function
   */
  response: (request?: IncomingMessage) => Promise<Buffer | string>

  /**
   * error msg
   */
  errMsg?: string
}

/**
 * Handle specific path when running VuePress Dev Server
 *
 * @param bundlerOptions VuePress Bundler config
 * @param app VuePress Node App
 * @param path Path to be responded
 * @param response respond function
 * @param errMsg error msg
 */
export const customizeDevServer: (
  bundlerOptions: unknown,
  app: App,
  {
    errMsg = 'The server encountered an error',
    response,
    path,
  }: CustomServerOptions,
) => void
Example
import { useCustomDevServer } from '@vuepress/helper'

// handle `/api/` path
useCustomDevServer(bundlerOptions, app, {
  path: '/api/',
  response: async () => getData(),
  errMsg: 'Unexpected api error',
})

Vite Related

  • addViteOptimizeDepsInclude

    Add modules to Vite optimizeDeps.include list

    Tips

    If a package meets one of the following conditions, you should consider adding it here.

    • It's in CJS format
    • It's dependencies include CJS package
    • It's dynamically imported via import()
  • addViteOptimizeDepsExclude

    Add modules to Vite optimizeDeps.exclude list

    If a package and its dependencies are all pure ESM packages, you should consider adding it here.

  • addViteSsrExternal

    Add modules to Vite ssr.external list

    If a package is a pure ESM package and does not use aliases or define variables, you should consider adding it here.

  • addViteSsrNoExternal

    Add modules to Vite ssr.noExternal list

    If an alias or define is used within a package, you must add it here.

    /**
     * Add modules to Vite `optimizeDeps.include` list
     */
    export const addViteOptimizeDepsInclude: (
      bundlerOptions: unknown,
      app: App,
      module: string[] | string,
    ) => void
    
    /**
     * Add modules to Vite `optimizeDeps.exclude` list
     */
    export const addViteOptimizeDepsExclude: (
      bundlerOptions: unknown,
      app: App,
      module: string[] | string,
    ) => void
    
    /**
     * Add modules to Vite `ssr.external` list
     */
    export const addViteSsrExternal: (
      bundlerOptions: unknown,
      app: App,
      module: string[] | string,
    ) => void
    
    /**
     * Add modules to Vite `ssr.noExternal` list
     */
    export const addViteSsrNoExternal: (
      bundlerOptions: unknown,
      app: App,
      module: string[] | string,
    ) => void
    Examples
    import {
      addViteOptimizeDepsExclude,
      addViteOptimizeDepsInclude,
      addViteSsrExternal,
      addViteSsrNoExternal,
    } from '@vuepress/helper'
    
    addViteOptimizeDepsInclude(bundlerOptions, app, ['vue', 'vue-router'])
    addViteOptimizeDepsExclude(bundlerOptions, app, 'packageA')
    addViteSsrNoExternal(bundlerOptions, app, ['vue', 'vue-router'])
    addViteSsrExternal(bundlerOptions, app, 'packageA')
  • addViteConfig

    A function for you to add vite config

    export const addViteConfig: (
      bundlerOptions: unknown,
      app: App,
      config: Record<string, unknown>,
    ) => void
    Example
    import { addViteConfig } from '@vuepress/helper'
    
    addViteConfig(bundlerOptions, app, {
      build: {
        charset: 'utf8',
      },
    })
  • mergeViteConfig

    A function for you to merge vite config.

    Warning

    Your users may choose to use other bundler so it's pretty bad to declare vite as deps!

    export const mergeViteConfig: (
      defaults: Record<string, any>,
      overrides: Record<string, any>,
    ) => Record<string, any>
    Example
    import { mergeViteConfig } from '@vuepress/helper'
    
    config.viteOptions = mergeViteConfig(config.viteOptions, {
      build: {
        charset: 'utf8',
      },
    })

Webpack Related

  • chainWebpack

    Chain webpack config.

    export const chainWebpack: (
      bundlerOptions: unknown,
      app: App,
      chainWebpack: (
        config: WebpackChainConfig,
        isServer: boolean,
        isBuild: boolean,
      ) => void,
    ) => void
    Example
    import { chainWebpack } from '@vuepress/helper'
    
    chainWebpack(bundlerOptions, app, (config, isServer, isBuild) => {
      // do some customize here
    })
  • configWebpack

    Config Webpack

    export const configWebpack: (
      bundlerOptions: unknown,
      app: App,
      configureWebpack: (
        config: WebpackConfiguration,
        isServer: boolean,
        isBuild: boolean,
      ) => void,
    ) => void
    Example
    import { configWebpack } from '@vuepress/helper'
    
    configWebpack(bundlerOptions, app, (config, isServer, isBuild) => {
      // do some customize here
    })
Edit this page on GitHub
Last Updated:: 1/10/25, 6:07 PM
Contributors: Mister-Hope, meteorlxy, pengzhanbo
Next
Locales Related