sdx

SDX extends Drupal's Single Directory Components with React, Vue, and Svelte. Write components using modern JavaScript frameworks inside Drupal's SDC structure. SDX handles the build pipeline, mounting, hydration, and server integration.

Drop a single component into a Twig template with {{ sdx('my_theme:hero', {title: node.label}) }}, or go all-in and replace Twig entirely with a full framework-powered theme engine. SDX scales from one interactive widget to a complete single-page application. Your choice, not the framework's.

Why SDX

Drupal has the best content modeling, access control, and editorial workflow of any CMS. What it lacked was a modern frontend story that doesn't force you to decouple.

SDX fixes that. You get the component model, reactivity, and developer experience of modern frameworks, built natively on Drupal's plugin system, render pipeline, and cache infrastructure. No REST API to maintain. No separate frontend deployment. No lost Drupal features.

• Progressive adoption: start with one component in a Twig template, scale to a full SPA. No architecture commitment upfront.
• Framework choice: React, Vue, or Svelte via a plugin system. Any framework can be added as a contrib module.
• No decoupling tax: keep Drupal's admin UI, permissions, contextual links, cache tags, and editorial workflows. SDX components are Drupal components.
• Production SSR: clustered Node.js server with cache tag integration, circuit breaker, and streaming. Instant first paint, then hydration.
• Reactive without JavaScript: build interactive components in pure PHP with server-owned state, actions, and computed properties.

Features

Component System

• Use SDX components from any Twig template: {{ sdx('my_theme:chart', {data: values}) }}
• React 18+, Vue 3, and Svelte 5 via a plugin architecture
• Components live in Drupal's standard SDC directory structure
• Automatic library generation, no manual .libraries.yml entries
• Schema-driven props with validation from component.yml

Build Pipeline

• Vite with Hot Module Replacement (HMR) for development
• Automatic import maps, vendor bundles, and code splitting
• SCSS/Sass and PostCSS support
• TypeScript support with type generation from component schemas
• Cross-extension import aliases: @theme:aurora/, @module:my_module/

SPA Navigation (sdx_router)

• Client-side navigation with scoped partial page responses
• Prefetch on hover for instant page transitions
• Form interception with AJAX batch and modal support
• Server-declared scope (content/page/full), no client-side URL heuristics
• Automatic full reload on theme boundary crossings

Server-Side Rendering (sdx_ssr)

• Framework-agnostic: works with React, Vue, or Svelte
• Clustered Node.js server (1 worker per CPU, zero-downtime restart)
• LRU render cache with Drupal cache tag integration. Entity saves surgically invalidate cached renders
• Circuit breaker: 3 failures opens a 30s cooldown, automatic recovery
• Works with or without the theme engine. SSR for a single Twig-embedded component or a full page

Reactive Components: Livewire for Drupal (sdx_reactive)

• Build interactive components in pure PHP + Twig, zero JavaScript required
• Server-owned state with #[ReactiveState] properties
• Server-side actions with #[ReactiveAction] methods
• Computed properties with #[Computed]
• Three transport modes: props (JS framework re-render), morph (server HTML diff), realtime (shared state)

Theme Engine (sdx_drast, separate project)

• Replaces Twig entirely. All rendering produces structured JSON, not HTML strings
• Write React/Vue templates for any Drupal theme hook (block.tsx, form-element.tsx, etc.)
• Self-contained structured tokens survive Drupal's render cache
• DataProvider plugin system for typed, optimized route-level data
• Region-level partial reloads via cache tag checksums
• See SDX DRAST for details

Developer Experience

• Setup wizard guides framework, bundler, and package manager selection
• drush sdx:doctor diagnoses issues with actionable fixes
• drush sdx:build compiles all components in one command
• drush sdx:dev starts a dev server with hot reload (auto-detects DDEV)
• drush sdx:create-component scaffolds new components
• Dashboard with build status, dependency management, and component overview
• Developer toolbar showing mount state, props, and performance
• npm, Yarn, pnpm, and Bun via pluggable package manager submodules

How It Works

Option 1: Components in Twig.

Keep your existing Twig theme. Add SDX components where you need interactivity.

{{ sdx('my_theme:search', {endpoint: '/api/search', placeholder: 'Search...'}) }}

The component renders as a mount container. The JS framework hydrates it on the client. If SSR is enabled, the component is pre-rendered on the server for instant first paint.

Option 2: Full theme engine.

Replace Twig entirely. Write React/Vue/Svelte templates for every Drupal theme hook. Get SPA navigation, partial reloads, and structured data throughout. Requires the separate SDX DRAST module.

Post-Installation

After enabling the module, a setup wizard will guide you through selecting your stack:

• Framework: React, Vue, or Svelte
• Bundler: Vite (selected automatically)
• Package Manager: npm, Yarn, pnpm, or Bun (only detected options shown)
• Features: optional submodules like SSR, TypeScript, Reactive, Storybook, Router, etc.

Then run:

drush sdx:doctor    # Verify your environment
drush sdx:build    # Compile components
drush sdx:dev      # Start dev server with HMR

For DDEV users, expose the Vite port in .ddev/config.yaml:

web_extra_exposed_ports:
  name: vite 
  container_port: 5173
  http_port: 5173 
  https_port: 5174

Additional Requirements

• Drupal 10.3+ or 11
• PHP 8.3+
• Node.js 18+ for building components and running the dev server
• npm, Yarn, pnpm, or Bun for managing JavaScript dependencies
• Drush 13+ required for all CLI commands
• Private file system must be configured in settings.php ($settings['file_private_path'])

Recommended modules/libraries

• BigPipe (core) for optimal caching with reactive components
• Layout Builder (core) for placing SDX components as blocks in layouts
• SDX DRAST full structured rendering theme engine

Similar projects

Single Directory Components (SDC) is part of Drupal core. SDC provides component discovery and Twig rendering. SDX adds JavaScript framework integration, build tooling, SSR, and reactivity on top.

React Drupal provides basic React integration. SDX provides the full stack: build pipeline, SSR, SPA navigation, reactive components, and multi-framework support.

Livewire for Drupal has similar goals to sdx_reactive. SDX's reactive module is inspired by Laravel Livewire but built natively on Drupal's plugin and component systems, with multiple transport modes.

Next.js / Nuxt decoupled: SDX achieves the same frontend experience without decoupling. You keep Drupal's admin, permissions, caching, and editorial features intact.

Supporting this Module

Report bugs and feature requests in the issue queue.

Contributions welcome. The plugin architecture makes it straightforward to add new frameworks, bundlers, and features as separate submodules.

The project follows Drupal coding standards and uses PHPUnit for testing.

Community Documentation

- Coming Soon -