Overview

Before you can generate PDFs in production, your Format documents need to be compiled into a renderer bundle. Compilation transforms your framework components (React, Vue, or HTML) into an optimized JS module, resolves your styles and dependencies, and packages your static assets into an assets.zip per document.

There are a few ways to compile your documents: the CLI, a bundler plugin or the Next.js plugin.

Which should I use?

• Using Next.js? Opt for the Next.js plugin. It handles compilation, caching, and deployment configuration for you.
• Already using a bundler? (Vite, webpack, Rollup, esbuild): Use a bundler plugin. Compilation runs as part of your existing build.
• Not bundling? (Node.js, Lambda, Hono, etc): Use the CLI. It produces a standalone bundle with no build tool required. The CLI can also be useful in CI/CD environments.

CLI

The format compile command produces a standalone renderer bundle without needing an existing build tool. This is a good fit for dedicated build steps in CI/CD pipelines, monorepos with a separate publishing stage, or projects that don't use a bundler at all.

# Compile all documents:
npx format compile

# Compile the Invoice and Receipt documents for a Node environment:
npx format compile --documents invoice receipt --preset node

The output of compile is written to _generated relative to your configured rootDir:

Import the bundle by pointing at the _generated directory. Each of your documents will return a FormatRenderer.

import { invoice } from './_generated'
import { FormatClient } from '@format.dev/client'

const doc = await invoice.render({ customerName: 'Ada Lovelace' })

const format = new FormatClient()
const response = await format.pdf(doc)
await response.toFile('./output/invoice.pdf')

import { invoice } from './_generated/index.js'
import { FormatClient } from '@format.dev/client'

// Set the location of your assets ZIP (emitted at build time)
invoice.setAssetsUrl('https://cdn.example.com/invoice/assets.zip')

const doc = await invoice.render({ customerName: 'Ada Lovelace' })

const format = new FormatClient()
const response = await format.pdf(doc)

// Example: create a blob URL to view the PDF
const blob = await response.blob()
const url = URL.createObjectURL(blob)

import { invoice } from './_generated/index.js'
import { FormatClient } from '@format.dev/client'

// Set the location of your assets ZIP (emitted at build time)
invoice.setAssetsUrl('https://cdn.example.com/invoice/assets.zip')

export default {
	async fetch(request, env) {
		const doc = await invoice.render({ customerName: 'Ada Lovelace' })

		const format = new FormatClient()
		const response = await format.pdf(doc)

		// Example: Send the PDF back as a response
		return new Response(response.body, {
			headers: { 'Content-Type': 'application/pdf' }
		})
	}
}

See the Renderer API reference for the full method documentation.

Publishing as an npm package

Because the compiled bundle includes a package.json, it can be published to npm or a private registry. This lets other teams within your organization import a versioned renderer without needing access to the original Format documents or the Studio build setup.

Use --bundle-name and --version to produce a publishable package in one step:

npx format compile --bundle-name @acme/pdf-renderers --version 1.0.0

npm publish _generated --registry https://npm.pkg.github.com

Without --version, the bundle's package.json includes private: true as a guard against accidental publishing.

Consuming teams install and import it as a normal package:

npm install @acme/pdf-renderers

import { invoice } from '@acme/pdf-renderers'

const doc = await invoice.render({ customerName: 'Ada Lovelace' })

Bundler plugin

The Format bundler plugin integrates document compilation directly into your existing build pipeline. Rather than a separate compile step, your bundler handles compilation alongside the rest of your project.

Bundler plugins expose your documents using the @format:documents virtual module. This returns a FormatRenderer.

import { invoice, receipt } from '@format:documents'

The plugin compiles your documents on first import and re-compiles automatically when document files change during development.

Format supports the following bundlers:

• Vite
• Rollup / Rolldown
• Webpack
• esbuild