Rollup

Use the Format Rollup plugin to compile your documents as part of your Rollup or Rolldown build.

The Format Rollup plugin compiles your documents and makes them available via the @format:documents virtual module. The same plugin works for both Rollup and Rolldown.

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 Rollup config:

rollup.config.mjs

import formatRollupPlugin from '@format.dev/compile/rollup'

export default {
	input: 'src/index.js',
	output: { dir: 'dist', format: 'esm' },
	plugins: [
		formatRollupPlugin()
	]
}

rolldown.config.mjs

import formatRolldownPlugin from '@format.dev/compile/rollup'

export default {
	input: 'src/index.js',
	output: { dir: 'dist', format: 'esm' },
	plugins: [
		formatRolldownPlugin()
	]
}

The plugin can be configured by passing options.

rollup.config.mjs

import formatRollupPlugin from '@format.dev/compile/rollup'

export default {
	input: 'src/index.js',
	output: { dir: 'dist', format: 'esm' },
	plugins: [
		formatRollupPlugin({ ... 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.

rollup.config.mjs

import formatRollupPlugin from '@format.dev/compile/rollup'

export default {
	plugins: [formatRollupPlugin({ ...options })]
}

Was this page helpful?