esbuild

Use the Format esbuild plugin to compile your documents as part of your esbuild build.

The Format esbuild plugin compiles your documents and makes them available via the @format:documents virtual module.

Install

Use the Format CLI to install the @format.dev/compile package.

# Install the Format CLI if you haven't already
npm install "@format.dev/cli" --save-dev

# Add the @format.dev/compile package
npx format add compile

# Install the Format CLI if you haven't already
pnpm add "@format.dev/cli" --save-dev

# Add the @format.dev/compile package
pnpm dlx format add compile

# Install the Format CLI if you haven't already
yarn add "@format.dev/cli" --dev

# Add the @format.dev/compile package
yarn dlx format add compile

# Install the Format CLI if you haven't already
bun add "@format.dev/cli" --dev

# Add the @format.dev/compile package
bun x format add compile

Add the plugin to your esbuild config:

build.mjs

import esbuild from 'esbuild'
import formatEsbuildPlugin from '@format.dev/compile/esbuild'

await esbuild.build({
	entryPoints: ['src/index.js'],
	bundle: true,
	outdir: 'dist',
	plugins: [
		formatEsbuildPlugin()
	]
})

The plugin can be configured by passing options.

build.mjs

import esbuild from 'esbuild'
import formatEsbuildPlugin from '@format.dev/compile/esbuild'

await esbuild.build({
	plugins: [
		formatEsbuildPlugin({ ...options })
	]
})

Usage

Import your documents using the @format:documents virtual module. Export names are camelCase versions of your document folder names.

Render your document and pass the result to the Format API client to generate a PDF:

import { invoice } from '@format:documents'
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 '@format:documents'
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 '@format:documents'
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.

Plugin options

Name	Description
`target`	The output target for the compiled bundle.
`assets`	Asset mode. See `--assets` for more information on the available modes.
`assetsOutDir`	Specify a subdirectory for the `assets.zip`.
`inlineRemoteCss`	Inline remote CSS at compile time. See `--inline-remote-css`.
`validateSchema`	Validate render data against your schema. See `--no-validate-schema`.
`bundleName`	A custom name for the compiled bundle and virtual module. Sets the virtual module import to `@format:<bundleName>`.
`clean`	Whether to clear the Format output directory before recompiling.
`outDir`	Override the base internal output directory for the compiled Format bundle. See `--out-dir`. Rarely needs to be changed. Resulting structure: `{bundler outDir}/{outDir}/{documentName}...`
`configPath`	Explicit path to your `format.config.*` file. Useful if your config is in a non-standard location.

`target`

Description

The output target for the compiled bundle.

Type

"node" | "browser" | "worker"

Default value

"node"

`assets`

Description

Asset mode. See --assets for more information on the available modes.

Type

"static" | "dynamic" | "none"

`assetsOutDir`

Description

Subdirectory within your bundler's output directory where compiled assets.zip output is placed. Useful when you want to keep assets separate from your JS output. Resulting structure: {bundler outDir}/{assetsOutDir?}/{documentName}/assets.zip. This path is not affected by setting bundler asset dirs, like Vite's build.assetsDir.

Type

string

Example

"./assets"

`inlineRemoteCss`

Description

Inline remote CSS at compile time. See --inline-remote-css.

Type

boolean

Default value

false

`validateSchema`

Description

Validate render data against your schema. See --no-validate-schema.

Type

boolean

Default value

true

`bundleName`

Description

A custom name for the compiled bundle and virtual module. Sets the virtual module import to @format:<bundleName>.

Type

string

Default value

"documents"

Example

"my-docs"

`clean`

Description

Whether to clear the Format output directory before recompiling.

Type

boolean

Default value

true

`outDir`

Description

Override the base internal output directory for the compiled Format bundle. See --out-dir. Rarely needs to be changed. Resulting structure: {bundler outDir}/{outDir}/{documentName}...

Type

string

Default value

<rootDir>/_generated

`configPath`

Description

Explicit path to your format.config.* file. Useful if your config is in a non-standard location.

Type

string

The plugin can be configured by passing options.

build.mjs

import esbuild from 'esbuild'
import formatEsbuildPlugin from '@format.dev/compile/esbuild'

await esbuild.build({
	plugins: [formatEsbuildPlugin({ ...options })]
})

Was this page helpful?