Metalsmith Bundled Components

0.9.1 verified Fri May 01 auth: no javascript

A Metalsmith plugin (v0.9.1, active development) that automatically discovers, orders, and bundles CSS/JS files from component-based architectures using esbuild. It scans directories for components, validates requirements, resolves CSS @imports, and produces minified bundles with tree shaking. Key differentiators: convention-over-configuration with sensible defaults, support for both ESM and CommonJS, PostCSS integration via esbuild plugins, and a validation system for component properties to catch configuration errors early. Requires Node >=18.0.0 and metalsmith ^2.5.0 as a peer dependency. Release cadence is irregular with several major feature updates in 2024.

Common errors

error Error: Cannot find module 'metalsmith-bundled-components' ↓

cause Plugin not installed or not in node_modules.

fix

Run npm install metalsmith-bundled-components in your project directory.

error TypeError: bundledComponents is not a function ↓

cause Using named import instead of default import: `import { bundledComponents } from '...'`

fix

Use default import: import bundledComponents from 'metalsmith-bundled-components'

error Error: metalsmith.use() requires a function or plugin instance ↓

cause Calling bundledComponents() returns a plugin function, but forgetting parentheses passes the module constructor.

fix

Ensure you call bundledComponents() with parentheses: .use(bundledComponents())

Warnings

breaking Breaking changes may occur before v1.0.0. The API is stable but not finalized. ↓

fix Pin to a specific version (e.g., 0.9.1) and review changelog before upgrading.

deprecated use of require() for ESM-only packages may break in future Node versions. ↓

fix Use ESM import syntax for better compatibility with esbuild and future Node releases.

gotcha Node.js 18 or higher required; Node 16 and below are not supported. ↓

fix Upgrade Node.js to 18+ or use an older version of the plugin (not recommended).

gotcha Metalsmith 2.5.0 or higher required; older Metalsmith versions may not work. ↓

fix Update metalsmith to ^2.5.0.

Install

npm install metalsmith-bundled-components

yarn add metalsmith-bundled-components

pnpm add metalsmith-bundled-components

Imports

bundledComponents

wrong

const bundledComponents = require('metalsmith-bundled-components');

correct

import bundledComponents from 'metalsmith-bundled-components'

Default export. ESM is recommended, but CommonJS require also works in Node >=18.

bundledComponents

wrong

import { bundledComponents } from 'metalsmith-bundled-components'

correct

const bundledComponents = require('metalsmith-bundled-components');

CommonJS require works but named import is incorrect (default export only).

type
```
import type { Options } from 'metalsmith-bundled-components'
```
TypeScript users should import types via type import; Options interface describes plugin configuration.

Quickstart

Shows basic usage with custom component paths and bundled output destinations.

import Metalsmith from 'metalsmith';
import bundledComponents from 'metalsmith-bundled-components';
import { fileURLToPath } from 'url';
import { dirname } from 'path';

const __dirname = dirname(fileURLToPath(import.meta.url));

Metalsmith(__dirname)
  .use(bundledComponents({
    basePath: 'components/base',
    sectionsPath: 'components/sections',
    cssDest: 'assets/bundle.css',
    jsDest: 'assets/bundle.js'
  }))
  .build((err) => {
    if (err) throw err;
  });