sdx_engine

SDX Engine replaces Drupal's Twig template engine with a structured data pipeline. Instead of producing HTML strings, the engine outputs typed JSON that React, Vue, or Svelte components consume directly. Write block.tsx instead of block.html.twig, and your framework component receives structured props instead of pre-rendered markup.

Why SDX Engine

Twig produces HTML strings. JavaScript frameworks consume data. SDX Engine bridges that gap at the Drupal render pipeline level, so your components never parse DOM or decode HTML markers.

Every rendering path (page load, SPA navigation, AJAX dialog) produces the same structured output. One pipeline, one data format, zero fallbacks.

Features

Structured Token Rendering

Self-contained tokens (__SDX{base64json}SDX__) embed component ID and props directly in the string
Tokens survive Drupal's render cache without side-channel state
Server resolves tokens into ComponentNode[] arrays before sending to the client
Client receives clean JSON. No DOM parsing, no base64 decoding, no HTML markers

Template Engine

Implements Drupal's template engine contract as a drop-in Twig replacement
Resolves .tsx, .vue, .svelte templates for any Drupal theme hook
Template auto-discovery: templates/block/block.tsx, templates/form-element/form-element.tsx
Scans themes, base themes, and enabled modules for template overrides
Set engine: sdx in your theme's .info.yml to activate

Region-Level Partial Reloads

Per-region cache tag checksums computed during rendering
On SPA navigation, only regions whose cache tags changed are re-rendered and sent
Unchanged regions preserved client-side from previous navigation

AJAX Structured Responses

Tokens in AJAX dialog responses are resolved to structured data automatically
Forms opened in modals receive the same structured output as full page loads

DataProvider Plugin System (sdx_data_provider submodule)

Route-level typed data via PHP 8 attributes (#[SdxDataProvider])
Prop priorities: Prop::IMMEDIATE, Prop::DEFERRED, Prop::LAZY for progressive loading
Persistent layouts via getLayout() keep UI state across navigations
Partial prop updates, CSRF token injection, contextual links resolution
16 DataProviders included: admin overview, appearance, block layout, config pages, content types, entity lists, field UI, help, menu editor, permissions, status report, Views editor, and more

Serialization

Form serialization with per-element-type handlers (select, textarea, boolean, file, table, text format, etc.)
Entity field extraction, render array serialization, native HTML rendering for standard Drupal elements
Breadcrumb, tabs, actions, and messages extraction via PageDataExtractor

How It Works

Render array > Drupal renderer (structured mode) > self-contained tokens > PageRenderer resolves tokens > ComponentNode[] JSON > Client renders directly

The engine hooks into Drupal's standard rendering pipeline. When a theme hook is rendered, SdxThemeEngine creates a structured token instead of calling Twig. PageRenderer collects all tokens after the page is built, resolves them into a typed component tree, serializes regions with cache tag checksums, and sends the result as JSON.

The client framework receives a complete page description: regions as component arrays, metadata (title, breadcrumb, tabs, messages), and the main content as either a DataProvider response or resolved region data.

Post-Installation

Install the SDX module first
Enable sdx_engine and optionally sdx_data_provider
Set engine: sdx in your theme's .info.yml
Create framework templates in your theme's templates/ directory
Run drush cr to rebuild the theme registry

A base theme with common Drupal templates already implemented is available at SDX React Base.

Additional Requirements

Drupal 10.3+ or 11
PHP 8.3+
SDX module
A theme with engine: sdx and framework component templates

Recommended modules/libraries

SDX (required) provides framework plugins, build pipeline, and component discovery
sdx_router (included in SDX) for SPA navigation with partial reloads
sdx_ssr (included in SDX) for server-side rendering of full pages
SDX React Base base theme with standard Drupal templates

Similar projects

Inertia.js for Laravel replaces Blade with React/Vue page components. SDX Engine takes the same approach for Drupal but goes deeper: template-level replacement (not just page-level), region-level partial reloads via cache tags, and integration with Drupal's block and render systems.

Decoupled Drupal (Next.js, Nuxt, Gatsby) requires a separate frontend application and a JSON API layer. SDX Engine keeps everything in Drupal: one deployment, one codebase, full access to admin UI, permissions, and editorial workflows.

Supporting this Module

Report bugs and feature requests in the issue queue.

Part of the SDX ecosystem. The engine is a separate module because it is optional: SDX components work in Twig templates without it.

Community Documentation

- Coming Soon -