Tooling

Lit^sx uses the standard JSX/TSX toolchain and compiles authored source into Lit templates and custom elements. Editors, TypeScript, ESLint, Prettier, and Storybook use their normal JSX/TSX support.

Vite

import { defineConfig } from "vite";
import { litsx } from "@litsx/vite-plugin";

export default defineConfig({
  plugins: [litsx()],
});

The plugin transforms project-local .js, .jsx, .ts, and .tsx, runs the supported Lit^sx pipeline, and preserves authored sourcemaps. Processing ordinary Lit modules allows it to emit hydration boundaries when a Lit template consumes a Lit^sx Light DOM component; it does not turn pure Lit classes into Lit^sx components. Modules outside the Vite root remain untouched unless selected through include or reactCompat.transformDependencies.

Important options include:

• defaultDomMode: "shadow" | "light"
• lightDomStyles: "scoped" | "global" | "none"
• reactCompat: true | { domMode, reactKeys, transformDependencies }
• generic authoringPlugins and outputPlugins extension points

Use @litsx/compiler directly only for a custom build integration or programmatic compilation. Build tools that transform many modules can reuse analysis and compiler caches through createLitsxCompilationSession(...):

import { createLitsxCompilationSession } from "@litsx/compiler";

const session = createLitsxCompilationSession({
  projectPath: process.cwd(),
  transformOptions: { sourceMaps: true },
});

const result = await session.transform(source, { filename });
session.invalidate([filename]);
session.dispose();

Call invalidate(...) for changed watched files and dispose() when the build or development server stops. The session also provides transformSync(...).

TypeScript

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "@litsx/core"
  }
}

Run ordinary tsc --noEmit. The @litsx/core/jsx-runtime types cover intrinsic elements, component props, refs, and typed custom events. .tsx is the recommended source format; .jsx is the JavaScript equivalent.

ESLint and formatting

import litsx from "@litsx/eslint-plugin";

export default [litsx.configs["recommended-flat"]];

The recommended preset enables no-native-classname, valid-component-name, and rules-of-hooks. Component names must derive directly to valid custom-element tags, and hooks must keep a stable order: conditions, early-return tails, loops, try blocks, handlers, deferred actions, async render functions, and nested hook declarations are rejected with stable LITSX_* diagnostic codes.

The plugin uses normal JSX/TypeScript parsing. React-shaped source is handled by the optional compatibility compiler. Format source with standard Prettier TSX support.

Storybook

import { createLitsxStorybookConfig } from "@litsx/storybook";

export default createLitsxStorybookConfig();

The helper builds on @storybook/web-components-vite, indexes ordinary .stories.jsx and .stories.tsx, and registers story elements from compiler metadata. Integrations can place Vite plugins explicitly in beforeLitsx or afterLitsx phases.

Optional CSS integrations

Lit^sx does not require a utility-CSS engine. Component styles can use Lit's css template directly, and other CSS systems can compose with the generic authoringPlugins and outputPlugins phases.

The official Vite adapters compose Lit^sx compilation with their CSS engine in the correct order:

• @litsx/tailwind/vite for Tailwind CSS v4
• @litsx/unocss/vite for UnoCSS

Both adapters isolate utility ownership during concurrent component generation and multi-entry builds while keeping shared project-level infrastructure stable.

Integration authors can use the shared finite-class analysis exposed by @litsx/compiler/utility-css. Applications should use one of the adapters instead of calling those low-level helpers directly.

Server rendering

@litsx/vite-plugin exports createLitsxViteAssetResolver(...) for resolving browser module URLs from SSR output. Pair it with @litsx/ssr; the plugin itself does not render HTML. See Server Rendering and Hydration.

React compatibility

Enable reactCompat in the Vite plugin for staged migration. Selected dependency packages can be allowlisted through transformDependencies; unsupported React-hook boundaries are reported instead of leaving a React dispatcher call in the output. New native code should use the standard Lit^sx authoring model.