@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

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

Usage

Basic Setup

// 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:

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

// 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

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

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

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

Multiple Environments

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

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

CI/CD Pipeline

# .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:

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

Development

Building

npm run build

Testing

npm test

Running Tests in Watch Mode

npm run test

License

MIT