{"id":14242,"library":"vite-plugin-static-copy","title":"Vite Static Asset Copy Plugin","description":"vite-plugin-static-copy is a Vite plugin designed to copy static assets during both development and production builds, mirroring the functionality of `rollup-plugin-copy` but optimized for Vite's ecosystem. It is currently at version 4.1.0 and maintains an active release cadence with frequent updates and bug fixes, often several per month. Key differentiators include its dedicated dev server support, which avoids copying files during development for faster startup times by serving them directly. Unlike Vite's built-in public directory, this plugin allows for more granular control over specific files and directories, offering options like renaming, stripping base paths (`stripBase`), and transformation of content. It specifically targets scenarios where assets need to be programmatically managed or placed outside the standard public directory, or when `import` statements are not suitable for asset inclusion. It uses `tinyglobby` for pattern matching, aligning with Vite's internal dependencies, and preserves directory structure by default, unlike `rollup-plugin-copy`'s default `flatten: true`.","status":"active","version":"4.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/sapphi-red/vite-plugin-static-copy","tags":["javascript","vite","vite-plugin","typescript"],"install":[{"cmd":"npm install vite-plugin-static-copy","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-static-copy","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-static-copy","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for Vite plugin integration.","package":"vite","optional":false}],"imports":[{"note":"This package is primarily consumed as an ESM module within `vite.config.ts` or `vite.config.js`.","wrong":"const viteStaticCopy = require('vite-plugin-static-copy')","symbol":"viteStaticCopy","correct":"import { viteStaticCopy } from 'vite-plugin-static-copy'"},{"note":"Type import for configuring the plugin options. Useful for TypeScript users to ensure correct configuration.","symbol":"ViteStaticCopyOptions","correct":"import type { ViteStaticCopyOptions } from 'vite-plugin-static-copy'"},{"note":"Type import for the `rename` option's object form, including `stripBase` and `name` properties.","symbol":"RenameOptions","correct":"import type { RenameOptions } from 'vite-plugin-static-copy'"}],"quickstart":{"code":"import { defineConfig, normalizePath } from 'vite';\nimport { viteStaticCopy } from 'vite-plugin-static-copy';\nimport path from 'node:path';\n\nexport default defineConfig({\n  plugins: [\n    viteStaticCopy({\n      targets: [\n        {\n          src: normalizePath(path.resolve(__dirname, 'public/images/**/*')), // Copy all images\n          dest: 'assets/images', // To dist/assets/images\n        },\n        {\n          src: 'node_modules/some-lib/dist/web-worker.js', // Copy a specific web worker\n          dest: 'workers', // To dist/workers\n          rename: 'my-worker.js', // Rename it\n        },\n        {\n          src: 'src/data/**/*.json', // Copy JSON files, stripping base path\n          dest: 'data',\n          rename: { stripBase: 1 }, // `src/data/config.json` -> `dist/data/config.json`\n        },\n        {\n          src: normalizePath(path.resolve(__dirname, 'assets/favicon.ico')),\n          dest: '', // Copy to the root of the output directory\n        }\n      ]\n    })\n  ]\n});","lang":"typescript","description":"Demonstrates how to configure `vite-plugin-static-copy` in `vite.config.ts` to copy various static assets, including renaming and stripping base directories, using `normalizePath` for Windows compatibility."},"warnings":[{"fix":"Update `src` glob patterns to explicitly match files (e.g., use `path/to/dir/**/*` instead of `path/to/dir`).","message":"Starting with v4.0.0, the plugin's glob behavior was simplified. Glob patterns now only match files, not directories. Previously, matching a directory would recursively copy its contents. This means you must explicitly match files (e.g., `dir/**/*` instead of `dir`).","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Always wrap `path.resolve()` calls for `src` paths with `normalizePath` from Vite (e.g., `normalizePath(path.resolve(__dirname, './foo'))`).","message":"On Windows, `path.resolve` returns backslash-separated paths (e.g., `C:\\project\\foo`), which are treated as escape characters by the underlying `tinyglobby` library. This can lead to incorrect or no matches for `src` paths.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Ensure `dest` paths are relative to your `build.outDir` or use an alternative plugin for copying outside this directory.","message":"The `dest` option is relative to Vite's `build.outDir` (default `dist`). If you need to copy files outside of `build.outDir`, this plugin is not suitable during the build phase; consider `rollup-plugin-copy` instead for non-dev server related copying.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Review complex `rename` functions to ensure compatibility or leverage the new `name` and `stripBase` object forms for simpler configuration.","message":"Version 4.1.0 introduced new capabilities for the `rename` option, allowing it to be an object with a `name` property to replace the file's basename or a `RenameObject` returned by a rename function. While an enhancement, ensure existing complex rename functions handle this new type if they were previously returning only strings.","severity":"breaking","affected_versions":">=4.1.0"},{"fix":"If copying is needed for non-client environments (e.g., SSR), use the `environment` option: `{ environment: ['client', 'ssr'] }` or `{ environment: 'all' }`.","message":"Prior to v3.1.5, the plugin would copy for all environments if multiple existed. Since v3.1.5, it defaults to only copying for the client environment, which was then made configurable via the `environment` option in v3.2.0. If your build process involves multiple environments and requires static copy in non-client contexts, you might need to adjust this option.","severity":"gotcha","affected_versions":">=3.1.5"}],"env_vars":null,"search_vec":"'4.1.0':45 'activ':49 'align':150 'allow':94 'asset':3,19,121,142 'avoid':71 'base':109 'bug':56 'build':25 'built':88 'built-in':87 'cadenc':51 'content':115 'control':98 'copi':4,10,17,33,72,166 'current':42 'dedic':66 'default':161,168 'depend':155 'design':15 'dev':67 'develop':22,75 'differenti':63 'direct':83 'directori':91,103,133,158 'ecosystem':39 'faster':77 'file':73,101 'fix':57 'flatten':169 'frequent':53 'function':28 'granular':97 'import':136 'includ':64 'inclus':143 'intern':154 'javascript':171 'key':62 'like':106 'maintain':47 'manag':126 'match':149 'mirror':26 'month':61 'need':122 'offer':104 'often':58 'optim':35 'option':105 'outsid':129 'path':110 'pattern':148 'per':60 'place':128 'plugin':5,8,14,32,93,165,175 'preserv':157 'product':24 'programmat':125 'public':90,132 'releas':50 'renam':107 'rollup':31,164 'rollup-plugin-copi':30,163 'scenario':119 'serv':81 'server':68 'sever':59 'specif':100,117 'standard':131 'startup':78 'statement':137 'static':2,9,18 'strip':108 'stripbas':111 'structur':159 'suitabl':140 'support':69 'target':118 'time':79 'tinyglobbi':146 'transform':113 'true':170 'typescript':176 'unlik':84,162 'updat':54 'use':145 'version':44 'vite':1,7,13,37,85,152,172,174 'vite-plugin':173 'vite-plugin-static-copi':6","created_at":"2026-04-20T01:58:40.976642+00:00","updated_at":"2026-04-20T01:58:40.976642+00:00","problems":[{"fix":"Ensure all `path.resolve` outputs used in `src` options are passed through Vite's `normalizePath`: `src: normalizePath(path.resolve(__dirname, 'public/images/**/*'))`.","cause":"Using `path.resolve` directly on Windows for `src` paths without `normalizePath`, leading to incorrect absolute paths being passed to the glob library, causing unexpected nested directory creation.","error":"Error: EEXIST: file already exists, mkdir 'C:\\project\\dist\\assets\\images\\C:\\project\\public\\images'"},{"fix":"Verify that each object within the `targets` array has a `src` property defined with a valid glob string or an array of strings.","cause":"Incorrectly defined `targets` array or missing `src` property within a target object in the `viteStaticCopy` configuration.","error":"Vite config error: [vite-plugin-static-copy] 'src' must be a string or array of strings, or an array of objects. Received: undefined"},{"fix":"Double-check `src` glob patterns for correctness (e.g., ensure `**/*` is used to match files inside directories). If running a non-client build, explicitly set the `environment` option (e.g., `{ environment: 'all' }`). Enable debug logging with `DEBUG=vite:plugin-static-copy npm run dev` to see matched files.","cause":"The glob pattern specified in `src` is incorrect or too restrictive, failing to match any files, or the `environment` option is not configured correctly for the build process.","error":"Files are not being copied to the `dist` directory, but there are no errors."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/sapphi-red/vite-plugin-static-copy","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/vite-plugin-static-copy","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}