@tagged-jsx/ts-plugin

TypeScript language service plugin that provides real-time diagnostics for JSX syntax inside tagged template literals. Surface semantic errors, type checking, and IntelliSense for template expressions like html`<div>${content}</div>` directly in your editor.

No build step required — the plugin rewrites templates to JSX on the fly inside the language service.

How it works

The plugin hooks into the TypeScript language service by wrapping getSemanticDiagnostics. For each file the user opens or edits, it:

1. Finds all tagged templates matching configured tags (e.g., html`...`)
2. Rewrites each template to valid JSX using @tagged-jsx/transform
3. Creates a synthetic TypeScript program with the rewritten source (using ts.createProgram with a custom compiler host)
4. Runs the TypeScript compiler on the synthetic program to get diagnostics
5. Maps diagnostic positions back to the original template literal positions using character-level offset mapping

This means TypeScript's type checker sees:

// What you write:
html`<div class=${active ? "on" : "off"}>
  <${MyComponent}>${children}</${MyComponent}>
</div>`

// What TypeScript sees (in-memory, via the plugin):
<div class={active ? "on" : "off"}>
  <MyComponent>{children}</MyComponent>
</div>

Diagnostics (type errors, missing props, etc.) are then mapped back to the correct positions in your original template literal source.

Installation

npm install --save-dev @tagged-jsx/ts-plugin

Configuration

Add the plugin to your tsconfig.json. For SolidJS projects, configure JSX with Solid's import source:

{
  "compilerOptions": {
    "jsx": "react",
    "jsxImportSource": "solid-js",
    "plugins": [
      {
        "name": "@tagged-jsx/ts-plugin",
        "tags": ["html", "jsx"],
        "useCallbacks": true
      }
    ]
  }
}

After changing tsconfig, restart your TS server in VS Code (TypeScript: Restart TS Server).

Plugin options

| Option | Type | Default | Description | |--------|------|---------|-------------| | tags | string[] | ["jsx"] | Tag names to treat as JSX tagged templates | | useCallbacks | boolean | false | Enable expression transform callbacks |

tags

Controls which tagged template identifiers trigger JSX parsing:

{ "tags": ["jsx", "html", "css"] }

All matching templates in your source files will be checked for JSX diagnostics.

useCallbacks

When enabled, expressions are wrapped with () => during the tagged→JSX conversion and unwrapped on the reverse path. This matches the semantics of SolidJS-style reactive template libraries where interpolated values are treated as lazy thunks.

Without callbacks (default):

// Tagged template
html`<div class=${activeClass}>${content}</div>`

// Diagnostics will be checked against:
<div class={activeClass}>{content}</div>

With callbacks (useCallbacks: true):

// Tagged template (SolidJS reactive):
html`<div class=${() => activeClass}>${() => content()}</div>`

// The plugin unwraps () => before checking diagnostics:
<div class={activeClass}>{content()}</div>
// then back-maps diagnostics to:
html`<div class=${() => activeClass}>${() => content()}</div>`
// Callbacks handle the () => wrapping for reactive frameworks

How diagnostics are mapped

The plugin uses the mapping system from @tagged-jsx/transform to translate positions. When TypeScript reports an error at position X in the JSX output, the plugin:

1. Looks up the reverse mapping for position X
2. Finds the corresponding position in the original tagged template source
3. Returns the mapped diagnostic to the editor

This means error squiggles, hover info, and quick fixes all appear at the correct locations in your template literals.

Limitations

• The synthetic program created for diagnostics does not have access to the full project context (type resolution is limited to the single file being checked)
• Complex type dependencies across files may not resolve in synthetic diagnostics
• The plugin currently only overrides getSemanticDiagnostics — syntactic diagnostics, completions, and quick info use the default language service

License

MIT