vite-plugin-smart-assets

A Vite plugin that provides smart and enhanced control over asset management, copying, and cleanup. This plugin replaces the functionality of Vite's built-in emptyOutDir and copyPublicDir options with more intelligent and granular control.

Note: This plugin was primarily developed to improve the development experience when using Vite with Shopify themes, where precise control over asset management is essential for proper theme development.

Features

• Customizable public folder for static assets
• Selective file copying based on existence in output directory
• Smart cleanup of managed files during build
• Preserves build artifacts and non-managed files
• Optional HMR support for file copying
• Control over copy timing with copyAtStart option
• File filtering options for including, excluding, and preserving files
• Logging options for verbose, dry-run, and silent modes
• Transform options for modifying file content before copying
• Event hooks for customizing copy, delete, and error handling

Installation

npm install vite-plugin-smart-assets --save-dev

Usage

// vite.config.ts
import { defineConfig } from 'vite';
import smartAssets from 'vite-plugin-smart-assets';

export default defineConfig({
  plugins: [
    smartAssets({
      publicDir: 'public', // default
      outDir: 'dist', // default
      copyOnHMR: false, // default
      copyAtStart: true // default
    })
  ]
});

Cleanup Behavior

The plugin performs smart cleanup of files during the build process:

• Cleanup only occurs at the start of a new build
• Only files matching your include/exclude patterns are considered for cleanup
• Files created during or after the build (like build artifacts) are preserved
• Files specified in preserveFiles are always protected
• HMR updates only trigger file copying, not cleanup

This ensures that:

1. Your source files are properly synced to the output directory
2. Orphaned files from previous builds are removed
3. Build artifacts and non-managed files remain untouched
4. The development experience remains fast and efficient

Shopify Theme Usage Example

When using this plugin with a Shopify theme:

// vite.config.ts
import { defineConfig } from 'vite';
import smartAssets from 'vite-plugin-smart-assets';

export default defineConfig({
  plugins: [
    smartAssets({
      publicDir: 'theme/assets',  // your Shopify theme static assets directory to be copied from
      outDir: 'dist/assets',      // where your built assets and copied assets will be served from
      copyOnHMR: true,           // ensure assets are updated during development
      copyAtStart: true,         // copy assets at build start
      include: ['**/*.{jpg,png,gif,svg,liquid}'], // only manage theme asset files
      preserveFiles: ['settings_data.json']  // protect important theme files
    })
  ]
});

This setup ensures that your Shopify theme assets are properly managed during development, with automatic cleanup of removed assets and protection against accidental overwrites.

Options

• publicDir (string, default: 'public'): The directory containing static assets to copy
• outDir (string, default: 'dist'): The output directory where files will be copied
• copyOnHMR (boolean, default: false): Whether to copy files on HMR updates
• copyAtStart (boolean, default: true): Whether to copy files at build start

File Filtering Options

• include (string[], optional): Glob patterns for files to include (e.g., ['**/*.{jpg,png}']). Only matched files will be managed by the plugin.
• exclude (string[], optional): Glob patterns for files to exclude (e.g., ['**/*.temp.*'])
• preserveFiles (string[], optional): Files in outDir that should never be deleted (e.g., ['generated-manifest.json'])

Logging Options

• verbose (boolean, default: false): Enable detailed logging of all file operations
• dryRun (boolean, default: false): Show what would happen without making changes
• silent (boolean, default: false): Suppress all logs except errors

Transform Options

• transform (function, optional): Transform file content before copying

  (file: string, content: Buffer) => string | Buffer | Promise<string | Buffer>

• rename (function, optional): Rename files during copy

  (fileName: string) => string

Event Hooks

• onCopy (function, optional): Called after a file is copied

  (file: string) => void | Promise<void>

• onDelete (function, optional): Called after a file is deleted

  (file: string) => void | Promise<void>

• onError (function, optional): Called when an error occurs

  (error: Error, file: string) => void | Promise<void>

Common Use Cases

Static Site with Image Optimization

import { defineConfig } from 'vite';
import smartAssets from 'vite-plugin-smart-assets';
import sharp from 'sharp';

export default defineConfig({
  plugins: [
    smartAssets({
      include: ['**/*.{jpg,png,webp}'],  // only manage image files
      transform: async (file, content) => {
        if (file.endsWith('.jpg') || file.endsWith('.png')) {
          return await sharp(content)
            .resize(800, 800, { fit: 'inside' })
            .webp({ quality: 80 })
            .toBuffer();
        }
        return content;
      },
      rename: (fileName) => fileName.replace(/\.(jpg|png)$/, '.webp'),
      verbose: true
    })
  ]
});

