Next.js integration

@systhemaui/next provides the Systhema components for Next.js. It re-exports framework-independent React components and supplies twins that use next/image, next/link or pathname-aware listeners. Import from this package in Next.js applications; a few twin props intentionally differ from React.

Design philosophyLink to this section

• When a component benefits from Next-specific behavior (such as Image, Link, Button, Card, Chip, Header, Footer), @systhemaui/next ships a custom Next implementation.
• When a component doesn't need Next-specific behavior (such as Section, Paragraph, Heading, Form*, SearchField, Separator, Stack, Columns, Accordion), @systhemaui/next re-exports it from @systhemaui/react.

Import components from @systhemaui/next in Next.js apps. Either you get the Next-aware version, or you get the React component verbatim.

import { Image, Link, Separator } from '@systhemaui/next'

InstallationLink to this section

pnpm add @systhemaui/core @systhemaui/next

You don't need to install @systhemaui/react separately. @systhemaui/next depends on it transitively. Install it explicitly when importing React-specific implementations directly.

Opt-in locale support bundles next-intl. See Frontend locales. Never install next-intl yourself; a second copy conflicts with the bundled one.

See Manual installation for the full setup including registry access and Tailwind wiring.

What this section coversLink to this section

This section covers only the Next-specific parts of @systhemaui/next: the provider, the gateway, the public origin helper and frontend locales. Props, subcomponents and examples of every component are on the component pages, each with a "Next.js" section where the Next twin differs.

Next.js twinsLink to this section

The package keeps hand-maintained twins where Next.js changes rendering or navigation. With the current source:

LinkHelper wraps next/link and also handles same-page hashes; see LinkHelper. Image behavior and sizing remain subject to the component's props; see Image.

Intentional API differencesLink to this section

The twin drift test compares exported names, workspace-declared props and literal vocabularies against React. Its ALLOWED list records these intentional differences:

• Next listeners take no resetKey prop and do not export the React listener props types. They restart through usePathname().
• Next adds CardLinkProps and Card.link, an alias of Card.a. Both link variants render through next/link.
• Next exports NextLinkChipProps for Chip.a.
• Next PostCard and HighlightCard render their own images, so they omit React's renderImage prop. They add linked; setting it to false disables their link wrapper. PostsList supplies Next image and link defaults while honoring caller render overrides.
• React exports the internal helpers resolveSamePageHash, withTagProxy, DisableAnimationsContext and useAnimationClasses for twin implementations; the Next root does not re-export them.

Use the component pages for complete props. Next and React share the token-derived variant vocabulary, but their inherited image and link library props can differ.

Best practicesLink to this section

• Import components from @systhemaui/next in Next.js apps, including re-exported components.
• Put SysthemaProvider in the root layout to mount the config server and Next listeners.
• Use Card.link for a clickable card, Button.a for a button-style link and Icon.a for a linked icon.
• Supply appropriate image dimensions and sizes. Image disables optimization for GIF and SVG; use unoptimized when another format needs to bypass the optimizer.
• Import runtime values from @systhemaui/core/client in client-reachable code. The core root reaches token JSON that cannot be tree-shaken. See Client and server code.
• Set adminRouting: false in the gateway for a Next-only application.

RelatedLink to this section

• Browser support (including how withSysthema() drops Next's legacy polyfills)
• Next.js template
• Payload template