JSX Theme Engine: Roadmap to Stable for Drupal 11 and 12

Summary

The JSX Theme Engine can reach a stable 2.0.0 for Drupal 11.3+ and 12 in five phases over about 9–12 months. Most of that time goes to one dependency: a core change that lets a non-Twig engine render module templates and SDC components.

Where the project stands (September 2026):

• Dormant since April 2024. 41 commits, a single 1.0.x-dev branch, no tagged release, no security advisory coverage, 47 issues (about 22 still open). The project is marked experimental and minimally maintained. Maintainers are bnjmnm, effulgentsia and hooroomoo, supported by Acquia.
• Broken on 11.3+. It ships a legacy jsx.engine file, and 11.3 replaced that contract with tagged services. Canvas's sibling engine hit exactly this failure: "Service 'semi_coupled' not found" (canvas#3556101).
• Its best ideas are already in Canvas. Canvas's semi-coupled theme engine "lifted relevant parts" of JSX (#3446434: Document "Semi-Coupled Theme Engine" and "Redux-integrated field widgets" components). Canvas is now removing that engine in favor of custom HTML tags inside Twig (canvas#3555062), which leaves JSX as the only effort aimed at a full non-Twig engine.

What stable means for this roadmap: a tagged service implementing ThemeEngineInterface; SDC components authored in JSX; server-rendered HTML with client hydration (no blank page before JS runs); full coverage of Drupal core's templates; opt-in to the security advisory policy; and tested support for Drupal 11.3, 11.4, 11.5 and 12.x.

The critical path is #3525011: Allow complete replacement of the default theme engine (twig) in Drupal core, "Allow complete replacement of the default theme engine (twig)". Until it lands, core forces Twig for module templates and SDC. The roadmap treats it as a hard blocker for SDC-to-JSX, drives it from inside core, and builds everything else in parallel.

Review of the current JSX project

The existing design is a sound proof of concept: Drupal emits custom elements with serialized props, and the browser maps them onto JSX components. It is not yet a theme engine in the production sense, because nothing renders without JavaScript.

Review basis: the Drupal.org project page, the 47-issue queue and discussion on merged merge requests. File-level details should be confirmed against the 1.0.x branch before estimates are finalized.

How it works today

Render array -> ThemeManager -> jsx.engine (legacy .engine file) -> <drupal-*> custom elements + serialized props -> Browser: hyperscriptify() -> React / Preact / Solid components mount

