Connect-Next Middleware Framework

Common errors

• ERR_REQUIRE_ESM: require() of ES Module ... connect-next/index.js from ... not supported.

  cause Attempting to use CommonJS `require()` to import `connect-next`, which is a native ES module.
  fix Refactor your import statement from `const connect = require('connect-next');` to `import { connect } from 'connect-next';` and ensure your project uses ES modules.

• TypeError: connect_next_1.default is not a function

  cause You are attempting to use a default import for `connect-next`, but it only exposes a named `connect` export.
  fix Change your import statement from `import connect from 'connect-next';` to `import { connect } from 'connect-next';`.

• SyntaxError: Must use import to load ES Module: ...connect-next/index.js

  cause Your Node.js environment or file is configured for CommonJS, but `connect-next` is an ES module.
  fix Ensure your `package.json` has `"type": "module"` if you intend to use ESM globally, or use `.mjs` file extensions for individual ES module files. Always use `import { connect } from 'connect-next';`.

Warnings

• breaking Connect-Next requires Node.js version `^20.19.0 || >=22.12.0`. Older Node.js versions are not supported and will result in errors upon installation or execution.
  Fix: Upgrade your Node.js environment to a compatible version.
• breaking Connect-Next is published as a native ES module (ESM) and only supports 'import' syntax. CommonJS 'require()' calls will fail.
  Fix: Ensure your project is configured for ESM (e.g., via `"type": "module"` in `package.json` or by using `.mjs` extensions) and use `import { connect } from 'connect-next';`.
• breaking When migrating from the original `connect` package, note that `connect-next` exposes a named `connect` export, not a default one. Additionally, `@types/connect` is no longer needed as types are included.
  Fix: Change `import connect from 'connect';` to `import { connect } from 'connect-next';` and remove `@types/connect` from your dependencies.
• gotcha Error-handling middleware must explicitly take four arguments: `(err, req, res, next)`. Middleware with fewer arguments are treated as regular middleware and will not catch errors passed to `next()`.
  Fix: Define error middleware with the signature `(err: Error, req: IncomingMessage, res: ServerResponse, next: NextFunction) => void;`.

Install

• npm install connect-next npm
• yarn add connect-next yarn
• pnpm add connect-next pnpm

Imports

• connect
  wrong:

  import connect from 'connect-next';

  correct:

  import { connect } from 'connect-next';

  Since v4, connect-next is a native ES module (ESM) and exposes a named 'connect' export, unlike the original 'connect' which used a default export.
• connect (CommonJS)
  wrong:

  const connect = require('connect-next');

  correct:

  N/A

  connect-next is an ES module only. Direct CommonJS 'require()' is not supported; use dynamic import() if absolutely necessary within CJS contexts, or convert your project to ESM.
• Middleware types

  import type { IncomingMessage, ServerResponse } from 'node:http';
  import type { NextFunction } from 'connect-next';

  While 'NextFunction' is not directly exported, 'connect-next' ships with its own TypeScript types. Middleware typically takes (req: IncomingMessage, res: ServerResponse, next: NextFunction) => void. 'NextFunction' represents (err?: any) => void.

Quickstart

Demonstrates creating a basic Connect-Next application, adding common middleware for compression, session management, and body parsing, then listening for HTTP requests.

import { connect } from 'connect-next';
import { createServer } from 'node:http';
import compression from 'compression';
import cookieSession from 'cookie-session';
import bodyParser from 'body-parser';

const app = connect();

// gzip/deflate outgoing responses
app.use(compression());

// store session state in browser cookie
app.use(
  cookieSession({
    keys: ['secret1', 'secret2'],
  }),
);

// parse urlencoded request bodies into req.body
app.use(bodyParser.urlencoded({ extended: false }));

// respond to all requests
app.use((req, res) => {
  res.end('Hello from Connect!\n');
});

// create an HTTP server and listen on port 3000
createServer(app).listen(3000);