@palamedes/next-plugin

The recommended Palamedes entry point for Next.js applications.

@palamedes/next-plugin wires Palamedes into Next.js so message macros are transformed before they leak into runtime, and .po files can be loaded as part of the application build.

Status

• Recommended for Next.js applications using App Router and Palamedes macros
• Supports .po imports and source-string-first catalog semantics
• Uses Turbopack as the verified default path on Next.js 16.2
• The shipped example proves both server-rendered i18n and localized "use server" action output
• Also supports webpack as an opt-out / fallback path
• Not a full Next.js starter or scaffolding tool

Start Here

Use the full copy-paste setup guide:

• First working translation in 5 minutes

Installation

pnpm add @palamedes/core @palamedes/react @palamedes/runtime @palamedes/next-plugin
pnpm add -D @palamedes/cli @palamedes/config

Minimal Setup

const { withPalamedes } = require("@palamedes/next-plugin")

module.exports = withPalamedes({})

import { defineConfig } from "@palamedes/config"

export default defineConfig({
  locales: ["en", "de"],
  sourceLocale: "en",
  catalogs: [
    {
      path: "src/locales/{locale}",
      include: ["src"],
    },
  ],
})

Transformed code expects getI18n() from @palamedes/runtime, so make sure the active i18n instance is available on both the client and the server before translated code executes.

Options

const { withPalamedes } = require("@palamedes/next-plugin")

module.exports = withPalamedes({}, {
  include: /\.(tsx?|jsx?)$/,
  exclude: /node_modules/,
  enablePoLoader: true,
  configPath: "./palamedes.config.ts",
  failOnMissing: false,
  failOnCompileError: false,
  runtimeModule: "@palamedes/runtime",
})

What This Package Handles

• transforms supported message macros in JavaScript and TypeScript sources
• compiles imported .po files into JavaScript modules
• keeps source-string-first catalog semantics aligned with the native core
• integrates with both webpack and Turbopack

Related Docs

• Proof, benchmarks, and current maturity
• Migration from Lingui
• Examples

License

MIT © 2026 Sebastian Software