{"id":25932,"library":"metalsmith-bundled-components","title":"Metalsmith Bundled Components","description":"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.","status":"active","version":"0.9.1","language":"javascript","source_language":"en","source_url":"https://github.com/wernerglinka/metalsmith-bundled-components","tags":["javascript","metalsmith","metalsmith-plugin","components","assets","bundler","esbuild","css"],"install":[{"cmd":"npm install metalsmith-bundled-components","lang":"bash","label":"npm"},{"cmd":"yarn add metalsmith-bundled-components","lang":"bash","label":"yarn"},{"cmd":"pnpm add metalsmith-bundled-components","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency required for plugin integration","package":"metalsmith","optional":false}],"imports":[{"note":"Default export. ESM is recommended, but CommonJS require also works in Node >=18.","wrong":"const bundledComponents = require('metalsmith-bundled-components');","symbol":"bundledComponents","correct":"import bundledComponents from 'metalsmith-bundled-components'"},{"note":"CommonJS require works but named import is incorrect (default export only).","wrong":"import { bundledComponents } from 'metalsmith-bundled-components'","symbol":"bundledComponents","correct":"const bundledComponents = require('metalsmith-bundled-components');"},{"note":"TypeScript users should import types via type import; Options interface describes plugin configuration.","wrong":"","symbol":"type","correct":"import type { Options } from 'metalsmith-bundled-components'"}],"quickstart":{"code":"import Metalsmith from 'metalsmith';\nimport bundledComponents from 'metalsmith-bundled-components';\nimport { fileURLToPath } from 'url';\nimport { dirname } from 'path';\n\nconst __dirname = dirname(fileURLToPath(import.meta.url));\n\nMetalsmith(__dirname)\n  .use(bundledComponents({\n    basePath: 'components/base',\n    sectionsPath: 'components/sections',\n    cssDest: 'assets/bundle.css',\n    jsDest: 'assets/bundle.js'\n  }))\n  .build((err) => {\n    if (err) throw err;\n  });","lang":"typescript","description":"Shows basic usage with custom component paths and bundled output destinations."},"warnings":[{"fix":"Pin to a specific version (e.g., 0.9.1) and review changelog before upgrading.","message":"Breaking changes may occur before v1.0.0. The API is stable but not finalized.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Use ESM import syntax for better compatibility with esbuild and future Node releases.","message":"use of require() for ESM-only packages may break in future Node versions.","severity":"deprecated","affected_versions":">=0.5.0"},{"fix":"Upgrade Node.js to 18+ or use an older version of the plugin (not recommended).","message":"Node.js 18 or higher required; Node 16 and below are not supported.","severity":"gotcha","affected_versions":">=0.9.0"},{"fix":"Update metalsmith to ^2.5.0.","message":"Metalsmith 2.5.0 or higher required; older Metalsmith versions may not work.","severity":"gotcha","affected_versions":">=0.9.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Run `npm install metalsmith-bundled-components` in your project directory.","cause":"Plugin not installed or not in node_modules.","error":"Error: Cannot find module 'metalsmith-bundled-components'"},{"fix":"Use default import: `import bundledComponents from 'metalsmith-bundled-components'`","cause":"Using named import instead of default import: `import { bundledComponents } from '...'`","error":"TypeError: bundledComponents is not a function"},{"fix":"Ensure you call bundledComponents() with parentheses: `.use(bundledComponents())`","cause":"Calling bundledComponents() returns a plugin function, but forgetting parentheses passes the module constructor.","error":"Error: metalsmith.use() requires a function or plugin instance"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}