metalsmith-static-files

A Metalsmith plugin to copy a directory to the build directory

Features

• This plugin supports both ESM and CommonJS environments with no configuration needed:
  • ESM: import staticFiles from 'metalsmith-static-files'
  • CommonJS: const staticFiles = require('metalsmith-static-files')

Installation

npm install metalsmith-static-files

Usage

Pass metalsmith-static-files to metalsmith.use. The source directory path is resolved to metalsmith.directory(). The destination path is resolved to metalsmith.destination().

Typically, you want to use this plugin somewhere at the start of the chain, before any asset plugins are run, like @metalsmith/sass.

metalsmith.use(
  staticFiles({
    source: 'src/assets/',
    destination: 'assets/'
  })
)

Options

The plugin accepts the following options:

| Option | Type | Default | Description | | -------------------- | --------- | ------------ | ------------------------------------------------------ | | source | string | src/assets | Source directory path relative to Metalsmith root | | destination | string | assets | Destination directory path relative to build directory | | overwrite | boolean | true | Whether to overwrite existing files | | preserveTimestamps | boolean | false | Whether to preserve timestamps when copying files | | ignore | array | - | Array of glob patterns to exclude files (optional) |

Examples

Basic Usage

import Metalsmith from 'metalsmith'
import staticFiles from 'metalsmith-static-files'

Metalsmith(__dirname)
  .source('./src')
  .destination('./build')
  .use(staticFiles())
  .build((err) => {
    if (err) throw err
    console.log('Build complete!')
  })

With Options

import Metalsmith from 'metalsmith'
import staticFiles from 'metalsmith-static-files'

Metalsmith(__dirname)
  .source('./src')
  .destination('./build')
  .use(
    staticFiles({
      source: 'static',
      destination: 'public',
      overwrite: false,
      preserveTimestamps: true,
      ignore: ['**/*.tmp', '**/*.log'] // Exclude temporary files
    })
  )
  .build((err) => {
    if (err) throw err
  })

Advanced Usage

Using Ignore Patterns

metalsmith.use(
  staticFiles({
    source: 'static',
    destination: 'public',
    overwrite: false, // Don't overwrite existing files
    preserveTimestamps: true, // Keep original timestamps
    ignore: ['**/*.tmp', '**/*.bak', '**/cache/**'] // Exclude temporary files and cache
  })
)

Common Use Cases

// Exclude specific files
metalsmith.use(
  staticFiles({
    source: 'lib/assets/',
    destination: 'assets/',
    ignore: ['main.css', 'main.js'] // Exclude processed files
  })
)

// Exclude entire directories (all patterns work the same)
metalsmith.use(
  staticFiles({
    source: 'lib/assets/',
    destination: 'assets/',
    ignore: ['styles/', 'temp/', 'cache/'] // Exclude entire directories
  })
)

// Mixed patterns
metalsmith.use(
  staticFiles({
    source: 'lib/assets/',
    destination: 'assets/',
    ignore: [
      '*.tmp', // Exclude temp files
      '*.log', // Exclude log files
      'styles/', // Exclude styles directory
      'node_modules/', // Exclude node_modules directory
      '**/.DS_Store' // Exclude .DS_Store files everywhere
    ]
  })
)

Directory Exclusion Patterns

Key Feature: All directory patterns exclude the entire directory structure - no empty directories are created.

All of these patterns have identical behavior and exclude the complete directory:

• 'styles/' - Directory with trailing slash
• 'styles/*' - All files in directory
• 'styles/**' - Directory and all subdirectories

Important: The plugin excludes directories at the directory level, not just their contents. This means when you use any of these patterns, the entire styles/ directory and everything inside it will be completely excluded from the copy operation. No empty styles/ directory will be created in the destination.

Example:

Source directory:
assets/
├── images/
│   └── logo.png
├── styles/
│   ├── main.css
│   └── components/
│       └── button.css
└── scripts/
    └── app.js

With ignore: ['styles/']

Result directory:
assets/
├── images/
│   └── logo.png
└── scripts/
    └── app.js

Notice: No empty styles/ directory is created - it's completely excluded.

Debug

To enable debug logs, set the DEBUG environment variable to metalsmith-static-files:

DEBUG=metalsmith-static-files

CLI usage

To use this plugin with the Metalsmith CLI, add metalsmith-static-files to the plugins key in your metalsmith.json file:

{
  "plugins": [
    {
      "metalsmith-static-files": {}
    }
  ]
}

Author

[email protected]

License

MIT