Solid Layouts

Solid Layouts separates a Solid component's presentation recipe and markup from its behaviour, then compiles the package and the consuming application in two explicit passes.

Compilation is required. Authored .layout.tsx is template syntax, not ordinary TSX, and there is no runtime or graceful fallback when the compiler cannot match a template.

JSX names are case-sensitive. <button> is a native HTML element and bypasses Layout resolution; <Button> is an imported Layout component and must match the exact export recorded in C. Because lowercase <button> is valid HTML, E cannot assume it was intended to mean <Button>.

Start here

• Complete producer and application example
• Why the library compiler produces an intermediate npm package
• Compiler modes, public entry points, failures, and the Chuzz integration
• Porting from Vue
• Layout linting, porting reports, baselines, and user-owned recipes
• Local complex components and the cross-application pattern inventory
• Releasing with npm Trusted Publishing
• Original design document

The pipeline

A = authored UI package containing recipes and Layout template syntax
B = solid-layouts library compiler
C = generated, npm-ready Layout UI package
D = ordinary Solid application source
E = solid-layouts application compiler
F = executable JavaScript and assets

A + B     -> C
C + D + E -> F

The two passes have different jobs:

Stage	Runs where	Responsibility
B	UI library build	Turn invalid authoring syntax into valid generated TSX, compile recipes, validate slots, generate entries and emit the Layout manifest
E	Solid application build	Resolve C, validate its package and manifest, match exact imported exports, rewrite those imports to C's validated public entry, and enable the normal Solid/Rsbuild build

If B cannot match an authored template to its recipe, B fails. If E cannot resolve C or an imported component is absent from C's manifest, E fails. If E is removed, C's compiler boundary remains unresolved and the application build fails.

Where UI/ comes from

UI/ is not part of this repository and is not generated by solid-layouts. It is the component-library source that plays role A.

There are two concrete sources:

1. Test-UI/ in this repository is the working four-component producer fixture. It contains Icon, Button, Flex, and Chip extracted from the larger Pathscale migration and is a small complete A+B→C example.
2. pathscale/ui PR #221 is the full Layout-authored migration. It was compiled, validated, merged, and published in the Layouts-only 2.x series; the current package is @pathscale/ui@2.0.0.

To inspect the full authored UI:

git clone https://github.com/pathscale/ui.git UI

An application must never alias imports to raw UI/src. The application consumes the C bundle produced by B as @pathscale/ui from npm. Test-UI/bundle remains the small compiler fixture, not the production package.

Install and use the published pipeline

Install the runtime and application plugin in a Solid/Rsbuild application:

bun add @pathscale/ui solid-layouts
bun add -d rsbuild-plugin-solid-layouts

The published packages are solid-layouts@0.1.2, solid-layouts-oxc@0.1.6, rsbuild-plugin-solid-layouts@0.1.3, and @pathscale/ui@2.1.0. The platform-specific native compiler binding is selected automatically for Apple arm64, Linux x64 GNU, or Linux arm64 GNU.

For the application half, add pluginSolidLayoutsApplication before the Babel and Solid plugins:

import { defineConfig } from "@rsbuild/core";
import { pluginBabel } from "@rsbuild/plugin-babel";
import { pluginSolid } from "@rsbuild/plugin-solid";
import { pluginSolidLayoutsApplication } from "rsbuild-plugin-solid-layouts";

export default defineConfig({
  plugins: [
    pluginSolidLayoutsApplication({
      layouts: ["@pathscale/ui"],
    }),
    pluginBabel({ include: /\.(?:jsx|tsx|ts)$/ }),
    pluginSolid(),
  ],
});

pathscale/chuzz PR #9 is the real consumer example. It resolves @pathscale/ui, the runtime, and the plugin exclusively from the package registry; it contains no sibling-checkout aliases.

Public entry points

import {
  compileLibrary,
  pluginSolidLayoutsLibrary,
} from "solid-layouts-oxc/library";

import {
  compileApplication,
  compileApplicationFile,
  pluginSolidLayoutsApplication,
} from "solid-layouts-oxc/application";

// Stable Rsbuild facade for application and library projects:
import {
  pluginSolidLayoutsApplication,
  pluginSolidLayoutsLibrary,
} from "rsbuild-plugin-solid-layouts";

The equivalent command-line entry points are solid-layouts-library and solid-layouts-application. The hosts always select library or application mode explicitly; mode is never inferred from a filename or package.

The shared OXC linter is solid-layouts-lint. Use normal mode for Layout library contracts and solid-layouts-lint --porting --layouts @pathscale/ui for a warning-only inventory of ordinary SolidJS application code. Porting mode finds manual Layout overrides, state-driven classes, styled native controls, and repeated static class signatures categorized as layout utilities, typography/tone, or compound recipe candidates; it does not interpret application TSX as Layout template syntax.

Tests

Yes, all three layers have tests:

Layer	Coverage	Command
Runtime	143 Bun tests plus TypeScript	cd packages/solid-layouts && bun run test && bun run typecheck
Native compiler	56 Rust unit/conformance tests	cd packages/solid-layouts-oxc && cargo test --workspace
Library host	7 package-production and discovery tests	cd packages/solid-layouts-oxc && bun run test:library
Application host	14 package-resolution, source-rewrite, and hard-failure tests	cd packages/solid-layouts-oxc && bun run test:application
Upstream Solid JSX	74 pinned DOM Expressions compiler fixtures	cd packages/solid-layouts-oxc && bun run test:upstream-solid

CI also runs cargo fmt, Clippy with warnings denied, regenerates the compiled parity fixture, rebuilds the four-component C fixture, and fails if generated output is stale. The JavaScript host tests require the local native binding:

cd packages/solid-layouts-oxc
./scripts/build-binding.sh
bun run test:library
bun run test:application

Repository layout

Test-UI/                    complete four-component A+B->C fixture
packages/solid-layouts/     shared Solid runtime
packages/solid-layouts-oxc/ both compiler hosts and the OXC transform
  application.js           application compiler E
  library.js               library compiler B
  crates/common/           modes, options and diagnostics
  crates/transform/        parser and native transforms
fixtures/                   input/output conformance corpus
docs/                       usage, architecture and migration guides

OXC versions are pinned deliberately. Its AST changes between releases, so dependency bumps are compiler changes that require fixture and test review.