Docs Developer Site
Developer Docs Next.XP next Next.js starter

Next.js starter

Contents

starter-nextjs is the recommended project template for an Enonic-backed Next.js application. It connects the Next.js adapter to Next.js App Router routes, localization, Content Studio editing, and revalidation.

This page documents the starter for Next.XP 6. Individual dependency patch versions may change as the starter is maintained.

The starter is intentionally small. Copy it when beginning a project, or use it as a reference when integrating Next.XP into an existing Next.js application.

Front-end dependencies

The starter includes these libraries. The adapter brings in @enonic/react-components transitively; the other packages are direct dependencies of the starter.

Software component Version Role in the starter

Next.js

16.4

Framework providing routing, rendering, and caching.

React and React DOM

19

Libraries for rendering the front-end UI.

@enonic/nextjs-adapter

6

Fetches Enonic content and renders it through registered React views.

@enonic/react-components

Selected by the adapter

Provides rich-text rendering through the adapter. See Adapter supporting libraries for details.

@enonic/page-editor

2

Browser library connecting the rendered page to Content Studio for visual editing and component refreshes.

The front-end requires Node.js 24.15.0 or later and npm 10.9.2 or later. The React Components and Page Editor libraries version independently of Next.XP.

See the Next.XP overview for the required Enonic applications and platform versions.

Usage

Create a new project from enonic/starter-nextjs without copying its Git history:

npx degit enonic/starter-nextjs my-nextjs-site
cd my-nextjs-site
npm install

Configure the Enonic API, application name, project mappings, and shared preview secret as described in Starter configuration, then start the development server:

npm run dev
Follow the Next.XP tutorial for a guided implementation that builds a complete site from the starter.

Project structure

The starter follows the Next.js App Router layout. Next.XP-specific files are concentrated in the catch-all route, component registry, locale proxy, phrase directory, and API routes.

Application routes

Path Responsibility

src/app/[locale]/[[…​contentPath]]/page.tsx

Calls fetchContent() to fetch XP content, validates the result, renders MainView, supplies metadata, and optionally generates static paths.

src/app/[locale]/[[…​contentPath]]/layout.tsx

Handles complete-page and single-component responses and preserves editor HTML during hydration.

src/app/[locale]/layout.tsx

Loads server-side phrases and establishes the locale-level document layout.

src/app/[locale]/not-found.tsx

Locale-aware missing-content UI.

src/app/[locale]/error.tsx

Locale-aware runtime error UI.

Integration routes

Path Responsibility

src/app/api/preview/route.ts

Validates the xp parameter, enables Draft Mode, and redirects Content Studio to the requested path.

src/app/api/mappings/route.ts

Returns the rules the Next.XP app uses to resolve content items to Next.js URLs.

src/app/api/revalidate/route.ts

Accepts secured publication notifications and calls revalidatePath().

src/proxy.ts

Resolves locale mappings, rewrites paths without a locale segment, and enables Draft Mode for Content Studio requests.

Components and data

src/components/_mappings.ts imports the adapter’s base mappings, registers the shared query, and maps application descriptors. Keep queries close to their consuming views; shared data belongs under src/components/queries/.

Static front-end dictionaries for server and client phrase localization live in src/phrases/<locale>.json. The @phrases alias is configured in next.config.js for webpack and Turbopack.

src/components/views/PageEditorScript.tsx initializes @enonic/page-editor in the browser and handles component refresh requests. See Editing and preview for the interaction with Content Studio.

The starter also supplies development views for unmapped content. See Starter configuration for bundler aliases and rendering choices.

Public files and proxy matching

The locale proxy excludes Next.js internals, API routes, and known public assets. When adding a top-level folder under public/, add it to the matcher exclusion so asset requests are not interpreted as content routes.

What to customize

Replace the example application name, project mappings, common query, phrases, and views. Register each content type and page component used by the site. Preserve the integration routes and editing wrappers unless the replacement implements the same contracts.

The starter is not the tutorial’s completed example. The finished reference implementation lives in demo-nextjs.

See Starter configuration for environment variables, the shared secret, component mappings, and rendering choices.

Contents

Contents