When a Next.js front end on Drupal fits your project
A Next.js front end on Drupal fits when your editors already work in Drupal and you need a separate, framework-built public site that reads content from Drupal over its API. The split makes sense when the public experience needs a different front-end stack, when several sites or channels will consume the same content, or when your developers want to own rendering, routing and performance in a JavaScript framework while the editorial team keeps its existing tools. If the public site is a simple brochure site that editors can run comfortably in Drupal's own theme layer, a fully decoupled build adds a second application to build, host and secure, and that cost should be justified by a concrete need.
The Next.js for Drupal project uses Drupal's JSON:API to fetch content, menus and media for pages built in Next.js. Drupal stays the system of record for content types, fields, editorial workflows, revisions, translations and access control, so unpublished or restricted content is filtered on the Drupal side before the front end receives it. Your team still decides how much of Drupal's model is exposed to the API and how the front end maps those fields to components. Confirm with the project documentation which Drupal and Next.js versions are currently supported, and confirm how your chosen authentication approach handles content that is only visible to signed-in users.
Before committing, check three things with your own team. First, list which editorial features must still work on the public site, such as layout builder output, webforms, search or personalization, because each one needs a decoupled equivalent or stays in Drupal. Second, confirm who will run the second application: someone must own Next.js builds, hosting, cache invalidation and dependency upgrades alongside Drupal's own update routine. Third, decide whether editors need to see draft content on the public site before publishing, since that determines whether inline preview is a requirement or a nice-to-have. A partner can help scope these questions in writing before any build starts.
How Drupal and Next.js divide the work
Drupal owns the content model, editorial workflow and media library. Editors create content types, fields, revisions and moderation states in Drupal, and the front end displays whatever the API returns. Field definitions in Drupal become the schema that consumers read, so changes to them affect the front end directly.
- Content model: Content types, fields and references are defined in Drupal. Renaming or removing a field changes the API output that the front end depends on.
- Editorial workflow: Drafts, review states and publishing rules stay in Drupal. If the front end tries to enforce them, editors lose the states they see in the admin interface.
- Preview: Editors need to see unpublished content in the context of the front end. Preview access checks and routing belong to the decoupled setup, and a front end that reads only published content removes the editor's review step.
- Media and embedded content: Images and embedded entities are stored in Drupal. Rendering rules for embedded content must be agreed with the front end, or the same article looks different across channels.
Before the content model is frozen, list the fields the front end reads and confirm with editors which preview and approval steps they need.
URLs, path aliases, redirects and navigation menus are where decoupled builds most often lose SEO value and editor control. Drupal stores the aliases, redirects and menu structure. The Next.js application owns the route files, the page lookup and how an incoming path maps to a page.
- Path aliases: Editors create aliases in Drupal. The front end must resolve incoming paths against those aliases, or pages published under new URLs return not found.
- Redirects: Redirect rules created in Drupal must be applied when the front end handles requests, or old URLs stop working after an edit.
- Menus: Navigation is authored in Drupal menus. Hardcoded navigation in the front end means every menu change needs a code release.
- Language prefixes: Language paths and aliases must follow the same structure on both sides, so translated pages resolve to the correct content.
- Removed content: Unpublished and deleted nodes must return responses that match what the front end renders. Otherwise search engines keep indexing dead pages.
Test a sample of aliases, redirects, menu items and translated pages from end to end, including unpublished content, before launch.
Rendering and caching decide how fresh content is and how much load reaches Drupal. Next.js can generate pages at build time, on request or on a schedule, and it can regenerate pages after a trigger. Drupal's own caching and cache tags still matter, because they determine what the API returns and when that output changes.
- Static generation: Pre-built pages are fast to serve, but a content change needs a rebuild or regeneration path, or the site shows stale content.
- Revalidation triggers: Drupal must notify the front end when content changes. Without a trigger, updates depend on timers that editors cannot predict.
- Layered caches: Drupal's cache tags decide what the API serves. A front end cache on top of stale Drupal responses keeps old content longer than the team expects.
- Preview bypass: Preview requests must skip static output. Otherwise editors see the published version and assume their draft did not save.
- Load on Drupal: Every build or regeneration reads from Drupal. Large sites should confirm that the API and database can absorb a full rebuild without slowing editors.
For each content type, write down how fresh it must be and which event refreshes it, then test an edit to published content in staging.
Drupal and the front end have different runtime needs, and they can be hosted separately. Drupal runs on Apache, Nginx and other web servers, with MariaDB, MySQL, PostgreSQL or SQLite as the database. The Next.js front end runs as a Node.js application or as static output, and the choice depends on the rendering model. When self-hosting is required, both parts should sit inside infrastructure the organization controls.
- Drupal runtime: The supported PHP version depends on the Drupal version. Drupal 11 requires PHP 8.3 or later and Drupal 10 requires PHP 8.1 or later, so the PHP runtime can block an upgrade.
- Front end runtime: Server rendering needs a long-running Node.js process or an equivalent. Static output needs a build step and storage for the generated files. Each choice affects cost and rebuild time.
- Network paths: The front end calls Drupal's API over an internal or public route. Exposing Drupal's administrative paths to the public network to make the API reachable is a common mistake.
- Secrets: Preview and revalidation secrets live in the front end's environment. If they leak, outsiders can trigger rebuilds or view drafts.
- Multiple front ends: Each consumer on one Drupal needs its own origin, preview and revalidation settings.
Confirm with the platform team where the front end runs, how it reaches Drupal, and who holds each secret before the environments are provisioned.
Rendering and build options and when each fits
This table compares four ways a Next.js front end can produce pages from Drupal content: build-time static generation, incremental static regeneration, request-time server rendering and a per-route hybrid. Read each row as a question to answer for a route type such as article, landing page or listing, then confirm the current behavior against the Next.js for Drupal documentation for your version.
| Option | Freshness and editor expectation | What it needs from Drupal |
|---|---|---|
| Static generation at build time | Content is fixed until the next build, so editors wait for a deploy to see changes | Full content fetch during build, plus a rebuild trigger such as a webhook on publish |
| Incremental static regeneration | Pages refresh after a set revalidation window or on demand, so updates appear with a short delay | Stable entity IDs and a publish webhook that revalidates the affected paths |
| Server rendering on request | Each request reads current content, so freshness is highest but load rises with traffic | Fast, cache-aware JSON:API responses and sensible cache headers at the Drupal and proxy layers |
| Hybrid per route type | Stable pages stay static, while high-change pages use regeneration or request rendering | Cache tags and webhooks mapped per content type, with routing rules for each route pattern |
| Build load | Static builds grow with page count and can strain CI and API limits | Check API throughput and build time for your largest content set before choosing full static output |
| Preview for editors | Inline preview needs draft content and usually runs on request rendering, not cached output | Authenticated preview access and a preview secret that the front end can verify |
| Cache invalidation | Stale pages are the main risk with long revalidation windows | Confirm which Drupal events fire webhooks for menus, aliases and referenced entities |
Setup sequence for a Drupal and Next.js build
This sequence takes a Drupal content model from exposed JSON:API endpoints to a staged Next.js front end that renders published and draft content, so each layer is checked before the next one depends on it. The order matters because preview, revalidation and routing all read from what Drupal exposes.
Model content and expose JSON:API resources
The Drupal team defines content types, fields, taxonomies and menus, then decides which entity types and fields the front end may read. In a standard Drupal install, JSON:API is available without extra configuration, so the team reviews the exposed resources and their field names before any front-end code depends on them. Done means an authenticated request to a sample node's JSON:API resource returns the expected fields with stable names, and an anonymous request returns only published content the role permits.
Configure decoupled routing and menus
Set up path alias resolution and menu exposure so the front end can map URLs to content without hard-coding paths. The Drupal team installs and configures the routing and menu modules, and the front-end lead confirms how route lookups will handle redirects and unpublished paths. Done means a request for a known alias resolves to the correct entity type and ID, and a menu request returns the link tree that editors manage in Drupal.
Scaffold the Next.js project
The front-end team creates the Next.js application and adds the Next.js for Drupal project, then sets up a typed client, a catch-all route and a base layout. Decisions made here include how pages are fetched (static generation, server rendering or both) and where the Drupal client lives in the codebase. Done means the development server builds a page for one published node, and the build output lists that page without errors.
Set environment configuration per environment
Define the Drupal base URL, the Next.js site URL, the preview and revalidation secrets, and any OAuth credentials for private content, separately for development, staging and production. The platform team stores secrets in the secret manager the client already runs, not in source control, and the front-end lead confirms that the Next.js build reads the correct Drupal host for each environment. Done means a deployed staging build reads from the staging Drupal instance and rejects a request that presents a wrong or missing secret.
Wire inline preview for editors
Create a preview route in Next.js that accepts a secret and an entity reference from Drupal, validates them, then fetches the draft revision through an authenticated request. The Drupal team configures the preview link in the content editing form so editors can open it from an unpublished node. Done means an editor who opens preview for a draft node sees the unsaved title and body, while a visitor with the same URL and no secret gets a rejection.
Connect revalidation hooks
Configure Drupal to notify the Next.js site when content is saved, updated or deleted, and have the Next.js route regenerate the affected static pages. The team tests each content operation (create, edit, unpublish, delete, menu change) because a missed event leaves stale pages in place. Done means publishing a change in Drupal updates the public page within the interval the team has agreed for the site, and an unpublish returns a not-found response.
Run a staging check before launch
Run the full path on a staging copy with production-like content volume: routing, menus, images, preview, revalidation, and access for both anonymous and authenticated users. The team records failures against each earlier step and retests from the step that failed. Done means a written checklist shows every step passing on the staging environment, and the site owner signs off on the content editing workflow before production deployment is scheduled.
Running several Next.js sites from one Drupal
One Drupal content store can feed several Next.js front ends, but only if the team decides early what the sites share and what each site owns. Content types, taxonomy vocabularies, menus and image styles are usually shared, so an article or product record is modeled once and every front end reads the same fields. Routing, visual design, page composition and the list of enabled JSON:API resources are better kept per site, because a brand site and a support portal rarely need the same URLs, navigation or fields. The Next.js for Drupal project expects each front end to hold its own site configuration, so the build should treat each site as a separate consumer of a shared content model rather than as a copy of the first one.
Three decisions need confirmation during scoping because they shape the Drupal configuration and the hosting layout. The first is preview URLs: each front end needs its own preview route, secret and base URL, and the team must confirm which editor actions open which site's draft. The second is per-site API exposure: confirm whether every front end may read every content type, which fields and resources each consumer should see, and whether unpublished content or internal taxonomy should ever reach a public build. The third is editor permissions: confirm which roles can edit content that appears on several sites, who may publish to each brand, and whether a shared change needs review on every site before it goes live. Answers to these questions determine the roles, JSON:API settings and preview configuration that the implementation builds.
Plan for the operational side before the first build. Each Next.js site adds its own deployment, environment variables and revalidation settings, so a change in Drupal must reach every affected front end. Confirm how many sites will run at launch, which of them will be rebuilt on content change, and who owns each site's hosting and incident response. Ask for the design to name the content and configuration each site depends on, so a change to a shared content type is tested against every consuming site, not only the one an editor happened to notice.
Questions teams ask before building a Next.js front end on Drupal
How much does a Next.js front end on Drupal cost?
The cost comes from the scope of work, not from a license fee, because Drupal and its contributed modules are GPL-2.0-or-later and there is no paid edition of Drupal itself. The bill has four parts: the one-time build (content model, API configuration, Next.js templates, routing, images and editor preview), content migration, hosting for both systems, and recurring support. The main drivers are the number of content types and page templates, how many front ends sit on the same Drupal, the number of integrations, the volume and condition of existing content, and how much preview and workflow editors expect. Ask for an itemized written quote that separates one-time work from recurring hosting and support, lists assumptions, and states what your team provides.
How long does a Next.js front end on Drupal take to build?
No duration is reliable until the scope is written, so treat any figure given before scoping with caution. The length depends on the number of content types, page templates, components and integrations, whether content is migrated from an existing site, and how quickly stakeholders make decisions between review rounds. Your Drupal version also affects timing: Drupal 10 reaches end of life on December 9, 2026, according to the Drupal core release schedule, so a platform still on Drupal 10 may need an upgrade in the same window. Ask for a timeline tied to milestones such as content model sign-off, a working editor preview, and a staging review, and confirm which dependencies, such as identity, search and hosting accounts, sit on your side.
Can an internal team build this without a partner?
An internal team can build it alone if it already has three skills: Drupal site building and custom module work, React and Next.js development, and operations for both systems. Drupal 11 requires PHP 8.3 or later, so the team also needs a PHP and Node.js setup it can keep current. Decoupled work adds specific tasks that Drupal-only teams often have not done before, including shaping the JSON:API, authenticating editor preview, invalidating cache between Drupal and the front end, and delivering responsive images. Assess each skill against the people you have, count how many can cover the work during leave, and decide whether a fixed-scope engagement, a retainer, or a mix fills the gaps.
What does our team need to provide before the build starts?
The build moves faster when your team supplies decisions and access before development begins. Typical inputs include:
- Content owners who approve the content model and page templates
- Brand and design files, including component designs and accessibility requirements
- Access to, or an export of, existing content and media, with notes on its quality
- Hosting accounts and environments for Drupal, the front end and staging
- Identity, search and analytics integration details, with a named contact for each
- A list of editors who will test inline preview during the build
Unresolved content decisions are usually the most common cause of delay, so agree on owners and a decision deadline for each item at the start.
Who maintains the Drupal site and the Next.js front end after launch?
Two systems need two maintenance tracks, and the owner of each should be named in the written scope. Drupal core ships bugfix releases on the first Wednesday of each month and security releases on the third Wednesday, according to the Drupal core release schedule, and contributed modules release on their own schedules. The Next.js front end depends on Node.js and npm packages that also need regular updates, plus occasional framework upgrades. Define who applies Drupal updates, who upgrades the front end, who monitors security advisories, who responds to outages, and who approves changes to the content API. A support retainer can cover some or all of these tasks, and its scope should list which ones it includes.
What does hosting the Next.js front end cost?
Hosting is a recurring cost with two parts, the Drupal stack and the front end, and DeployOpen does not set hosting prices. Drupal runs on Apache, Nginx or other web servers with MariaDB, MySQL, PostgreSQL or SQLite as its database, according to the Drupal system requirements, so its cost follows the web, database, storage and cache tiers you choose. The Next.js front end can run as a Node.js server, as statically generated pages, or on a platform you already use, and each option has different compute, build and CDN costs. Ask your hosting provider for an estimate for each environment, including staging and preview, and include build minutes, bandwidth, image processing and backups.
Can one Drupal site feed several Next.js front ends?
Yes, one Drupal site can serve more than one front end through its content API. Shared content types and API configuration reduce duplicate work, but each front end still adds its own templates, routing, preview setup and deployment pipeline, so cost grows with each site. Differences in brand, navigation and language need separate design decisions. Each front end also needs its own API client and authentication setup, and access rules should be reviewed per site. Ask for a design that shows the content types and API access for each front end, and confirm how editors preview each site before the scope is fixed.
Security and operational risks in a decoupled setup
A decoupled build splits one site into two running systems: Drupal holds the content and its API, and Next.js serves the public pages. Each seam between them, from preview links to the API and the patch cycle, is a place where unpublished content or credentials can leak or go stale.
Preview authentication
Inline preview lets editors see unpublished changes through the front end, so the preview route must verify who is asking before it renders anything. Confirm that preview requests carry a short-lived, signed credential tied to one editor and one entity, and that the Next.js preview mode cannot be enabled by a plain URL. Test with a logged-out browser and with an expired token before launch.
Unpublished content through the API
Drupal's JSON:API returns whatever the requesting role is allowed to read, so an anonymous consumer can reach drafts if the entity access setup is loose. Review the anonymous role's permissions for each content type and check that unpublished revisions are not exposed through collection or filter queries. Run the same requests as an anonymous client against staging and compare the results to the published set.
Access control on JSON:API resources
Every resource and field exposed to a consumer is a decision, and JSON:API Extras and Simple OAuth can narrow what each client sees. Map each front end to its own consumer role with read-only scopes, and disable resources and fields that the page templates never use. Ask your team to document which fields carry personal data before they are published to the API.
Secrets for revalidation and preview
Revalidation webhooks and preview secrets let Drupal tell Next.js to refresh cached pages, and a leaked secret lets anyone trigger rebuilds or read drafts. Store these values in a secrets manager or the hosting platform's encrypted settings, not in the repository or in Drupal's exported configuration. Plan a rotation procedure that updates both sides in one change window.
CORS and origin settings
Browsers call the Drupal API from the front end's origin, so CORS rules decide which sites can read responses. Allow only the known front end origins, avoid a wildcard origin on any endpoint that returns drafts or authenticated data, and confirm that preview routes are not reachable from unrelated domains. Test the headers from each environment, because staging and production often use different hostnames.
Patching on the security cadence
Drupal core and contributed modules publish security releases on a fixed weekly-day schedule, and the Next.js and Node.js packages in the front end need their own updates. Assign an owner for each side, subscribe to the Drupal security advisories, and set a window to apply Drupal and Next.js fixes together so the two systems do not drift apart. Confirm how your hosting provider handles Node.js patches.
Hosting the Next.js front end next to a self-hosted Drupal
The first decision is where the Next.js front end runs, and the answer should follow from who must operate it at 2 a.m. Teams usually choose between three options that the client controls: Node.js processes on virtual machines in the same data center or cloud account as Drupal, containers scheduled on an existing Kubernetes cluster, or a platform-as-a-service the client's own team administers. Each option changes who patches the Node runtime, who rotates the front end's secrets, and who gets paged when a build fails. Whichever you pick, the front end should sit in the same network zone as Drupal or be able to reach it over a private route, so that the JSON:API endpoints are not exposed to the public internet just to be read by the build and render servers. Confirm with your platform team which Node.js version your chosen Next.js release supports before you fix the base image or runtime.
The network design matters more than the hosting brand. Place Drupal behind a reverse proxy or load balancer that is reachable from the internet, and reach the Drupal origin from the Next.js servers over a private address, a service mesh or an internal load balancer. Set the Drupal base URL and any preview or revalidation endpoints in the front end's environment configuration, and keep the shared secrets for revalidation requests in your secrets manager rather than in the repository. Restrict which hosts can call Drupal's revalidation endpoint, since a publicly callable endpoint lets anyone trigger rebuilds. Confirm with the Next.js for Drupal project documentation which endpoints and environment variables the release you choose expects.
Edge caching and incremental static regeneration interact in ways that cause stale pages if they are left unplanned. A CDN or reverse proxy in front of Next.js may cache HTML and image responses for longer than the revalidation window, so an editor's publish may appear only after both the on-demand revalidation and the CDN expiry have run. Decide which layer owns freshness for each route, and test a publish end to end: a change in Drupal, the webhook or revalidation call, the regenerated page and the purged CDN object. Ask your team to confirm the cache TTLs and the purge mechanism your CDN or proxy supports, because the purge path is usually the part that is missing. Keep Drupal's own page cache and cache tags in mind too, since stale API responses can come from Drupal before Next.js ever sees the change.
How DeployOpen scopes and delivers a Drupal and Next.js build
DeployOpen plans, implements, integrates, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, including the Drupal and Next.js pieces of a decoupled build. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
How we scope
- Written scope lists the content types, editor roles and Next.js sites the Drupal backend must serve.
- Scope records which JSON:API resources, preview paths and revalidation triggers the front end depends on.
- Hosting target for the Next.js front end and the Drupal backend is agreed before any build work starts.
How we build
- Drupal content model, JSON:API exposure and access rules are configured and tested against the agreed front end.
- Next.js for Drupal integration covers incremental static regeneration, inline preview and routing in your environment.
- Custom modules and front-end code are reviewed and tested so they survive future Drupal and Next.js upgrades.
How we hand over
- Handover documentation covers the content model, environment variables, revalidation setup and preview configuration.
- Your team receives runbooks for deploying the front end, clearing caches and rotating API credentials.
- Editors receive guidance on previews, publishing and what happens to changes after revalidation.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- Support covers Drupal core and contributed module updates, which follow the bugfix and security release schedule.
- Retainer scope, response expectations and upgrade planning are confirmed in writing with your quote.