Multi-Environment Configuration

import { defineConfig } from 'vite';
import smartAssets from 'vite-plugin-smart-assets';

export default defineConfig({
  plugins: [
    smartAssets({
      publicDir: process.env.NODE_ENV === 'production' ? 'public/prod' : 'public/dev',
      include: ['**/*.{css,js,jpg,png}'],  // only manage specific file types
      preserveFiles: ['generated-assets.json', 'manifest.json'],
      exclude: ['**/*.temp.*', '**/*.draft.*'],
      verbose: process.env.DEBUG === 'true'
    })
  ]
});

Development Workflow with Custom Hooks

import { defineConfig } from 'vite';
import smartAssets from 'vite-plugin-smart-assets';

export default defineConfig({
  plugins: [
    smartAssets({
      copyOnHMR: true,
      include: ['**/*.{css,js,jpg,png}'],  // only manage specific file types
      onCopy: async (file) => {
        console.log(`Asset updated: ${file}`);
        // Notify other build tools or services
        await notifyAssetUpdate(file);
      },
      onDelete: async (file) => {
        console.log(`Asset removed: ${file}`);
        // Clean up related files or caches
        await cleanupRelatedAssets(file);
      },
      onError: async (error, file) => {
        console.error(`Error processing ${file}:`, error);
        // Send error to monitoring service
        await notifyErrorMonitoring(error, file);
      }
    })
  ]
});

Shopify Theme with Asset Versioning

import { defineConfig } from 'vite';
import smartAssets from 'vite-plugin-smart-assets';
import { createHash } from 'crypto';

export default defineConfig({
  plugins: [
    smartAssets({
      publicDir: 'theme/assets',
      outDir: 'dist/assets',
      copyOnHMR: true,
      include: ['**/*.{css,js,jpg,png}'],  // only manage theme assets
      // Add content hash to filenames
      rename: (fileName) => {
        const ext = path.extname(fileName);
        const base = path.basename(fileName, ext);
        const hash = createHash('md5')
          .update(fs.readFileSync(path.join('theme/assets', fileName)))
          .digest('hex')
          .slice(0, 8);
        return `${base}.${hash}${ext}`;
      },
      // Preserve any dynamically generated files
      preserveFiles: ['settings_data.json', 'theme.liquid']
    })
  ]
});

How it works

1. The plugin checks for files in your public directory
2. It copies files that don't exist in the output directory
3. It removes files from the output directory that don't exist in the public directory
4. When copyOnHMR is enabled, it performs these operations on HMR updates
5. The copyAtStart option allows you to control whether files are copied before other plugins run

Note: The plugin uses a simple filename check to determine if a file should be copied, rather than comparing file contents or hashes. This means that if a file with the same name exists in the output directory, it won't be overwritten, even if its contents differ from the source file in the public directory. This approach prioritizes performance and simplicity over content verification.

Comparison with Similar Plugins

There are a few similar plugins in the ecosystem, but each serves different use cases:

vite-plugin-hmr-public-copy

• Similarities:

  • Copies files from public directory during HMR
  • Supports copyAtStart option
  • Designed specifically for public directory use case

• Differences:

  • This plugin adds automatic cleanup of orphaned files in the output directory
  • This plugin checks file existence before copying to prevent overwriting
  • This plugin provides a more complete replacement for Vite's built-in emptyOutDir and copyPublicDir options

vite-plugin-static-copy

• Similarities:

  • Handles file copying during build
  • Supports dev server integration

• Differences:

  • vite-plugin-static-copy requires explicit configuration of file targets
  • This plugin focuses specifically on public directory management
  • This plugin automatically handles cleanup of removed files
  • This plugin provides simpler configuration for public directory use cases

When to use this plugin: Choose this plugin if you need:

• A direct replacement for Vite's emptyOutDir and copyPublicDir with more control
• Automatic cleanup of removed files
• Protection against overwriting existing files
• Simple configuration focused on public directory management

When to use alternatives:

• Use vite-plugin-static-copy if you need to copy files from multiple sources to multiple destinations
• Use vite-plugin-hmr-public-copy if you only need HMR support without file cleanup functionality
• Use Vite's built-in options if you don't need the additional control and safety features

License

MIT