Visual Next Builder

Visual Next Builder is a visual page builder for headless Next.js sites, run from Drupal. Site builders drag React components onto a canvas, connect them to live data from any JSON API, add behaviour without writing code, and publish. Drupal stores and delivers the pages; your Next.js site renders them with the companion npm package @visual-next-builder/next.

It gives decoupled projects the site-building experience of Layout Builder or Site Studio, while the frontend stays a normal, fast Next.js App Router application that your developers own.

Who is it for?

• Site builders and editors who want to build and change landing pages, campaign pages and dashboards on a decoupled site without waiting for a developer.
• Frontend developers who want editors to use their React components, with typed props, instead of a separate theme layer.
• Teams that deploy with configuration management: every layout, pattern, data source and design token is exportable Drupal configuration.

Features

Visual builder

• Drag-and-drop editor (GrapesJS) with layers, undo/redo, and desktop, tablet and mobile previews.
• The canvas renders the real React components your Next.js site uses, so what editors see is what visitors get.
• Per-component Settings, with values per breakpoint, and a Styles panel for per-breakpoint and :hover styles and global classes.
• Autosaved drafts, Next.js draft-mode preview, publish history with restore, and edit locking so two people cannot overwrite each other.

32 starter components

Provided by the Visual Next Builder Components submodule:

• Layout: Section, Container, Grid, Stack, Columns, Spacer, Divider, Navigation
• Content: Heading, Text, Rich text, Image, Button, Icon, Video embed
• Data: Card, Card grid, List, Table, Statistic, Chart, Empty state, Skeleton
• Interactive: Carousel, Tabs, Accordion, Pagination, Search box, Modal
• Utility: Conditional, Repeater, Form, Global pattern

Developers can register their own React components and make them available in the builder (see Custom components below).

Data binding

• Bind any component prop to data: Drupal JSON:API, any external REST/JSON endpoint, the current entity, static JSON, page state or the current item in a repeater.
• The builder suggests keys from the API's response, and supports item mapping, transforms (date, number, currency, truncate…) and fallbacks.
• Data is fetched by Drupal on the server and cached; only the bound values are sent to Next.js. API keys stay in settings.php and never reach the browser.
• Browser-side sources refetch automatically when page state changes, so a search box, pagination and a card grid work together without code.

Interactions without code

Map component events (click, change, submit…) to actions: open or close a modal, set or toggle page state, go to a URL, reload a data source, scroll to an anchor, or dispatch a browser event.

Reuse and templates

• Patterns: save any selection as a reusable section. A global pattern stays linked, so editing it once updates every page that uses it (header, footer, call to action).
• Content templates: one layout renders every node of a content type, bound to that node's fields.
• Per-item layouts (Visual Next Builder Field submodule): give individual nodes their own layout, with revisions and translations.
• Design tokens (colours, spacing, fonts, radius) compiled to CSS custom properties, with a live style guide page.
• Packages: export layouts with all their dependencies as one file and import them on another site.

Accessible, SEO-friendly output

• Clean, semantic HTML5: components render on their own elements with no wrapper div elements. Sections can be header, main, footer, aside or article elements, and menus are built as nav, ul, li and a.
• Built for WCAG 2.1 AA: keyboard support, ARIA patterns for tabs, accordion, carousel and dialogs, visible focus, and prefers-reduced-motion support.
• A Checks tab in the builder lists problems while you edit: heading order, missing alt text, vague link text, missing labels and captions, landmarks, duplicate IDs and design-token colour contrast.
• Responsive, mobile-first components with no inline styles; prop values become reusable CSS classes.

Next.js integration

• A delivery API plus resolvePage(), fetchRoute() and fetchLayout() helpers for the App Router.
• Static generation with on-demand revalidation: publishing in Drupal invalidates exactly the affected Next.js pages through cache tags.
• Route handlers for draft-mode preview, revalidation and a data proxy, ready to drop in.
• Server-rendered HTML; heavy parts such as charts are code-split.

How it works

1. In Drupal, editors build a layout in the visual builder and click Publish.
2. Drupal saves the layout as configuration, resolves server-side data, compiles scoped CSS and tells Next.js which pages to revalidate.
3. Next.js requests the page from Drupal's delivery API (/vnb/api/delivery/route?path=…) and renders the component tree with the VnbRenderer component.

