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
  })