Renderer compatibility

This reference is for existing applications that retain project-wide renderer settings or Lit templates.

For new v3 components, use Ignite JSX and component-local styles.

The current packages still export defineIgniteConfig and the optional Lit renderer.

Keeping this compatibility reference does not make them part of the handbook’s recommended setup.

For v2 applications, start with Update configuration imports.

The `ignite.config.ts` file

ignite.config.ts is an ordinary TypeScript module that calls defineIgniteConfig and export defaults the result.

Load it explicitly from your application entry module.

The filename is a convention; another module name works too.

Install the package you import directly:

pnpm add @ignite-element/renderer@beta

1. Create the config file

Save this at your project root or another location your bundler can resolve:

import { defineIgniteConfig } from '@ignite-element/renderer';

export default defineIgniteConfig({
  styles: new URL('./styles.css', import.meta.url).href, // injected into each shadow root
  logging: 'warn', // "off" | "warn" | "debug"
});

2. Load it before component registration

Import the config once at the top of your application entry module:

// main.ts (app entry)
import './ignite.config';
import './components/ignite-counter';

3. Build with your existing toolchain

Vite, Webpack, and esbuild resolve the config as an ordinary TypeScript module.

The configuration takes effect when the module is imported.

See Getting started for the separate JSX settings.

`defineIgniteConfig` options

defineIgniteConfig(config: IgniteConfig): IgniteConfig normalizes and registers the config.

Returns the normalized IgniteConfig that was registered (the effective value).

Option	Type	Default	Purpose
`styles`	`string \| { href, integrity?, crossOrigin? }`	—	Stylesheet injected into every component shadow root.
`renderer`	`"ignite-jsx" \| "lit"`	auto-detect	Force one renderer project-wide, overriding per-view auto-detection.
`strategy`	`"diff" \| "replace"`	`"diff"`	Render-update strategy (see below).
`logging`	`"off" \| "warn" \| "debug"`	`"off"`	Renderer/strategy diagnostics.

Component-local <style> tags remain the default scoped-styling path; styles is for stylesheets shared across every component.

Add light-DOM styles in your host app as usual.

Renderer selection

Ignite selects the renderer from each view’s output.

After importing @ignite-element/renderer/lit, a lit-html TemplateResult uses Lit.

Other output uses Ignite JSX.

Install the Lit dependencies to use this renderer:

pnpm add ignite-element@beta @ignite-element/renderer@beta lit-html

Because this path imports a scoped renderer directly, @ignite-element/renderer must be a direct dependency.

Normal facade/JSX consumers do not need to install scoped packages explicitly.

This fragment assumes component is your source-backed core with isOn and toggle, as in Getting started.

import '@ignite-element/renderer/lit';
import { html } from 'lit-html';

component('ignite-toggle', ({ isOn, toggle }) =>
  html`<button @click=${toggle}>${isOn ? 'On' : 'Off'}</button>`
);

See Rendering for the full authoring and selection story.

Set renderer here only to force one strategy project-wide, overriding auto-detection — for example, to render every component through lit regardless of output:

import { defineIgniteConfig } from '@ignite-element/renderer';

export default defineIgniteConfig({
  renderer: 'lit',
});

An unknown renderer value is normalized by legacy compatibility behavior and logged — don’t rely on that path.

Render strategies

The render strategy controls how DOM updates apply.

The default diff strategy minimizes DOM changes for JSX components.

The replace strategy mirrors Lit’s replacement behavior.

To set a project-wide strategy:

import { defineIgniteConfig } from '@ignite-element/renderer';

export default defineIgniteConfig({
  strategy: 'replace',
});

Per-component strategy overrides are internal and not part of the public API.

Advanced primitives

Use these @ignite-element/renderer functions when building tooling, custom renderers, or diagnostics.

import {
  registerRenderStrategy,
  resolveRenderStrategy,
  getRegisteredRenderStrategies,
  getIgniteConfig,
} from '@ignite-element/renderer';

registerRenderStrategy(rendererId, factory) — register a custom render-strategy factory under a renderer id. The built-in ignite-jsx (default) and lit strategies register themselves when you import their entry points. Returns nothing.
resolveRenderStrategy(rendererId) — returns the render-strategy factory registered for an id, falling back to the default strategy (with a warning) if the id is unknown.
getRegisteredRenderStrategies() — returns string[]: the renderer ids that currently have a registered strategy.
getIgniteConfig() — returns the effective IgniteConfig registered by defineIgniteConfig, or undefined when no config is registered.

Other symbols on the package (injectStyles, flushPendingStyles, getGlobalStyles/setGlobalStyles) are @internal implementation details.

Manage shared styles through defineIgniteConfig({ styles }) instead.

Notes & troubleshooting

With no renderer set — whether config is absent or present only for styles/logging — Ignite auto-detects per view (lit for lit-html output, Ignite JSX otherwise).
lit is not part of the stable ignite-element root surface — import @ignite-element/renderer/lit to make the lit strategy available; auto-detection then selects it for lit-html views.
globalStyles is a deprecated alias for styles; migrate to styles.

Sources — connect source behavior to a component.
igniteCore — the component factory these options apply to.
Compatibility — supported lit-html and toolchain versions.