Installation

Pick your package manager and install Ignite Element with the one state adapter you use:

pnpm add ignite-element@beta xstate
# pnpm add ignite-element@beta @reduxjs/toolkit   # Redux
# pnpm add ignite-element@beta mobx               # MobX

The state libraries are optional peer dependencies, so only the one you install is pulled in — adding ignite-element@beta never drags in Redux/MobX/lit when you only use XState. ignite-element depends on the scoped @ignite-element/core, @ignite-element/adapters, and @ignite-element/renderer packages internally; they install automatically and you don’t reference them directly.

Node 22+ and TypeScript 5.x are required. For the full version matrix (state libraries, lit-html), see Compatibility.

1) Configure JSX (required for the default Ignite JSX path)

Add the Ignite JSX runtime to your tsconfig.json (or use a file-level pragma):

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "ignite-element/jsx"
  }
}

2) Start building

For the default path, you do not need ignite.config.ts, a bundler plugin, or shared adapter teardown overrides. The default Ignite JSX renderer is registered automatically by the public entrypoints.

Optional advanced and legacy setup

Use the advanced setup only when you need @ignite-element/renderer primitives for shared styles or renderer diagnostics. (Using lit is not advanced — it is config-free; see Rendering.)

Advanced config: ignite.config.ts, renderer selection, and bundler notes

Runtime dependencies and tree shaking

Ignite Element stays lean but is not literally “zero dependency”: you must install the state library you choose (XState, Redux Toolkit, or MobX). Ignite JSX uses a minimal custom renderer (no framework runtime). If you opt into the lit renderer, install lit-html. Import from the adapter entry point that matches your state library (ignite-element/xstate, ignite-element/redux, or ignite-element/mobx) so only the renderer and adapter you pick are pulled into your bundle and unused adapters are tree-shaken.

Verify your setup

Run a TypeScript check (e.g., pnpm exec tsc --noEmit or npx tsc --noEmit) to ensure JSX settings work.
Create a smoke test component via Your first component.
Add config/plugins only if you need global renderer defaults, shared styles, or diagnostics. Using lit needs none of these — just import @ignite-element/renderer/lit.

Project checklist

A baseline for a real project:

Node & package manager: Node 22+. Pick pnpm, npm, or yarn and use it consistently.
TypeScript JSX: set "jsx": "react-jsx" and "jsxImportSource": "ignite-element/jsx" (or the per-file pragma).
Testing: add a runner (Vitest or Jest) and a smoke test per web component (mount + basic interaction). See Test components.
Linting/formatting: use your preferred stack (ESLint/Prettier, Biome, …); the package imposes none.
Advanced setup (optional): reach for ignite.config.ts only when you need project-wide renderer defaults, shared styles, or diagnostics. Lit is config-free — see Rendering.