OpenElement

English | 简体中文

OpenElement is a Web Platform-first core for two products: Element and Router. Element compiles JSX-authored Custom Elements into a Part Program used by server serialization, fresh DOM, and existing-DOM hydration. Router owns route selection, HTTP semantics, navigation, loaders, actions, and the shared Framework Mode application contract (one compiled-native renderer, selected explicitly).

The source tree is 1.0.0-alpha.15, a new public baseline for Element and Router. It is not a compatibility migration from historic 0.x snapshots. From this release the six packages (protocol, element, compiler, router, create, ui) publish as one line, and npm latest points at that line — npm install @openelement/router resolves to the current 1.0 prerelease. Since #1557 the Element monolith is three packages: @openelement/protocol (cross-system contracts, zero dependencies), @openelement/element (pure runtime), and @openelement/compiler (build-time TSX-to-Part-Program compiler + Vite plugin).

The description above is the current alpha.15 implementation. The accepted target is HTML-first Full TSX with explicit Signals and an explicit CE boundary. On 2026-11-03 the owner ended the independent OhMyLit initiative and initiated first-party Lit renderer retirement; the 2026-11-08 owner ruling (ADR-0152) executes that retirement with no compatibility window. The current source line no longer ships the first-party Lit renderer — its public entry points, runtime branch, tests and fixtures are removed, and renderer: 'lit' fails with an explicit migration error — while the published alpha.15 artifact still contains it. Third-party Lit WC client-only use remains, without automatic SSR or Lit DSD hydration guarantees. The candidate author samples are unreleased and unverified, not the Quick Start API.

Evidence & recognition

These references are reproducible and verifiable by third parties.

• Software Heritage
• js-framework-benchmark — external benchmark results (check the entry for its measured version)
• deps.dev package view and npm provenance attestations on npm
• Bundle size via Bundlephobia

Quick Start

Requires Node.js 24.2+ (24.18.0 recommended) and a package manager: npm, pnpm, yarn, or bun (the scaffolder prefers the invoking package manager, then probes PATH in pnpm/npm/yarn/bun order; the generated project is package-manager neutral). Create, run, and build — the generator installs the dependencies itself, so there is no separate install step:

npm create @openelement my-app
cd my-app
npm run dev
npm run build

Add a page — one compiled element plus one route record:

// app/components/page-hello.tsx
import { element, OpenElement } from '@openelement/element';

@element('hello-page', { root: 'shadow-open' })
export default class HelloPage extends OpenElement {
  render() {
    return (
      <main>
        <h1>Hello from OpenElement</h1>
      </main>
    );
  }
}

// app/routes/hello.tsx
import { definePage } from '@openelement/router';
import HelloPage from '../components/page-hello.tsx';

export default definePage(HelloPage, {
  head: { title: 'Hello' },
});

Re-run npm run dev, open the URL Vite prints plus /hello, and npm run build emits the static-first dist/ output. Full walkthrough: https://openelement.org/guide/getting-started.

Build-time host: Framework Mode development and builds run on Node.js 24.2+ through application package scripts (ADR-0161, superseding the Deno-native decision in ADR-0108): the @openelement/router tooling subpaths (./vite, ./cli/*) are consumed through the starter's own dependency pins as plain Node programs. The request-time output uses standard ESM and Web Request/Response; deployment support is limited to the runtimes and Nitro targets actually covered by the qualification matrix, not every runtime that can load ESM. Element remains independently consumable in npm-only projects.

Features

• Declarative Shadow DOM plus SSR, existing-DOM hydration, and islands that hydrate only where needed.
• Authoring JSX is compiled to a Part Program at build time; there is no runtime virtual-DOM contract.
• Route Mode for explicit route records and Framework Mode for file routes, loaders, actions, and forms.
• One compiled-native renderer behind the application contract; renderer selection stays explicit, and the retired Lit renderer is rejected with a migration error.
• Compiled output tree-shakes so server-only modules never leak into the client bundle.

Repository shape

• packages/protocol — the cross-system contract package (#1557): Part Program IR, error dialect, admission descriptors; zero dependencies, contracts only.
• packages/element — the Element core product: the pure runtime; depends only on protocol plus @preact/signals-core at publish time.
• packages/compiler — the Element compiler (#1557): the TSX-to-Part-Program semantic core and the Vite plugin boundary; TypeScript lives here within the Element three-package split, while Router tooling also depends on TypeScript.
• packages/router — the Router core product: Route Mode and Framework Mode plus the application lifecycle tooling (@openelement/router/vite, /nitro-mount, /cli/*).
• packages/create — the supported creation entry for the two core products.
• packages/ui — experimental UI product, maintained in this repository outside the 1.0 stable promise.
• www — the official product surface (documentation site).
• apps/saas — an independent first-party consumer application, maintained in this repository but separately governed; it is not part of the framework core or the Alpha repository candidate.

Element and Router are the public framework core. UI is an experimental product; Site is the official product surface; SaaS is an independent first-party application governed separately and is not part of the Alpha repository candidate. None extends the Element/Router stable API promise, and all are owned and maintained by this repository. Historical snapshots remain available through Git tags.

Development

The source repository is a pnpm workspace on Node (.node-version pins the development line, 24.18); published npm artifacts are qualified separately in disposable npm consumers.

pnpm install
pnpm run fmt:check
pnpm run lint
pnpm run typecheck
pnpm test
pnpm run build

Documentation

• Current architecture (in force)
• Active decisions
• Archive and removal register
• Security policy
• Contributing

OpenElement is available under the MIT license.