vite-plugin-static-copy

What is vite-plugin-static-copy?

vite-plugin-static-copy is a Vite plugin that allows you to copy static files or directories to the output directory during the build process. This is useful for including assets that are not part of the module system, such as images, fonts, or other static resources.

What are vite-plugin-static-copy's main functionalities?

Copying Single Files

This feature allows you to copy a single file from the source directory to the destination directory in the output. In this example, 'src/assets/logo.png' is copied to 'assets' in the output directory.

const { defineConfig } = require('vite');
const { viteStaticCopy } = require('vite-plugin-static-copy');

module.exports = defineConfig({
  plugins: [
    viteStaticCopy({
      targets: [
        { src: 'src/assets/logo.png', dest: 'assets' }
      ]
    })
  ]
});

Copying Multiple Files

This feature allows you to copy multiple files using a glob pattern. In this example, all PNG files in 'src/assets' are copied to 'assets' in the output directory.

const { defineConfig } = require('vite');
const { viteStaticCopy } = require('vite-plugin-static-copy');

module.exports = defineConfig({
  plugins: [
    viteStaticCopy({
      targets: [
        { src: 'src/assets/*.png', dest: 'assets' }
      ]
    })
  ]
});

Copying Directories

This feature allows you to copy entire directories. In this example, the 'src/static' directory is copied to 'static' in the output directory.

const { defineConfig } = require('vite');
const { viteStaticCopy } = require('vite-plugin-static-copy');

module.exports = defineConfig({
  plugins: [
    viteStaticCopy({
      targets: [
        { src: 'src/static', dest: 'static' }
      ]
    })
  ]
});

Other packages similar to vite-plugin-static-copy

copy-webpack-plugin

copy-webpack-plugin is a plugin for Webpack that copies individual files or entire directories to the build directory. It offers similar functionality to vite-plugin-static-copy but is designed for use with Webpack instead of Vite.

rollup-plugin-copy

rollup-plugin-copy is a Rollup plugin that copies files and directories to the output directory. It provides similar capabilities to vite-plugin-static-copy but is intended for use with Rollup.

gulp-copy

gulp-copy is a Gulp plugin that copies files from a source to a destination. It offers similar functionality but is designed for use with Gulp task runner instead of Vite.

README

vite-plugin-static-copy

rollup-plugin-copy for Vite with dev server support.

[!NOTE] Before you use this plugin, consider using public directory or import in JavaScript. In most cases, these will work.

Install

npm i -D vite-plugin-static-copy # yarn add -D vite-plugin-static-copy

Usage

Add viteStaticCopy plugin to vite.config.js / vite.config.ts.

// vite.config.js / vite.config.ts
import { viteStaticCopy } from 'vite-plugin-static-copy'

export default {
  plugins: [
    viteStaticCopy({
      targets: [
        {
          src: 'bin/example.wasm',
          dest: 'wasm-files'
        }
      ]
    })
  ]
}

For example, if you use the config above, you will be able to fetch bin/example.wasm with fetch('/wasm-files/example.wasm'). So the file will be copied to dist/wasm-files/example.wasm.

[!WARNING]

If you are using Windows, make sure to use normalizePath after doing path.resolve or else. \ is a escape charactor in fast-glob and you should use /.

import { normalizePath } from 'vite'
import path from 'node:path'

normalizePath(path.resolve(__dirname, './foo')) // C:/project/foo

// instead of
path.resolve(__dirname, './foo') // C:\project\foo

See fast-glob documentation about this for more details.

Options

See options.ts.

Differences with rollup-plugin-copy

• Faster dev server start-up than using rollup-plugin-copy on buildStart hook.
  • Files are not copied and served directly from the server during dev to reduce start-up time.
• dest is relative to build.outDir.
  • If you are going to copy files outside build.outDir, you could use rollup-plugin-copy instead. Because that does not require dev server support.
• fast-glob is used instead of globby.
  • Because fast-glob is used inside vite.
• transform could return null as a way to tell the plugin not to copy the file, this is similar to the CopyWebpackPlugin#filter option, but it expects transform to return the original content in case you want it to be copied.
• transform can optionally be an object, with a handler property (with the same signature of the rollup-plugin-copy transform option) and an encoding property (BufferEncoding | 'buffer') that will be used to read the file content so that the handler's content argument will reflect the correct encoding (could be Buffer);
• structured: true preserves the directory structure. This is similar to flatten: false in rollup-plugin-copy, but it covers more edge cases.

Changelog

2.2.0

Minor Changes

• #141 88e513d Thanks @sapphi-red! - add Vite 6 to peer dep