@gluonjs/compiler

@gluonjs/compiler is Gluon's shared source-location and module-transform foundation. It records html and css tagged-template boundaries and interpolation locations, produces high-resolution source maps, and supplies the development wrappers consumed by @gluonjs/vite.

parseGluonSfc() is the public parser boundary used by editor tooling. It returns template/script/style block ranges and parser errors so editor diagnostics do not implement a second .gluon grammar. Aliased compose(Component, props)\body`calls are recorded as template boundaries with the same source-location and inline-style behavior ashtml. Imports from @gluonjs/core/decoratorsare detected explicitly. The compiler exposes the standard/legacy TypeScript decorator transpilation used by the Vite plugin and rewrites@customElement()` to the registered-element HMR bridge in development.

The compiler does not turn templates into a private renderer format. Runtime templates continue to use the public html and css APIs. In production it may attach internal metadata to one statically proven GluonElement shape: a direct fixed html return with exactly one declared primitive property in text position and, optionally, a private readonly event-handler field. This lets the runtime update that text Part without recreating the TemplateResult. Conditions, attributes, directives, multiple dynamic text values, mutable/public secondary bindings, inherited element bases, and custom update() methods are not marked. All production transforms retain source mappings and diagnostics without adding HMR imports.

Imported defineGluonElement() calls receive the functional Custom Element HMR bridge. The compiler also reports source-located invalid autonomous tags, listener/interval creation without setup cleanup ownership, and lifecycle registration deferred beyond synchronous setup.

The public @gluonjs/compiler/diagnostics entry contains the versioned, environment-neutral catalog used by the Language Server, Playground, Devtools reference, compact production codes, and generated JSON documentation.

Inline <style> elements in html templates produce GLUON_TEMPLATE_STYLE_ELEMENT; Gluon browser styling uses constructable stylesheets and adoptedStyleSheets only.

@gluonjs/compiler at a glance

Runtime: universal · Release: 1.13.0

Documentation guide · npm · Source

Public API: @gluonjs/compiler · @gluonjs/compiler/diagnostics

Install

npm install @gluonjs/compiler

Quick start

import {
  transformGluonModule,
  type GluonTransformResult,
} from '@gluonjs/compiler';

const source = `
  import { html } from '@gluonjs/core';
  export const ProductName = (name: string) => html\`<h1>\${name}</h1>\`;
`;

const result: GluonTransformResult = transformGluonModule(
  source,
  '/src/product-name.ts',
  { development: true },
);

console.log(result.templates[0]?.tag); // "html"
console.log(result.diagnostics); // source-located compiler diagnostics

Choose this package when

• Track html, svg, css, and aliased compose() tagged templates.
• Produce source maps and decorator transforms for tooling.
• Support downstream Vite and language tooling packages.

Choose another boundary when:

• Does not render templates or own runtime application state.
• Does not replace the public component model with a private renderer format.

Related documentation

• Presentational SFCs
• Tooling
• Diagnostics

Transform a module

Pass the original source and its filename to transformGluonModule(). The result preserves transformed code and its source map while reporting the templates and diagnostics that tooling can display:

import {
  transformGluonModule,
  type GluonTransformResult,
} from '@gluonjs/compiler';

const source = `
  import { html } from '@gluonjs/core';
  export const ProductName = (name: string) => html\`<h1>\${name}</h1>\`;
`;

const result: GluonTransformResult = transformGluonModule(
  source,
  '/src/product-name.ts',
  { development: true },
);

console.log(result.templates[0]?.tag); // "html"
console.log(result.diagnostics); // source-located compiler diagnostics

Use result.code and result.map together when passing the output to the next build transform. Production callers omit development: true; development mode adds the HMR bridges described above.

Presentational SFC compiler

compileGluonSfc(source, { filename }) lowers a .gluon presentational Single-File Component to ordinary public Core and Quark calls. The maintained application path is the official @gluonjs/vite plugin, which recognizes .gluon files automatically and transpiles their typed script blocks.

The compiler supports typed script, one annotated template, identifier interpolation, a default slot, a prop-driven conditional native root, and one owned constructable stylesheet. It rejects stateful or ambiguous forms instead of adding a second runtime. See the task-oriented SFC guide.

License

MIT License, Copyright © 2026 Marc Malerei.