intlayerProxy

intlayerProxy is a Vite plugin that registers locale-routing middleware for every environment: dev server, preview server, and production SSR (Nitro / TanStack Start).

Since Intlayer v9 intlayerProxy is automatically included inside the main intlayer() plugin and enabled by default via routing.enableProxy: true. You only need to register it separately if you need lower-level control or are using it outside the standard intlayer() setup.

Usage

As part of intlayer() (recommended, v9+)

Pass proxy options to the main plugin instead of registering intlayerProxy separately:

// vite.config.ts
import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

export default defineConfig({
  plugins: [
    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
  ],
});

Standalone (when needed)

// vite.config.ts
import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

export default defineConfig({
  plugins: [intlayer()],
});

Options

import type { IntlayerProxyPluginOptions } from "vite-intlayer";

All options are optional and passed as a single object:

Example

intlayerProxy({
  ignore: (req) => req.url?.startsWith("/api"),
  configOptions: { configFile: "./config/intlayer.config.ts" },
});

createIntlayerProxyHandler

createIntlayerProxyHandler creates a standalone, framework-agnostic Node.js (req, res, next) middleware that contains all the locale-routing logic. It is useful in environments where the Vite plugin API is unavailable (e.g. a plain Node.js server or a custom Nitro module).

import { createIntlayerProxyHandler } from "vite-intlayer";

const handler = createIntlayerProxyHandler({
  ignore: (req) => req.url?.startsWith("/api"),
  configOptions: { configFile: "./config/intlayer.config.ts" },
});

// Express / Connect
app.use(handler);

Production SSR (TanStack Start / Nitro via h3)

// server/middleware/intlayerProxy.ts
import { fromNodeMiddleware } from "h3";
import { createIntlayerProxyHandler } from "vite-intlayer";

export default fromNodeMiddleware(
  createIntlayerProxyHandler({
    ignore: (req) => req.url?.startsWith("/api"),
  })
);

Routing behaviour

The middleware mirrors the routing logic from next-intlayer middleware and supports all Intlayer routing modes.

Routing modes

Detection priority

1. URL path prefix (e.g. /fr/about → fr).
2. Cookie / localStorage value (intlayer-locale).
3. Accept-Language header.
4. defaultLocale from config.

Automatic bypass

The middleware always passes these requests straight through without locale handling:

• Requests matching the ignore predicate.
• /node_modules/**
• /@** – Vite internals (@vite/, @fs/, @id/, etc.).
• /_** – server internals (__vite_ping, __manifest, etc.).
• Requests whose path ends with a file extension (static assets). If a locale prefix is present on a static asset path (e.g. /fr/logo.png), it is stripped so the file can be served correctly.

Domain routing

When routing.domains is configured in your Intlayer config, the middleware handles cross-domain locale routing:

• A request for /zh/about on intlayer.org is redirected to https://intlayer.zh/about when domains.zh = "intlayer.zh".
• A request to intlayer.zh/about is rewritten internally to /zh/about so the [locale] route parameter is populated.

Redirect loop protection

The middleware tracks redirect counts per originalUrl → newUrl pair within a 2-second sliding window. More than 10 redirects within that window returns a 500 response with a descriptive error instead of looping forever.

Nitro / production SSR (automatic injection, v9+)

When intlayerProxy is used as a Vite plugin, it carries a .nitro property. The nitro/vite build plugin reads this property and pushes it into nitroConfig.modules, so intlayerNitroHandler is registered as a Nitro server middleware automatically — no manual configuration is needed for production SSR.

The Nitro handler uses h3 v2's Web Fetch API event model (not fromNodeMiddleware) so it is compatible with all Nitro presets: Node, Bun, Deno, edge runtimes.

Deprecated aliases