Stacked Middleware Bundler

1.1.1 · abandoned · verified Wed Apr 22

Stacked is a stand-alone, lightweight, and zero-dependency utility for bundling multiple middleware functions into a single, cohesive stack. Inspired by `connect`'s middleware infrastructure, it provides a `use` and `mount` API for composing HTTP middleware. As of its last published version, 1.1.1, the package has not seen updates since April 2017, indicating it is no longer actively maintained. Its key differentiator lies in its minimalist design, offering core middleware stacking functionality without the overhead or additional features found in more comprehensive frameworks. It is suitable for projects requiring a simple, independent middleware composition tool, particularly in environments compatible with its older CommonJS module format.

Common errors

```
TypeError: stacked is not a function
```
cause Attempting to use `stacked` as a function immediately after an incorrect CommonJS `require` or an ESM `import` that didn't resolve the default export correctly.

fix Ensure `const stacked = require('stacked');` is used in CommonJS environments. In ESM, if you must use it, `const { default: stacked } = await import('stacked');` might work, but it's not guaranteed without specific configuration.
```
SyntaxError: Cannot use import statement outside a module
```
cause Attempting to use `import stacked from 'stacked'` in a Node.js project that is configured as CommonJS (missing `"type": "module"` in `package.json` or not using `.mjs` file extension), as `stacked` itself is a CommonJS module, but the attempting *importer* is trying to use ESM syntax.

fix If your project is CommonJS, stick to `const stacked = require('stacked');`. If your project is ESM, either configure Node.js and TypeScript to correctly handle CommonJS interop, or use dynamic import `const { default: stacked } = await import('stacked');`.

Warnings

breaking The `stacked` package is effectively abandoned, with no updates since April 2017. This means it lacks support for modern JavaScript features (like native ESM) and will not receive security patches, bug fixes, or performance improvements. Integrating it into modern Node.js environments may lead to compatibility issues or require specific polyfills/transpilation configurations.
Fix: Consider migrating to actively maintained middleware frameworks like Express.js or Koa.js, or re-implementing the middleware stacking logic using native Node.js HTTP modules for better long-term support and security.
gotcha Being a CommonJS-only package, `stacked` does not natively support ECMAScript Modules (ESM). Directly `import stacked from 'stacked'` in an ESM project will likely fail or require Node.js `--experimental-json-modules` flag, `esModuleInterop` in TypeScript, or a bundler to resolve correctly. Its usage with modern tooling that defaults to ESM might be problematic.
Fix: In an ESM project, if `stacked` is indispensable, use `const stacked = await import('stacked');` for asynchronous loading, or ensure your build system properly transpiles CommonJS modules. For new projects, prefer ESM-compatible middleware solutions.
gotcha The `mount` method in `stacked` modifies `req.url` to be relative to the mount point, and adds `req.originalUrl` for the full, original URL. This behavior might differ from other middleware frameworks (e.g., Express.js) where `req.url` typically remains relative to the mount point but `req.baseUrl` or `req.path` might be used differently. Unawareness of this can lead to incorrect path handling.
Fix: Always use `req.originalUrl` when the full request path is needed within mounted middleware. Be mindful that `req.url` inside a mounted middleware will be the path *relative* to the mount point, not the full path.

Install

npm install stacked npm
yarn add stacked yarn
pnpm add stacked pnpm

Imports

stacked
wrong:
```
import stacked from 'stacked'
```
correct:
```
const stacked = require('stacked')
```
This package is CommonJS-only. While `import stacked from 'stacked'` might work in some ESM contexts with transpilation or specific Node.js loader configurations, the native and most reliable way is `require()`.
stacked (with named exports)
wrong:
```
import { stacked } from 'stacked'
```
correct:
```
const stacked = require('stacked')
```
The package provides a default export (the `stacked` function), not named exports. Attempting to use named imports will result in `undefined`.

Quickstart

This quickstart demonstrates how to initialize `stacked`, register multiple global middleware functions using `.use()`, and mount a specific middleware to a path using `.mount()`. It sets up a basic HTTP server to showcase how `stacked` handles incoming requests through the defined middleware chain, including path-specific logic.

const stacked = require('stacked');
const http = require('http');

/**
 * A simple logging middleware.
 */
function loggerMiddleware(req, res, next) {
  console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`);
  next();
}

/**
 * A middleware that adds a custom header.
 */
function headerMiddleware(req, res, next) {
  res.setHeader('X-Powered-By', 'Stacked');
  next();
}

/**
 * A specific middleware for a mounted path.
 */
function mountedPathMiddleware(req, res, next) {
  // req.url is stripped to the mount point here
  console.log('Mounted path URL:', req.url, 'Original URL:', req.originalUrl);
  res.end('Hello from mounted path!');
}

// Create the stacked middleware instance
const app = stacked()
  .use(loggerMiddleware)
  .use(headerMiddleware)
  .mount('/api', mountedPathMiddleware)
  .use((req, res, next) => {
    // This middleware only runs if the above .mount('/api') did not handle the request
    res.statusCode = 200;
    res.setHeader('Content-Type', 'text/plain');
    res.end('Hello from root!');
  });

// Create a Node.js HTTP server and use the stacked app as its request listener
const server = http.createServer(app);

const port = 3000;
server.listen(port, () => {
  console.log(`Server listening on http://localhost:${port}`);
  console.log('Try visiting:');
  console.log(`- http://localhost:${port}/`);
  console.log(`- http://localhost:${port}/api/data`);
});

view raw JSON →