format compile

# Compile all documents
npx format compile

# Compile select documents
npx format compile --documents invoice monthly-update

Documents match the folder name of the document.

Each compile replaces the output directory, including documents from an earlier compile. To include several documents in one bundle, name them all in one command.

There are three options for assets:

• Static: bundles every known asset into a per-document assets.zip at build time (default).
• Dynamic: outputs the raw assets and embeds a URL map in the bundle and builds the zip at render time, allowing you to replace dynamic assets before rendering.
• None: outputs no assets. You should use @format.dev/zip to create an assets zip.

--assets is Ignored with --output html, which always bundles assets at build time.

Read more about how to work with assets.

The --preset flag is a shorthand that sets --target along with sensible defaults for bundling and module resolution conditions.

You can combine a preset with explicit overrides. For example, use the edge preset but exclude a package:

npx format compile --preset edge --external some-large-lib

In most cases, --preset is all you need. Use --target directly if you need pinpoint control over bundling and conditions yourself.

Choose the JavaScript environment your renderer will run in. --target sets the runtime assumptions only. In most cases you should prefer --preset.

node (default)

Framework packages (react, react-dom, vue) are left out of the bundle and must be installed where the renderer runs. Most other packages too. Use --bundle to include specific ones:

npx format compile --target node --bundle date-fns lodash

browser

All dependencies are bundled in by default, producing a self-contained module. No Node.js APIs are assumed. Use --external to exclude packages you load separately:

npx format compile --target browser --external date-fns

worker

For edge or worker runtimes. Like browser, no Node.js or DOM APIs are assumed. The framework is bundled, but other dependencies are externalized by default. Opt them in with --bundle, or switch to --preset edge which bundles everything and applies worker-friendly module resolution.

npx format compile --preset edge

We generally recommend using a JavaScript output bundle, so it can be invoked dynamically at runtime. If your templates contain any sort of dynamic data, this really should be the preferred route.

However, if either want pre-rendered HTML based on your studio variants, or plan to pipe the HTML into your own existing (likely non-JS) ecosystem — i.e. .NET, the HTML output mode can be used.

Compiling to HTML

With the following command:

npx format compile --output html

You would get the following example output:

Each document has an assets.zip, which holds the document's full asset set, across all variants. A document with no assets gets no zip.

default and alternative are variants in the above example.

manifest.json lists what was generated, for programmatic consumers:

{
	"output": "html",
	"engine": "1.2.3",
	"documents": [
		{
			"document": "invoice",
			"assets": "invoice/assets.zip",
			"variants": [
				{ "variant": "default", "html": "invoice/default/index.html" },
				{ "variant": "alternative", "html": "invoice/alternative/index.html" }
			]
		},
		{
			"document": "monthly-report",
			"assets": "monthly-report/assets.zip",
			"variants": [
				{ "variant": "default", "html": "monthly-report/default/index.html" },
			]
		}
	]
}

Choosing variants

By default, the HTML output mode renders every variant a document has. Use --variants to narrow it:

The following flags are not compatible with the HTML output mode: --target, --preset, --external, --bundle, and --cjs.

Remote assets

--remote-assets works with the HTML output mode, and it applies to every variant. Any remote assets referenced across any variants will be folded into the document's assets ZIP.

Publishing your bundles as an NPM package.

Publishing your bundles as an NPM package.