0
# Rollup Plugin Copy
1

2
Rollup Plugin Copy provides comprehensive file and folder copying functionality during the build process, supporting glob patterns, multiple targets, and advanced features like file transformation and renaming. It offers flexible configuration options including synchronous/asynchronous copying, directory structure flattening, verbose output, and various Rollup hooks for different build phases.
3

4
## Package Information
5

6
- **Package Name**: rollup-plugin-copy
7
- **Package Type**: npm (Rollup plugin)
8
- **Language**: JavaScript (ES modules)
9
- **Installation**: `npm install rollup-plugin-copy -D`
10

11
## Core Imports
12

13
```javascript
14
import copy from 'rollup-plugin-copy';
15
```
16

17
For CommonJS:
18

19
```javascript
20
const copy = require('rollup-plugin-copy');
21
```
22

23
## Basic Usage
24

25
```javascript
26
// rollup.config.js
27
import copy from 'rollup-plugin-copy';
28

29
export default {
30
  input: 'src/index.js',
31
  output: {
32
    file: 'dist/app.js',
33
    format: 'cjs'
34
  },
35
  plugins: [
36
    copy({
37
      targets: [
38
        { src: 'src/index.html', dest: 'dist/public' },
39
        { src: ['assets/fonts/arial.woff', 'assets/fonts/arial.woff2'], dest: 'dist/public/fonts' },
40
        { src: 'assets/images/**/*', dest: 'dist/public/images' }
41
      ]
42
    })
43
  ]
44
};
45
```
46

47
## Capabilities
48

49
### Copy Plugin Factory
50

51
Creates a Rollup plugin that copies files and folders based on configuration.
52

53
```typescript { .api }
54
/**
55
 * Creates a Rollup plugin for copying files and folders
56
 * @param options - Configuration options for the copy plugin
57
 * @returns Rollup plugin object with name and hook handlers
58
 */
59
function copy(options?: CopyOptions): RollupPlugin;
60

61
interface RollupPlugin {
62
  name: string;
63
  [hook: string]: any;
64
}
65

66
interface CopyOptions {
67
  /**
68
   * Copy items once. Useful in watch mode.
69
   * @default false
70
   */
71
  readonly copyOnce?: boolean;
72

73
  /**
74
   * Copy items synchronous.
75
   * @default false
76
   */
77
  readonly copySync?: boolean;
78

79
  /**
80
   * Remove the directory structure of copied files.
81
   * @default true
82
   */
83
  readonly flatten?: boolean;
84

85
  /**
86
   * Rollup hook the plugin should use.
87
   * @default 'buildEnd'
88
   */
89
  readonly hook?: string;
90

91
  /**
92
   * Array of targets to copy.
93
   * @default []
94
   */
95
  readonly targets?: readonly Target[];
96

97
  /**
98
   * Output copied items to console.
99
   * @default false
100
   */
101
  readonly verbose?: boolean;
102

103
  /**
104
   * Global glob pattern matching options (inherited by all targets)
105
   */
106
  readonly dot?: boolean;
107
  readonly expandDirectories?: boolean;
108
  readonly ignore?: string | readonly string[];
109
  readonly gitignore?: boolean;
110
  readonly absolute?: boolean;
111
  readonly onlyFiles?: boolean;
112
  readonly onlyDirectories?: boolean;
113

114
  /**
115
   * File system copy options
116
   */
117
  readonly overwrite?: boolean;
118
  readonly errorOnExist?: boolean;
119
  readonly dereference?: boolean;
120
  readonly preserveTimestamps?: boolean;
121

122
  /**
123
   * File writing options (for transformed files)
124
   */
125
  readonly encoding?: string;
126
  readonly mode?: number;
127
  readonly flag?: string;
128
}
129

130
interface Target {
131
  /**
132
   * Path or glob of what to copy.
133
   */
134
  readonly src: string | readonly string[];
135

136
  /**
137
   * One or more destinations where to copy.
138
   */
139
  readonly dest: string | readonly string[];
140

141
  /**
142
   * Change destination file or folder name.
143
   */
144
  readonly rename?: string | ((name: string, extension: string, fullPath: string) => string);
145

146
  /**
147
   * Modify file contents.
148
   */
149
  readonly transform?: (contents: Buffer, name: string) => any;
150

151
  /**
152
   * Glob pattern matching options
153
   */
154
  readonly dot?: boolean;
155
  readonly expandDirectories?: boolean;
156
  readonly ignore?: string | readonly string[];
157
  readonly gitignore?: boolean;
158
  readonly absolute?: boolean;
159
  readonly onlyFiles?: boolean;
160
  readonly onlyDirectories?: boolean;
161
}
162
```
163