Requirements

• Drupal 11.2 or later, PHP 8.3 or later.
• Core modules: File, Serialization. Optional: JSON:API (JSON:API data sources) and Field (per-item layouts).
• A Next.js 15 or 16 site with React 19, using the @visual-next-builder/next npm package.

Installation

Install as you would normally install a contributed Drupal module. See Installing modules for further information.

composer require drupal/visual_next_builder
drush en visual_next_builder vnb_components
# Optional:
drush en vnb_jsonapi vnb_field   # JSON:API data sources, per-item layouts
drush en vnb_example             # five example pages at /vnb-example

Or apply the starter recipe: drush recipe modules/contrib/visual_next_builder/recipes/vnb_starter.

In your Next.js app:

npm install @visual-next-builder/next

The module ships a complete example app in next/example and a step-by-step guide in docs/NEXTJS.md.

Getting started

1. Connect Next.js. Go to Structure » Next.js layouts » Settings and enter your Next.js site URL. In settings.php, set a shared secret used for revalidation and preview:
   

   $settings['vnb_next_secret'] = getenv('VNB_NEXT_SECRET');

   Set the same value as VNB_SECRET in Next.js, along with VNB_DRUPAL_URL.

2. Grant permissions. Edit layouts in the visual builder and Publish layouts for editors; Administer data sources and Administer layouts for site builders.
3. Add a data source (optional). Under Data sources, add a JSON:API, HTTP JSON or static source and use Test fetch to see its keys. Allowed external hosts are configured in Settings.
4. Create a layout. Under Layouts, click Add layout and choose how it is used:
   • Page: served at a path such as /pricing.
   • Content template: renders every node of a content type.
   • Template: embedded by ID wherever you need it.
5. Build the page. Click Open builder and drag components from the left panel onto the canvas. Select a component to edit it in the right panel:
   • Settings: text, links, images, sizes, and values per breakpoint.
   • Data: bind props to a data source key.
   • Interactions: add behaviour such as "on click, open modal".
   • Styles: fine-tune CSS and apply global classes.
   • Checks: fix accessibility and SEO problems before publishing.
6. Structure it well. Use a Section set to Header with a Navigation component for the site banner, one Section set to Main content, and a Footer Section. Save shared parts as global patterns.
7. Preview and publish. Changes autosave as a draft. Preview opens the page in Next.js draft mode; Publish makes it live and revalidates the affected pages.

Install the Visual Next Builder Example submodule to explore five finished pages (home, pricing, dashboard, component gallery and search) that together use every component and feature. Uninstall it to remove them.

Deploying with configuration management

Layouts, patterns, data sources, component definitions and design tokens are configuration entities, so they move between environments with drush config:export and drush deploy. Dependencies are calculated, so incomplete imports fail early. Per-item layouts are stored in content fields; drafts stay on the environment where they were made. You can lock config editing on production.

Useful commands for CI:

drush vnb:validate                 # validate every layout and pattern
drush vnb:refresh-schema --check   # fail when an API stops returning keys you bind to
drush vnb:revalidate vnb           # revalidate Next.js pages by cache tag

Custom components

Register your own React components in the Next.js app with an optional definition (label, props, slots, events), build a canvas bundle with npx vnb-canvas build, add its URL under Settings » Custom component scripts, and import the definitions with drush vnb:import-components. Editors then use your components in the builder like the built-in ones. Full guide and examples: docs/COMPONENTS.md.

Security

• No secrets in configuration: credentials live in settings.php and are referenced as {{ secret:name }}.
• External requests are limited to an allow-list of hosts, with protection against requests to private networks.
• Text is escaped by React. Rich text is filtered through a Drupal text format or sanitized; URLs and CSS are validated.
• Preview links are signed and short-lived; revalidation requires the shared secret.

Similar projects

• Drupal Canvas (Experience Builder): Drupal's new visual builder, rendering in Drupal. Visual Next Builder targets decoupled Next.js frontends.
• Next.js: decoupled preview and routing for Next.js. It does not include a visual page builder; the two approaches can be compared for your project.
• Layout Builder (core): visual layouts for Drupal-rendered themes.

Support and contributing

Report bugs and request features in the issue queue. Patches and merge requests are welcome; please include tests. The README, docs/COMPONENTS.md and docs/NEXTJS.md in the module cover every feature in detail.