Compiler API

compile(src, filename, options)

Returns a Promise of the compile result. compileSync(src, filename, options) returns the result directly.

The filename does not need to exist on disk, which suits sources a bundler holds in memory. Tag discovery and relative imports resolve from its directory.

import { compileSync } from "@marko/compiler";

const { code } = compileSync(
  "<p>Order #${input.orderId} has shipped</p>",
  "/app/src/tags/shipping-notice.marko",
);

compileFile(filename, options)

Reads filename through the fileSystem option, then compiles it as compile does. compileFileSync(filename, options) is the synchronous form.

Metadata

Errors

A template that fails to compile throws a CompileError. Its message carries the file position and a code frame, so logging the error shows where it occurred. Integrations that print errors in their own format read its other properties.

When a template has several errors, a single CompileErrors is thrown with the individual CompileErrors in its errors array.

output

A template compiled once with "html" and once with "dom" produces the server and browser halves of the same component. See targeted compilation.

entry

Compiles the template as an entry point instead of a plain module. Requires linkAssets.

linkAssets

Connects the server output to the browser assets a bundler builds. It belongs on every compile, server and browser alike.

The server build compiles each page with entry: "page", which reports the page, and each template it bundles with output: "html", which reports the templates they load lazily. Each reported asset then gets a browser entry.

import path from "node:path";
import { compileFile } from "@marko/compiler";

const assets = new Map();
const options = {
  linkAssets: {
    runtime: path.resolve("asset-runtime.js"),
    onAsset(kind, file, id) {
      assets.set(id, { kind, file });
    },
  },
};

const page = "./src/pages/checkout.marko";
const entry = await compileFile(page, {
  ...options,
  output: "html",
  entry: "page",
});
const template = await compileFile(page, { ...options, output: "html" });

for (const [id, { kind, file }] of assets) {
  const browser = await compileFile(file, {
    ...options,
    output: "dom",
    entry: kind,
  });
  // Bundle `browser.code`, then record the tags that load it under `id`.
}

The runtime module reads the tags the build recorded.

import manifest from "./dist/asset-manifest.json" with { type: "json" };

export function flush($global, type, id) {
  return manifest[id]?.[type] ?? "";
}

resolveVirtualDependency

A template can produce more than one module. Each <style> block becomes its own stylesheet, and some generated modules register values for the browser. The compiler calls resolveVirtualDependency(filename, dep) for each one and imports the path it returns.

The bundler serves the returned path with dep.code. A path that keeps the extension of virtualPath gets the bundler's usual handling for stylesheets and scripts. Without this option, <style> block contents are left out of the output.

import path from "node:path";

const virtualModules = new Map();

function resolveVirtualDependency(filename, { virtualPath, code, map }) {
  const id = path.join(path.dirname(filename), "__virtual__", virtualPath);
  virtualModules.set(id, { code, map });
  return id;
}

modules

The module format of the output, "esm" (the default) or "cjs".

optimize

Compiles for production: templates import the production runtime instead of its debug build and use shorter internal names. By default it is on when NODE_ENV is set to anything other than "development". A MARKO_DEBUG environment variable overrides that, turning it off unless set to false or 0.

optimizeKnownTemplates

A list of template paths that receive short, sequential ids when optimize is on. Server and browser compiles must use the same list.

runtimeId

Distinguishes the Marko runtimes on a page that loads more than one of them. It must start with a letter or underscore and contain only letters, numbers and underscores.

sourceMaps

code

When false, skips generating code, which saves time when only meta or ast is needed. Defaults to true.

ast

When true, includes the final Babel AST in the result. Defaults to false.

stripTypes

Removes TypeScript types from the output. When unset, types are removed for every output except "source" and "migrate".

translator

The translator that turns templates into JavaScript, as a module id or a translator object. By default it is the translator of the installed marko package, or of a @marko/runtime-* package listed in the application's package.json.

fileSystem

An fs-compatible object the compiler reads through, providing readFileSync, statSync and readdirSync (and readFile for compileFile). Defaults to Node's fs, and lets a bundler share its own cached file system.

cache

A Map that holds compiled templates, so a template used by several others is analyzed once. Entries are reused until the template or a file it depends on changes. Since each template's analysis is reused between them, compiles that share a cache are expected to use the same options apart from output. By default every compile shares one Map.

babelConfig

Babel options merged into the configuration the compiler uses to parse and generate code.

getTemplateId

A function (filename) => id that replaces the default template id, the template's percent-encoded path relative to the project root.

errorRecovery

When true, recoverable errors are recorded in the result's meta.diagnostics instead of being thrown, so tools such as editors can report every problem in a template.

applyFixes

Selects which migration fixes run. When set, only diagnostics whose index is a key of this Map apply their fix, receiving the mapped value. By default every fix applies.