1. jsx.engine swaps each template for a custom element named after the hook, e.g. form-element becomes <drupal-form-element>, carrying the template variables as props (#3397049: Integrate with AJAX).
2. Each component's prop types are declared with PropTypes. *.template-info.json files generated from them tell the engine which props a component expects (#3396749: Automate the generation of *.template-info.json files from the components' PropTypes declarations, #3396706: Add a way to discover possible props).
3. In the browser, index-*.js entry points call hyperscriptify(), which walks the DOM and builds a component tree for the chosen framework.
4. Preprocess logic moved from PHP into JS (#3392970: Move preprocess functions to JS code), and CSS moved from attach_library() to CSS-in-JS (#3393003: Move CSS attachment from {{ attach_library() }} to a CSS-in-JS solution).
5. The Umami JSX demo theme ships React, Preact and Solid builds, plus a React debug tool showing template suggestions.

Strengths to keep

• Custom-element boundary. It lets JSX and Twig output coexist on one page, so the engine can be adopted one template at a time.
• Framework-agnostic mapping. Hyperscriptify targets React, Preact and Solid alike.
• Real Drupal UIs exercised. Layout Builder, AJAX, BigPipe and language switchers were all tested against it, and AJAX responses are re-hyperscriptified (#3397049: Integrate with AJAX).
• Props metadata anticipates SDC's *.component.yml schemas.
• Lineage. Its approach was proven again in Canvas's semi-coupled engine.

Findings

The existing npm toolkit (drupal-jsx org)

The rendering approach above is not just a design on paper: it already exists as eight small, single-purpose packages under the drupal-jsx GitHub organization, all type: module, MIT-licensed, last touched December 2023 — the same dormancy window as the main project. Phase 1 should revive and publish these rather than rebuild them from scratch.

What this changes in the plan: @drupal-jsx/runtime (target architecture, below) is a revival of hyperscriptify + drupal-utils + drupal-utils-react, generalized to Preact as the default per the framework-scope decision, and @drupal-jsx/vite is a revival of vite-plugin-drupal + drupal-utils-dev. serialize-prop-types maps directly onto @drupal-jsx/types's job, but should be re-pointed at SDC's *.component.yml schemas instead of hand-authored PropTypes, per the SDC bridge in Phase 2. All of it is currently pinned to React 18 and Vite 5 peer dependencies, which need bumping as part of the 11.3+/12 compatibility pass.

Gap analysis: Drupal 11.3+ and Drupal 12

The project was written against Drupal 10's theme layer, and nearly every integration point it touches has moved since. Target core_version_requirement: ^11.3 || ^12 and drop Drupal 10, which reaches end of life on December 9, 2026.

Release timeline that sets the support matrix

Source: core release schedule.

What must change

Carryover from the 2023 design that no longer fits

• Semi-coupled mapping JSON. Canvas is removing the same pattern because "few understand" it (canvas#3555062). Replace hand-maintained template-info JSON with SDC's *.component.yml prop schemas plus generated TypeScript types.
• CSS-in-JS. Return to Drupal libraries (or SDC's automatic per-component CSS/JS) so aggregation, libraries-override and asset bubbling work.
• Framework trio. Supporting React, Preact and Solid triples the test matrix. Standardize on Preact with preact/compat to align with Canvas, and treat React and Solid as community adapters.

The core blocker: Twig as default infrastructure

#3525011: Allow complete replacement of the default theme engine (twig) in Drupal core "Allow complete replacement of the default theme engine (twig) in Drupal core" is the gate for SDC-to-JSX, and it needs a broader scope and a reroll before it can land. It was opened May 16, 2025 by d34dman, is still Active, and its summary predates 11.3: it cites twig_render_template, which no longer exists.

Three couplings, three different fixes

Reading core main (12.0-dev, September 2026) shows that "Twig as default" is really three separate couplings. Only one of them is solvable in contrib today.

inline_template itself, and Views rewrites, are Twig-language strings by definition. They should stay Twig and are not blockers.

Proposed core change set

File these as child issues of #3525011: Allow complete replacement of the default theme engine (twig) in Drupal core so each can land in its own minor release:

1. Reroll #3525011: Allow complete replacement of the default theme engine (twig) in Drupal core on the 11.3 service architecture. Replace the hard-coded 'twig' with an engine-declared fallback. Add an optional exclusive flag that makes the active engine own module templates, throwing when a template is missing.
2. New issue: engine-agnostic SDC template discovery. ComponentPluginManager asks the tagged engines which extensions they own (.twig, .jsx, .tsx) and stores engine on the component definition.
3. New issue: ComponentRenderingEngineInterface. An optional interface, e.g. renderComponent(ComponentPlugin $component, array $props, array $slots): array|MarkupInterface. ComponentElement delegates to the owning engine; Twig keeps today's inline_template path as its implementation.
4. New issue: cross-engine composition. Twig's include('provider:card') must render a JSX-owned component (via a render array placeholder), and JSX must be able to render Twig-owned components as slots. This keeps mixed sites working during migration.
5. Test engine upgrade. Extend core's nyan_cat test engine to own an SDC component and run in exclusive mode, so the new APIs stay covered in core CI.

Timing

New APIs land only in minor releases. 12.0 is in beta with release candidate 1 due the week of November 9, 2026, so the earliest realistic core target is a Drupal 12.x minor in 2027, with a backport to 11.x if the change is API-additive. The roadmap therefore ships a contrib-side SDC bridge first (Phase 2) and retires it once core lands (Phase 4).

Target architecture

Stable JSX renders HTML on the server and hydrates in the browser only where a component is interactive. SDC is the unit of authoring, and Drupal's render pipeline (caching, attachments, BigPipe) stays in charge. ThemeManager -> JsxThemeEngine::renderTemplate() -> PropNormalizer (Attribute, Markup, Url) -> Slots: nested render arrays via Renderer -> SSR renderer (Node sidecar or client-only) -> HTML + island markers -> Render cache / BigPipe -> Browser: hydrate interactive islands only

Components of the system

Rendering pipeline decisions

1. Props are normalized in PHP, not JS. Attribute becomes a plain object, MarkupInterface a pre-escaped HTML string, TranslatableMarkup a string, Url an href. This resolves #3398446: Add type coercion logic to jsx.engine so that themes can declare prop types based on their needs, not on knowledge of Drupal internals and replaces JS-side preprocess.
2. Render arrays become slots. Nested render arrays render through RendererInterface first, so #cache and #attached bubble exactly as with Twig. They arrive in JSX as a <Slot html={...} />.
3. SSR renderer is pluggable.
   • Node sidecar (default for production): a long-lived Node/Bun process on a local socket renders the component; it is called only on render-cache misses.
   • Client-only (development fallback): today's custom-element behavior, for hosts without a sidecar.
   • Compile-to-PHP (research track): compile a static JSX subset to PHP at build time, removing the runtime dependency entirely.
4. Islands, not whole-page hydration. Only components that export hydrate = true (or use a 'use client' directive) ship JS and serialized props. Server-only components never send variables to the browser, which closes the data-exposure finding.
5. Escaping. JSX autoescapes text; the only raw-HTML path is <Slot>, which accepts MarkupInterface output only.
6. Assets through Drupal libraries. The Vite plugin writes per-component libraries, so aggregation, libraries-override and SDC's automatic CSS/JS keep working.

SDC in JSX

themes/custom/mytheme/components/card/ card.component.yml # props + slots schema (unchanged SDC format) card.tsx # default export: the component card.css # auto-attached, as with Twig SDC card.stories.tsx # optional import type { CardProps } from './card.types'; // generated from card.component.yml export default function Card({ heading, image, children }: CardProps) { return ( <article className="card"> {image} <h3>{heading}</h3> {children /* SDC slot */} </article> ); }

With core's engine-aware discovery (blocker items 2–3), card.tsx is discovered like card.twig. Placing it with #type => 'component', Layout Builder or Canvas then works unchanged. Until then, the jsx module's bridge registers these components under its own element type.

Roadmap

The roadmap has five phases that end in a 2.0.0 stable release, targeted for mid-2027. The core track (Phase C) runs in parallel from day one because it gates the stable release.

The new work goes on a fresh 2.0.x branch. 1.0.x never had a release, so users see a clean line between the 2023 experiment and the supported engine.

Phase 0 — Collaboration and triage (October 2026)

• Share this roadmap with bnjmnm, effulgentsia and hooroomoo as a proposal, and refine it with their input on the original design goals.
• Offer to join as co-maintainer alongside the current team, and agree together on review and release responsibilities, especially for core-facing changes.
• Post a [META] Roadmap to stable issue so the wider community can comment and contribute.
• Review the queue with the maintainers: propose closing issues the new architecture supersedes (framework demos #3399991: Add a demo Fresh app and subtheme and #3396970: Integrate with Tome, JSON template-info work, CSS-in-JS follow-ups).
• Carry forward and retitle the issues that still apply: AJAX (#3432283: Layout Builder "Add Section" does not have submit button), Layout Builder (#3432278: Layout Builder "Remove Section" does not work in Umami JSX, #3432903: In Layout Builder the breadcrumbs are not showing up., #3432277: Get contextual links working in Layout Builder + Umami JSX), tests (#3432275: [META] Tests), npm publishing (#3427734: Publish helper libraries to npm or jsr), TypeScript (#3396747: Add TypeScript declarations to the JSX component props).
• With the maintainers' agreement, update the project status from experimental to "Under active development" and maintenance status to "Actively maintained".

Phase 1 — Compatibility (October – December 2026)

• Replace jsx.engine with JsxThemeEngine implements ThemeEngineInterface, tagged engine_name: jsx.
• Move engine-level preprocess into #[Hook] classes; convert .module/.theme procedural hooks to OOP.
• Set core_version_requirement: ^11.3 || ^12 and drop Drupal 10.
• Adopt the Drupal Association GitLab CI template; test on 11.3, 11.4, 11.5 and 12.0 (beta, then RC, then release), with next major runs.
• Finish the Vite migration (#3439774: Refactor jsx_umami to use Vite ) by reviving vite-plugin-drupal; standardize on Preact with preact/compat.
• Audit the eight dormant drupal-jsx npm packages (hyperscriptify, propsify, serialize-prop-types, drupal-utils, drupal-utils-react, drupal-utils-dev, vite-plugin-drupal, starter-react): bump their React 18 / Vite 5 peer dependencies, decide on a monorepo, and publish the revived @drupal-jsx/runtime and @drupal-jsx/vite to npm (#3427734: Publish helper libraries to npm or jsr).
• Rebuild jsx_umami on the new engine as the smoke test.

Phase 2 — SSR, islands and the SDC bridge (January – March 2027)

• Build the PHP prop normalizer and slot rendering through RendererInterface.
• Build the Node sidecar SSR renderer and a DDEV add-on, plus a client-only fallback mode.
• Add island hydration with opt-in hydrate, and stop serializing props for server-only components.
• Rework AJAX to one root per island; fix replaceWith and off-canvas submit buttons.
• Ship the contrib SDC bridge: discover *.tsx beside *.component.yml, validate props against the schema, render via the engine.
• Build @drupal-jsx/types to generate TypeScript prop types from component.yml.
• Emit server-side theme debug comments matching Twig's format.

Phase 3 — Full template coverage (March – June 2027)

Core main contains 263 non-test *.html.twig templates across its modules; system alone has 72. Admin-only templates (Views UI, Field UI, Help, Navigation) can stay on the admin theme's Twig, which leaves roughly half for jsx_base.

• Generate a coverage report: every theme hook versus the templates jsx_base provides.
• Port front-end templates in priority order: page/region/block, node/field/entity, forms and form elements, Views output, media/image/responsive image, menus, comments, user.
• Add a Drush generator, drush jsx:generate-theme, that clones jsx_base the way starterkit_theme does for Twig.
• Port the relevant core theme tests plus Layout Builder, AJAX and BigPipe tests (#3435995: Port Layout Builder tests to umami JSX , #3432275: [META] Tests).
• Run accessibility (axe) and performance budgets (TTFB and hydration cost) against Olivero-on-Twig as the baseline.

Phase C — Core track (parallel, October 2026 – mid 2027)

• Reroll #3525011: Allow complete replacement of the default theme engine (twig) in Drupal core against the 11.3 service architecture, adding an engine-declared fallback and an exclusive mode.
• File and drive the child issues: engine-agnostic SDC discovery; ComponentRenderingEngineInterface; cross-engine include(); an SDC-capable nyan_cat test engine.
• Present the plan at a DrupalCon or camp session and at a core committer office hour to get framework-manager sign-off early.
• Coordinate with Canvas maintainers so JSX-owned SDC components appear in Canvas's component library.

Phase 4 — Stable

2.0.0 ships when these gates are all met:

• The core SDC APIs from Phase C are in a released Drupal minor, and the contrib bridge becomes a shim for older 11.x versions.
• No open critical or major bugs; test coverage includes every ported template.
• Security advisory coverage opted in, which requires a stable release and a vetted maintainer.
• Documentation covers the theming guide, SDC-in-JSX guide, migrating a Twig theme, and SSR hosting.

Risks and open questions

The largest risk is that the core track moves slower than the contrib work. The mitigation is a contrib bridge that is good enough to ship a beta without core changes.

Open questions:

• Framework scope: Preact-only for stable, with React and Solid as community adapters, or keep all three first-class?
• Branch: start 2.0.x, or continue 1.0.x because it was never released?
• SSR default: is a Node sidecar acceptable as the production default, or must client-only be the default?
• Canvas: should JSX SDC components be registered as Canvas "code components", or only as SDC components that Canvas already understands?

Sources

• JSX Theme Engine project page and issue queue
• drupal-jsx GitHub organization: hyperscriptify, propsify, serialize-prop-types, drupal-utils, drupal-utils-react, drupal-utils-dev, vite-plugin-drupal, starter-react
• JSX issues: #3397049: Integrate with AJAX, #3396749: Automate the generation of *.template-info.json files from the components' PropTypes declarations, #3393032: Add a server-side rendered (SSR or RSC) build for Umami JSX, #3396976: Integrate with SDC (single directory components), #3398446: Add type coercion logic to jsx.engine so that themes can declare prop types based on their needs, not on knowledge of Drupal internals, #3396754: Convert all Twig templates to JSX components for a single URL
• Core: #3525011: Allow complete replacement of the default theme engine (twig) in Drupal core and #1685492: Convert theme engines into services, plus change record 3547356
• Experience Builder: #3446434: Document "Semi-Coupled Theme Engine" and "Redux-integrated field widgets" components
• Canvas #3556101: semi-coupled engine broken on 11.3 and Canvas #3555062: removing the engine
• Drupal core release schedule
• Drupal core source, main branch (12.0-dev, September 18, 2026): ThemeManager.php, ComponentPluginManager.php, ComponentElement.php, TwigThemeEngine.php, ThemeEngineInterface.php, and template counts from core/modules

AI disclosure

The author used Claude Code throughout authoring this plan, with human review and decisions made independently, per Drupal.org's AI contribution policy.