📎 Metalsmith plugin to concatenate files
JavaScript CSS
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


NPM version Linux and OS X build status Windows build status Dependencies


A Metalsmith plugin to concatenate files.


$ npm install metalsmith-concat



  "plugins": {
    "metalsmith-concat": {
      "files": "styles/**/*.css",
      "output": "styles/app.css"


import MetalSmith from 'metalsmith';
import concat from 'metalsmith-concat';

new Metalsmith(__dirname)
    files: 'styles/**/*.css',
    output: 'styles/app.css',


Type: String / String[] Default: '**/*'

This defines which files are concatenated. This string will be interpreted as a minimatch pattern. An array of strings will be interpreted as minimatch patterns, in this case the order of the patterns matters (it will determine the order in which the files are concatenated).

Note: this is relative to the source path and the search paths (if any).


Type: String

It represents the filepath where the concatenated content will be outputted. This option is mandatory.

Note: this is relative to the destination path.


Type: Boolean Default: false

By default metalsmith-concat return an error if the output file already exists. You can force an existing output file to be overwritten by setting this option to true.


Type: Boolean | String Default: true

Whether a trailing new line (\n) should be appended after each concatenated file. Unless you face a problem, you should keep this option enabled as removing it could cause invalid concatenated files (see this article). It is also possible to pass a string, in which case it will be used instead of \n.


Type: Boolean Default: false

Whether to keep the files which were concatenated. By default they are not kept and deleted from the build (thus only keeping the newly created file at options.output).


Type: String / String[] Default: []

The additional paths to search after the src directory given to Metalsmith. The paths are resolved relatively to the metalsmith root directory. Absolute paths can also been given. An ignore pattern is applied on the results to make sure the src directory is not matched twice from a search path.

Let's consider the following example:


It is possible to include React from the node_modules before your index.js from src by using the following configuration:

  files: [
    'react/dist/react.min.js', // found in node_modules
    'index.js' // found in src
  searchPaths: ['node_modules'],


  • 6.0.0

    • Expect and produce a Buffer for the contents key
  • 5.0.2

    • Simplify the path given in the pattern
  • 5.0.1

    • Fix 100% code coverage on Node 4 (sandboxed-module -> proxyquire)
  • 5.0.0

    • Add the searchPaths option
    • Switch test suite to nyc + ava
  • 4.2.2

    • Lightweight npm-shrinkwrap
  • 4.2.1

    • Update license to public domain
  • 4.2.0

    • Require options.output to be a non-empty string
  • 4.1.1

    • Exclude test files from CodeClimate
  • 4.1.0

    • It is possible to override existing output file check by setting options.forceOutput to true (#19)
    • Handle metalsmith errors gracefully as described here
  • 4.0.1

    • Drop node 0.10 and 0.12 support as Metalsmith requires generators
  • 4.0.0

    • Update dependencies
    • Remove npm-shrinkwrap
    • Fix linting
    • Add node 4 and 5 to Travis/AppVeyor
  • 3.0.0

    • An array of minimatch patterns can now be passed as options.files (#6, #9)
    • File paths are normalized, hence making this plugin working on Windows (#8)
    • It is possible to pass a custom options.insertNewline character
  • 2.0.0

    • Add a newline at the end of each concatenated file by default (#4)
  • 1.0.1

    • Add the possibility to pass an array of files instead of a matching pattern (#2)
  • 1.0.0

    • Bump stable
  • 0.0.2

    • Fix an issue with file content
  • 0.0.1

    • Working plugin



To the extent possible under law, Aymeric Beaumet has waived all copyright and related or neighboring rights to this work.