0
# Vite Plugin Static Copy
1

2
Vite plugin for copying static files to build output with development server support. It serves as an alternative to `rollup-plugin-copy` specifically optimized for Vite workflows, providing faster dev server startup by serving files directly during development without copying.
3

4
## Package Information
5

6
- **Package Name**: vite-plugin-static-copy
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install -D vite-plugin-static-copy`
10

11
## Core Imports
12

13
```typescript
14
import { viteStaticCopy } from "vite-plugin-static-copy";
15
```
16

17
For type imports:
18

19
```typescript
20
import type { ViteStaticCopyOptions, Target, RenameFunc, TransformFunc } from "vite-plugin-static-copy";
21
import type { WatchOptions } from "chokidar";
22
```
23

24
## Basic Usage
25

26
```typescript
27
import { defineConfig } from "vite";
28
import { viteStaticCopy } from "vite-plugin-static-copy";
29

30
export default defineConfig({
31
  plugins: [
32
    viteStaticCopy({
33
      targets: [
34
        {
35
          src: "bin/example.wasm",
36
          dest: "wasm-files"
37
        }
38
      ]
39
    })
40
  ]
41
});
42
```
43

44
The above configuration will copy `bin/example.wasm` to `dist/wasm-files/example.wasm` during build, and serve it directly at `/wasm-files/example.wasm` during development.
45

46
## Capabilities
47

48
### Plugin Factory Function
49

50
Creates and returns an array of Vite plugins for static file copying.
51

52
```typescript { .api }
53
/**
54
 * Creates Vite plugins for static file copying with dev server support
55
 * @param options - Configuration options for the plugin
56
 * @returns Array of two Vite plugins (serve plugin and build plugin)
57
 */
58
function viteStaticCopy(options: ViteStaticCopyOptions): Plugin[];
59
```
60

61
**Usage Examples:**
62

63
```typescript
64
// Basic usage
65
viteStaticCopy({
66
  targets: [
67
    { src: "assets/*.wasm", dest: "wasm" }
68
  ]
69
});
70

71
// Advanced configuration
72
viteStaticCopy({
73
  targets: [
74
    {
75
      src: "data/**/*.json",
76
      dest: "api-data",
77
      rename: (name, ext) => `${name}.processed${ext}`
78
    }
79
  ],
80
  structured: true,
81
  silent: false,
82
  watch: {
83
    reloadPageOnChange: true
84
  }
85
});
86
```
87

88
## Configuration Types
89

90
### Main Options Interface
91

92
```typescript { .api }
93
interface ViteStaticCopyOptions {
94
  /** Array of targets to copy (required) */
95
  targets: Target[];
96
  /** Preserve the directory structure (default: false) */
97
  structured?: boolean;
98
  /** Suppress console output and ignore validation errors (default: false) */
99
  silent?: boolean;
100
  /** Watch configuration for development */
101
  watch?: {
102
    /** Chokidar watch options (from 'chokidar' package) */
103
    options?: WatchOptions;
104
    /** Reloads page on file change (default: false) */
105
    reloadPageOnChange?: boolean;
106
  };
107
  /** Rollup hook to use during build (default: 'writeBundle') */
108
  hook?: string;
109
}
110
```
111

112
### Target Configuration
113

114
```typescript { .api }
115
interface Target {
116
  /** Source path or glob pattern(s) (required) */
117
  src: string | string[];
118
  /** Destination directory (required) */
119
  dest: string;
120
  /** Rename pattern or function */
121
  rename?: string | RenameFunc;
122
  /** File transformation options */
123
  transform?: TransformOption;
124
  /** Should timestamps on copied files be preserved? (default: false) */
125
  preserveTimestamps?: boolean;
126
  /** Whether to dereference symlinks (default: true) */
127
  dereference?: boolean;
128
  /** Whether to overwrite existing files (default: true) */
129
  overwrite?: boolean | "error";
130
}
131
```
132

133
### Transform Functions
134

135
```typescript { .api }
136
/**
137
 * Function to rename files during copying
138
 * @param fileName - Base filename without extension
139
 * @param fileExtension - File extension including the dot
140
 * @param fullPath - Full path to the source file
141
 * @returns New filename (can be Promise)
142
 */
143
type RenameFunc = (
144
  fileName: string,
145
  fileExtension: string,
146
  fullPath: string
147
) => string | Promise<string>;
148

149
/**
150
 * Function to transform file content during copying
151
 * @param content - File content as string or Buffer
152
 * @param filename - Absolute path to the file
153
 * @returns Transformed content, or null to skip copying
154
 */
