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. /en-GB/about → en-GB).
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. /en-GB/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