Common Middleware

Common errors

• SyntaxError: Cannot use import statement outside a module

  cause Attempting to use `import` syntax for `common-middleware` in a CommonJS-only Node.js environment or without proper transpilation.
  fix Change `import middleware from 'common-middleware';` to `const middleware = require('common-middleware');`.

• TypeError: app.use is not a function

  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.
  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();`).

Warnings

• gotcha 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.
  Fix: Use `common-middleware` exclusively with applications built on `base-methods` or its derivatives like `assemble-core`.
• gotcha 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.
  Fix: Always use `const middleware = require('common-middleware');` for consuming this package.
• breaking 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.
  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.

Install

• npm install common-middleware npm
• yarn add common-middleware yarn
• pnpm add common-middleware pnpm

Imports

• middleware
  wrong:

  import middleware from 'common-middleware';

  correct:

  const middleware = require('common-middleware');

  This package is primarily a CommonJS module. Direct ESM `import` syntax is not supported without a transpilation step or a CommonJS wrapper.

Quickstart

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.

const middleware = require('common-middleware');
const assemble = require('assemble-core'); // Install via: npm install assemble-core

// Create your application instance (e.g., from assemble-core, verb, generate)
const app = assemble();

// Register the common middleware suite with the application.
// This attaches the various hooks (onLoad, preWrite, etc.) to the app's lifecycle.
app.use(middleware());

console.log('common-middleware registered with the application.');

// Now, as files are processed by 'app' (e.g., through app.src(), app.render(), app.dest()),
// this middleware will automatically intervene to perform tasks like:
// - Parsing YAML/JSON front-matter from files into `file.data`
// - Escaping or unescaping template delimiters (e.g., `<%= foo %>`)
// - Handling JSON parsing and stringifying for files matching `options.jsonRegex`

// Example of how options can be passed (optional):
// app.use(middleware({ jsonRegex: /\.(json|data)$/, extRegex: /\.(md|html|hbs)$/ }));