{"id":17426,"library":"common-middleware","title":"Common Middleware","description":"common-middleware is a JavaScript utility library that provides a collection of reusable middleware functions designed for applications built upon the `base-methods` framework, particularly for projects like Assemble, Verb, Generate, and Update. It currently stands at version 1.0.0, last updated over two years ago, indicating a maintenance phase rather than active development. The library focuses on processing file objects in a pipeline, offering functionalities such as front-matter parsing, escaping and unescaping template delimiters, and managing JSON data on load and pre-write. Its key differentiator is its integration within the `base` and `assemble` ecosystem, providing standardized pre-processing capabilities for file-based templating and content management workflows common in static site generators or documentation builders. It is specifically designed for Node.js environments, historically supporting versions `0.10.0` and above, and primarily uses CommonJS modules.","status":"maintenance","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/jonschlinkert/common-middleware","tags":["javascript","common","front","front-matter","matter","middleware","parse","templates","yaml"],"install":[{"cmd":"npm install common-middleware","lang":"bash","label":"npm"},{"cmd":"yarn add common-middleware","lang":"bash","label":"yarn"},{"cmd":"pnpm add common-middleware","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Functionally required for quickstart and typical usage, as `common-middleware` is designed to be registered with `assemble-core` or similar `base-methods` applications.","package":"assemble-core","optional":false}],"imports":[{"note":"This package is primarily a CommonJS module. Direct ESM `import` syntax is not supported without a transpilation step or a CommonJS wrapper.","wrong":"import middleware from 'common-middleware';","symbol":"middleware","correct":"const middleware = require('common-middleware');"}],"quickstart":{"code":"const middleware = require('common-middleware');\nconst assemble = require('assemble-core'); // Install via: npm install assemble-core\n\n// Create your application instance (e.g., from assemble-core, verb, generate)\nconst app = assemble();\n\n// Register the common middleware suite with the application.\n// This attaches the various hooks (onLoad, preWrite, etc.) to the app's lifecycle.\napp.use(middleware());\n\nconsole.log('common-middleware registered with the application.');\n\n// Now, as files are processed by 'app' (e.g., through app.src(), app.render(), app.dest()),\n// this middleware will automatically intervene to perform tasks like:\n// - Parsing YAML/JSON front-matter from files into `file.data`\n// - Escaping or unescaping template delimiters (e.g., `<%= foo %>`)\n// - Handling JSON parsing and stringifying for files matching `options.jsonRegex`\n\n// Example of how options can be passed (optional):\n// app.use(middleware({ jsonRegex: /\\.(json|data)$/, extRegex: /\\.(md|html|hbs)$/ }));","lang":"javascript","description":"This quickstart demonstrates how to initialize `common-middleware` and register its suite of file processing functions with an `assemble-core` application. Once registered, it automatically handles tasks like front-matter parsing, template escaping, and JSON file processing within the application's file pipeline."},"warnings":[{"fix":"Use `common-middleware` exclusively with applications built on `base-methods` or its derivatives like `assemble-core`.","message":"This library is specifically designed for the `base-methods` ecosystem (e.g., Assemble, Verb, Generate). It may not function as expected or integrate easily with other Node.js web frameworks (like Express or Koa) without significant adaptation or manual hook integration.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always use `const middleware = require('common-middleware');` for consuming this package.","message":"The package is exclusively a CommonJS module. Attempting to use ESM `import` syntax will result in a `SyntaxError` in Node.js environments configured for CommonJS, or incorrect behavior in pure ESM projects unless handled by a build tool or wrapper.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Thoroughly test `common-middleware` in your specific target Node.js environment. For critical applications, consider forking the repository for active maintenance or exploring more actively maintained alternatives if available within your ecosystem.","message":"The `common-middleware` package is in maintenance mode and has not been updated in over two years (last updated 2024 as of current date). While generally stable, compatibility with newer Node.js versions (e.g., Node.js 16, 18, 20+) or modern JavaScript features is not guaranteed, and runtime environment changes might introduce unforeseen issues without official patches.","severity":"breaking","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Change `import middleware from 'common-middleware';` to `const middleware = require('common-middleware');`.","cause":"Attempting to use `import` syntax for `common-middleware` in a CommonJS-only Node.js environment or without proper transpilation.","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Ensure that the `app` object you are calling `app.use()` on is an instance of `assemble-core` or a compatible `base-methods` application (e.g., `const app = assemble();`).","cause":"The `common-middleware` package expects to be registered with an application instance that provides an `app.use()` method, typically from the `base-methods` family (e.g., `assemble-core`). This error occurs if `app` is a plain object or an incompatible framework.","error":"TypeError: app.use is not a function"}],"ecosystem":"npm","meta_description":null}