npm package: @talixo-ds/vite-plugin-copy-files
Description: Vite plugin for copying build artifacts to external directories
Latest version: 2.0.2

# @talixo-ds/vite-plugin-copy-files

A Vite plugin for copying build artifacts to external directories. Perfect for monorepo setups where you need to copy frontend build outputs to backend static directories (like Django static files).

## Installation

```bash
npm install --save-dev @talixo-ds/vite-plugin-copy-files
```

## Usage

### Basic Setup

```typescript
// vite.config.ts
import { defineConfig } from "vite";
import { copyFilesPlugin } from "@talixo-ds/vite-plugin-copy-files";

export default defineConfig({
	plugins: [
		copyFilesPlugin({
			destination: "../backend/static/frontend"
		})
	]
});
```

### Environment Variable Configuration

The plugin supports the `COPY_FILES_PATH` environment variable, which takes precedence over the `destination` option:

```bash
# Set destination via environment variable
COPY_FILES_PATH=../backend/static/frontend npm run build
```

```typescript
// vite.config.ts - destination will be overridden by env var
import { defineConfig } from "vite";
import { copyFilesPlugin } from "@talixo-ds/vite-plugin-copy-files";

export default defineConfig({
	plugins: [
		copyFilesPlugin() // Will use COPY_FILES_PATH env var
	]
});
```

### Advanced Configuration

```typescript
import { defineConfig } from "vite";
import { copyFilesPlugin } from "@talixo-ds/vite-plugin-copy-files";

export default defineConfig({
	plugins: [
		copyFilesPlugin({
			source: "dist", // Source directory (default: 'dist')
			destination: "../backend/static/frontend", // Destination directory
			cleanDestination: true, // Clean destination before copying (default: true)
			failOnError: true, // Fail build on copy errors (default: true)
			verbose: true, // Enable verbose logging (default: false)
			envVariableName: "STATIC_FILES_PATH", // Custom env var name (default: 'COPY_FILES_PATH')
			createDestination: true // Create destination if it doesn't exist (default: true)
		})
	]
});
```

## API Reference

### Plugin Options

```typescript
interface CopyFilesOptions {
	/**
	 * Source directory to copy from
	 * @default 'dist'
	 */
	source?: string;

	/**
	 * Destination directory to copy to
	 * Can be overridden by environment variable
	 */
	destination?: string;

	/**
	 * Whether to clean the destination directory before copying
	 * @default true
	 */
	cleanDestination?: boolean;

	/**
	 * Whether to fail the build on copy errors
	 * @default true
	 */
	failOnError?: boolean;

	/**
	 * Enable verbose logging
	 * @default false
	 */
	verbose?: boolean;

	/**
	 * Custom environment variable name for destination path
	 * @default 'COPY_FILES_PATH'
	 */
	envVariableName?: string;

	/**
	 * Whether to create destination directory if it doesn't exist
	 * @default true
	 */
	createDestination?: boolean;
}
```

### Functions

#### `copyFilesPlugin(options?: CopyFilesOptions): Plugin`

Creates the Vite plugin instance.

#### `copyFiles(options: CopyFilesOptions, projectRoot: string): Promise<CopyResult>`

Programmatically copy files (useful for testing or standalone usage).

## Use Cases

### Monorepo with Django Backend

```typescript
// Frontend app vite.config.ts
export default defineConfig({
	plugins: [
		copyFilesPlugin({
			destination: "../../backend/myapp/static/frontend",
			verbose: true
		})
	]
});
```

### Multiple Environments

```bash
# Development
COPY_FILES_PATH=../backend/static/dev npm run build

# Production
COPY_FILES_PATH=/var/www/static npm run build
```

### CI/CD Pipeline

```yaml
# .github/workflows/build.yml
- name: Build Frontend
  run: npm run build
  env:
   COPY_FILES_PATH: ./deployment/static
```

## Error Handling

The plugin validates paths and provides clear error messages:

- **Source directory doesn't exist**: Build fails with descriptive error
- **Destination not writable**: Build fails with permission error
- **No destination specified**: Build fails asking for destination config

You can control error behavior with the `failOnError` option:

```typescript
copyFilesPlugin({
	failOnError: false // Logs warnings instead of failing build
});
```

## Development

### Building

```bash
npm run build
```

### Testing

```bash
npm test
```

### Running Tests in Watch Mode

```bash
npm run test
```

## License

MIT