Server Compilation

Compiling Ahead

Moving template compilation into a build step reads like an obvious optimization. For most projects it changes nothing measurable, since a template compiles once per component definition rather than per instance, in well under a millisecond.

Precompiling earns its place when you already have a build: a long-running server, or a static site.

Already Server Rendering Server rendering means you already have a build, so the only cost is changing an import. A long-running server compiles at boot rather than per request either way, so what precompiling removes is startup cost.

Templates

Keeping html and css in their own files is the recommended way to author a component. getText fetches them at runtime and needs no build. With a bundler they arrive as static imports instead: ?raw for text, and ?ast for a template compiled during the build.

Compiling ahead needs the import graph, so it is reachable only on the bundler path.

import ast from './component.html?ast';
import css from './component.css?raw';

defineComponent({
  tagName: 'my-card',
  ast,
  css,
});

defineComponent takes ast in place of template, and when it receives one the compiler never runs. Only the template changes, and CSS is text either way.

The loaders are built on unplugin, so they run in esbuild, Vite, Rollup, Rolldown, webpack, and rspack.

Specs

A component spec is read into a componentSpec at definition time. writeComponentSpec does that read during a build and writes the result as a module.

import { SpecReader } from '@semantic-ui/specs/server';
import buttonSpec from './button.spec.js';

new SpecReader(buttonSpec).writeComponentSpec('./generated/button.spec.js');

The generated module exports the resolved spec, which defineComponent accepts directly.

import componentSpec from './generated/button.spec.js';

defineComponent({
  componentSpec,
  template,
  css,
});

See the SpecReader reference for what a resolved spec contains.