155
type TransformFunc<T extends string | Buffer> = (
156
  content: T,
157
  filename: string
158
) => T | null | Promise<T | null>;
159

160
/** Transform option can be a function or configuration object */
161
type TransformOption = TransformFunc<string> | TransformOptionObject;
162

163
type TransformOptionObject = 
164
  | {
165
      encoding: Exclude<BufferEncoding, "binary">;
166
      handler: TransformFunc<string>;
167
    }
168
  | {
169
      encoding: "buffer";
170
      handler: TransformFunc<Buffer>;
171
    };
172
```
173

174
### Watch Options
175

176
```typescript { .api }
177
/**
178
 * Chokidar watch options interface (from 'chokidar' package)
179
 * Used in the watch.options property of ViteStaticCopyOptions
180
 */
181
interface WatchOptions {
182
  /** Indicates whether the process should continue to run as long as files are being watched */
183
  persistent?: boolean;
184
  /** Indicates whether to watch files that don't have read permissions */
185
  ignored?: string | RegExp | ((path: string) => boolean);
186
  /** If set to true then the strings passed to .watch() are treated as literal path names */
187
  ignoreInitial?: boolean;
188
  /** When false, only the symlinks themselves will be watched for changes instead of following the link references */
189
  followSymlinks?: boolean;
190
  /** The base directory from which watch paths are to be derived */
191
  cwd?: string;
192
  /** If set to true then the strings passed to .watch() are treated as glob patterns */
193
  disableGlobbing?: boolean;
194
  /** Whether to use fs.watchFile (backed by polling), or fs.watch */
195
  usePolling?: boolean;
196
  /** Interval of file system polling, in ms */
197
  interval?: number;
198
  /** Interval of file system polling for binary files, in ms */
199
  binaryInterval?: number;
200
  /** Indicates whether to watch dotfiles */
201
  ignorePermissionErrors?: boolean;
202
  /** Indicates how many levels of subdirectories will be traversed */
203
  depth?: number;
204
  /** Path to chokidar binary on Windows */
205
  awaitWriteFinish?: boolean | { stabilityThreshold?: number; pollInterval?: number };
206
}
207
```
208

209
**Transform Usage Examples:**
210

211
```typescript
212
// String-based transformation
213
{
214
  src: "config/*.json",
215
  dest: "configs",
216
  transform: (content, filename) => {
217
    const config = JSON.parse(content);
218
    config.buildTime = new Date().toISOString();
219
    return JSON.stringify(config, null, 2);
220
  }
221
}
222

223
// Buffer-based transformation
224
{
225
  src: "images/*.png",
226
  dest: "processed-images",
227
  transform: {
228
    encoding: "buffer",
229
    handler: (buffer, filename) => {
230
      // Process image buffer
231
      return processImage(buffer);
232
    }
233
  }
234
}
235

236
// Conditional copying (return null to skip)
237
{
238
  src: "docs/*.md",
239
  dest: "documentation",
240
  transform: (content, filename) => {
241
    if (content.includes("DRAFT")) return null;
242
    return content.replace(/DRAFT/g, "");
243
  }
244
}
245
```
246

247
## Common Use Cases
248

249
### WebAssembly Files
250

251
```typescript
252
viteStaticCopy({
253
  targets: [
254
    {
255
      src: "wasm/*.wasm",
256
      dest: "wasm-modules"
257
    }
258
  ]
259
});
260
```
261

262
### Static Assets with Glob Patterns
263

264
```typescript
265
viteStaticCopy({
266
  targets: [
267
    {
268
      src: ["assets/images/*", "assets/fonts/*"],
269
      dest: "static"
270
    }
271
  ]
272
});
273
```
274

275
### Structured Directory Copying
276

277
```typescript
278
viteStaticCopy({
279
  targets: [
280
    {
281
      src: "public-data/**/*",
282
      dest: "data"
283
    }
284
  ],
285
  structured: true  // Preserves directory structure
286
});
287
```
288

289
### Development Server with Auto-reload
290

291
```typescript
292
viteStaticCopy({
293
  targets: [
294
    {
295
      src: "content/*.json",
296
      dest: "api"
297
    }
298
  ],
299
  watch: {
300
    reloadPageOnChange: true
301
  }
302
});
303
```
304

305
## Dependencies
306

307
- **chokidar**: File watching during development
308
- **fast-glob**: Glob pattern matching
309
- **fs-extra**: Enhanced file system operations
310
- **p-map**: Promise mapping utility
311
- **picocolors**: Terminal colors for console output
312

313
## Peer Dependencies
314

315
- **vite**: ^5.0.0 || ^6.0.0