English | 中文

@laynezh/vite-plugin-lib-assets

A Vite Plugin extracts resource files referenced in library mode instead of embedded them as base64.

Install

npm i @laynezh/vite-plugin-lib-assets -D

Or

yarn add @laynezh/vite-plugin-lib-assets -D

Or

pnpm add @laynezh/vite-plugin-lib-assets -D

Usage

// vite.config.ts
import libAssetsPlugin from '@laynezh/vite-plugin-lib-assets'

export default defineConfig({
  plugins: [
    libAssetsPlugin({ /* options */ }),
  ],
})

Example: playground/

Hints

• If build.ssr is set to true, you might want to enable build.ssrEmitAssets, so assets are emitted.

Option

export interface Options {
  include?: string | RegExp | (string | RegExp)[]
  exclude?: string | RegExp | (string | RegExp)[]
  name?: string | ((resourcePath: string, resourceQuery: string) => string)
  limit?: number
  outputPath?: string | ((url: string, resourcePath: string, resourceQuery: string) => string)
  regExp?: RegExp
  publicUrl?: string
}

include

A valid picomatch pattern, or array of patterns indicate which files need to be handled by the plugin.

• Type: string | RegExp | (string | RegExp)[]
• Default: Same as Vite's default value for assetsInclude, you can find the complete list here.
• Example:

  libAssetsPlugin({
    include: /\.a?png(\?.*)?$/
  })

exclude

Same as include, but it is used to indicate the files that should to be omitted.

• Type: string | RegExp | (string | RegExp)[]
• Default: undefined.
• Example:

  libAssetsPlugin({
    exclude: /\.svg(\?.*)?$/
  })

name

Output name of the resource file, its usage aligns with the name option of the file-loader.

• Type: string | ((resourcePath: string, resourceQuery: string) => string)
• Default: '[contenthash].[ext]'
• Example:
  • string

    libAssetsPlugin({
      name: '[name].[contenthash:8].[ext]?[query]'
    })

  • function

    libAssetsPlugin({
      name: (resourcePath, resourceQuery) => {
        // `resourcePath` - `/absolute/path/to/file.js`
        // `resourceQuery` - `foo=bar`
    
        if (process.env.NODE_ENV === 'development') {
          return '[name].[ext]';
        }
    
        return  '[name].[contenthash:8].[ext]?[query]'
      },
    })

The complete list can be found at loader-utils#interpolatename

limit

Files larger than the limit will be extracted to the output directory, smaller files will remain embedded in the artifact in base64 format.

• Type: number，unit Byte
• Default: undefined，any size of resource files will be extracted
• Example:

  libAssetsPlugin({
    limit: 1024 * 8 // 8KB
  })

outputPath

Specify the output path where the extracted files will be placed.

• Type: string | ((url: string, resourcePath: string, resourceQuery: string) => string)
• Default: Vite's assetsDir configuration.
• Example:
  • string

    libAssetsPlugin({
      outputPath: 'images'
    })

  • function

    libAssetsPlugin({
      outputPath: (url, resourcePath, resourceQuery) => {
        // `url` - file name processed by the `name` option，eg: `logo.fb2133.png`
        // `resourcePath` - `/original/absolute/path/to/file.js`
        // `resourceQuery` - `foo=bar`
    
        return url.endsWith('.png') ? 'image' : 'assets'
      },
    })

regExp

Specifies a Regular Expression to extract parts of content(capture groups) from the file path and use [N] as placeholders in the name for replacement. Its usage aligns with the regexp option of the file-loader.

• Type: RegExp
• Default: undefined
• Example:

  libAssetsPlugin({
    regExp: /\/([^/]+)\/[^\.]+.png$/,
    name: '[1]-[name].[contenthash:8].[ext]'
  })

publicUrl

Access path prefix for built resource files. Once provided, it will take effect, even while building the cjs and esm formats.

• Type: string
• Default: ''
• Example:

  libAssetsPlugin({
    publicUrl: 'https://cdn.jsdelivr.net/npm/@laynezh/vite-plugin-lib-assets'
  })