@zanreal/nemo Documentation

The storage object is a shared data repository accessible to all functions within a single request chain. It is designed to prevent redundant data fetching (e.g., fetching a user profile multiple times) by allowing you to fetch data once and store it for subsequent middleware or functions to consume.

Key Characteristics:

• Request Scoped: Each request receives its own instance of event, meaning storage content does not persist between different requests.
• Default Implementation: By default, storage uses an in-memory implementation.
• Performance Warning: If you implement a custom adapter that queries an external database, every request to that adapter will increase the Time to First Byte (TTFB). It is highly recommended to use key-value stores like Redis or Vercel Edge Config for custom adapters.

import type { NextMiddleware } from "@zanreal/nemo";

const example: NextMiddleware = async (req, { storage }) => {
  let user = undefined;

  if (!storage.has("user")) {
    user = await fetchUser();
    storage.set("user", user);
  } else {
    user = storage.get("user");
  }

  if (!user) {
    return NextResponse.json({ message: "Unauthorized" }, { status: 401 });
  }
};

While the codemod is an AST-based transform (not a simple text search-and-replace), users should be aware of the following:

• Shadowed require: The transform matches require(...) and require.resolve(...) by shape. If you have a local function named require that is not the standard Node.js/bundler require, any call to it using the string '@rescale/nemo' will be incorrectly rewritten.
• Non-code content: Comments, docstrings, and changelogs containing @rescale/nemo are not changed. This is intentional to preserve historical context.
• Lockfiles: The tool does not modify lockfiles. You must run your package manager's install command (e.g., npm install) after running the codemod.
• Safety: If the tool encounters a file it cannot transform, it will exit with a non-zero status and stop before modifying package.json to prevent leaving your project in a broken state where sources use the new name but dependencies use the old one.

The middlewares object is a Record<string, MiddlewareFunction | MiddlewareFunction[]> where keys are route paths and values are the middleware to execute.

Matchers

Route paths use path-to-regexp syntax, similar to the Next.js matcher config. This allows for simple paths or complex route segments with parameters.

Middleware Execution

For each route, you can provide either a single MiddlewareFunction or an array of functions (MiddlewareFunction[]). If an array is provided, the functions are executed in order.

Supported Matcher Examples:

• Simple path: '/api'
• Route segments: '/team/:slug{/*path}' (matches /team/abc/def)

const middlewares = {
  // Single function
  '/api': async ({ request }: MiddlewareFunctionProps) => {
    // logic
  },

  // Chained functions executed in order
  '/api/v2': [
    async ({ request, context }: MiddlewareFunctionProps) => { /* first */ },
    async ({ request, context }: MiddlewareFunctionProps) => { /* second */ }
  ],

  // Complex route segment
  '/team/:slug{/*path}': async ({ request }) => { /* logic */ }
};

Use event.skip() to stop the execution of the remaining middlewares in the current chain section without returning a terminating response. This is useful for performance optimizations like cache hits.

• event.skip(): Skips remaining middlewares but allows the after chain to run (useful for cleanup).
• event.skip({ skipAfter: true }): Skips both the remaining middlewares AND the after chain (useful when no cleanup is required).

import type { NextMiddleware } from '@zanreal/nemo';
import { NextResponse } from 'next/server';

const cacheCheck: NextMiddleware = async (request, { storage, event }) => {
  const cacheKey = request.nextUrl.pathname;
  const cached = storage.get(cacheKey);
  
  if (cached) {
    // Skip remaining middlewares, but allow after chain to run
    event.skip();
    return NextResponse.next({
      headers: { 'x-cached': 'true' }
    });
  }
};

const earlyExit: NextMiddleware = async (request, { event }) => {
  if (request.headers.get('x-skip-all') === 'true') {
    // Skip remaining middlewares AND the after chain
    event.skip({ skipAfter: true });
    return NextResponse.next();
  }
};

NEMO allows you to organize middleware into a hierarchy that mirrors your application's route structure. This is achieved by defining a route key that contains an object with a middleware property and additional nested route keys.

• Parent Middleware: Runs for the parent route and every matching sub-route.
• Child Middleware: Runs only for the specific sub-route it is defined under.
• Execution: When a nested route is hit, both the parent and child middleware execute sequentially.

import { createNEMO } from "@zanreal/nemo";

const middleware = createNEMO({
  "/admin": {
    // Middleware for /admin route
    middleware: async (req) => {
      req.headers.set("x-section", "admin");
      return NextResponse.next();
    },

    // Nested route for /admin/users
    "/users": async (req) => {
      // This middleware only runs for /admin/users
      return NextResponse.next({
        headers: { "x-admin-users": "true" },
      });
    },
  },
});