164
**Usage Examples:**
165

166
```javascript
167
// Single file copy
168
copy({
169
  targets: [{ src: 'src/index.html', dest: 'dist/public' }]
170
});
171

172
// Multiple files with glob patterns
173
copy({
174
  targets: [
175
    { src: 'assets/*', dest: 'dist/public' },
176
    { src: ['src/index.html', 'src/styles.css'], dest: 'dist/public' }
177
  ]
178
});
179

180
// Multiple destinations
181
copy({
182
  targets: [{ src: 'src/index.html', dest: ['dist/public', 'build/public'] }]
183
});
184

185
// File renaming with string
186
copy({
187
  targets: [{ src: 'src/app.html', dest: 'dist/public', rename: 'index.html' }]
188
});
189

190
// File renaming with function
191
copy({
192
  targets: [{
193
    src: 'assets/docs/*',
194
    dest: 'dist/public/docs',
195
    rename: (name, extension, fullPath) => `${name}-v1.${extension}`
196
  }]
197
});
198

199
// File content transformation
200
copy({
201
  targets: [{
202
    src: 'src/index.html',
203
    dest: 'dist/public',
204
    transform: (contents, filename) => contents.toString().replace('__SCRIPT__', 'app.js')
205
  }]
206
});
207

208
// Advanced configuration
209
copy({
210
  targets: [
211
    { src: 'assets/images/**/*', dest: 'dist/public/images' }
212
  ],
213
  verbose: true,
214
  copyOnce: true,
215
  flatten: false,
216
  hook: 'writeBundle'
217
});
218
```
219

220
### Configuration Options
221

222
#### targets
223
Array of copy target objects. Each target specifies what to copy (`src`) and where to copy it (`dest`), with optional renaming and transformation.
224

225
- **src**: Can be a single path/glob string or array of paths/globs
226
- **dest**: Can be a single destination path or array of destination paths
227
- **rename**: Optional string or function for renaming files
228
- **transform**: Optional function for modifying file contents (only works on files, not directories)
229

230
#### verbose
231
When `true`, outputs detailed information about copied files to the console, including transformation and renaming flags.
232

233
#### hook
234
Specifies which Rollup build hook to use for the copy operation. Default is `'buildEnd'`. Other common options include `'writeBundle'`, `'generateBundle'`, etc.
235

236
#### copyOnce
237
When `true`, files are only copied once, which is useful in watch mode to prevent redundant copying on every rebuild.
238

239
#### copySync
240
When `true`, uses synchronous file operations instead of asynchronous ones.
241

242
#### flatten
243
When `true` (default), removes the directory structure of source files when copying. When `false`, preserves the original directory structure relative to the source root.
244

245
#### Global Options
246

247
**Glob Pattern Options (applied to all targets unless overridden):**
248
- **dot**: Include files starting with a dot (hidden files)
249
- **expandDirectories**: Expand directories to their contents
250
- **ignore**: Patterns to exclude from matching
251
- **gitignore**: Respect .gitignore files
252
- **absolute**: Return absolute paths
253
- **onlyFiles**: Only match files (not directories)
254
- **onlyDirectories**: Only match directories (not files)
255

256
**File System Copy Options:**
257
- **overwrite**: Replace existing files (default: true)
258
- **errorOnExist**: Throw error if destination exists
259
- **dereference**: Follow symbolic links
260
- **preserveTimestamps**: Preserve file timestamps
261

262
**File Writing Options (for transformed files):**
263
- **encoding**: Text encoding for file writes
264
- **mode**: File permissions mode
265
- **flag**: File system flag for write operations
266

267
### Error Handling
268

269
The plugin validates configuration and throws errors for:
270
- Invalid target objects (must be plain objects)
271
- Missing required `src` or `dest` properties in targets
272
- Invalid `rename` property type (must be string or function)
273
- Using `transform` option on non-file sources (directories)
274

275
### Glob Pattern Support
276

277
Uses globby for pattern matching, supporting:
278
- Standard glob patterns (`*`, `**`, `?`)
279
- Negated patterns (`!**/*.test.js`)
280
- Array of patterns with mixed inclusion/exclusion
281
- Advanced globby options for fine-grained control