Skip to content

README.md

Latest commit

 

History

History
152 lines (112 loc) · 7.42 KB

README.md

File metadata and controls

152 lines (112 loc) · 7.42 KB
Raw

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

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.