Webpack

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

The Format Webpack 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 Webpack config:

webpack.config.mjs

import formatWebpackPlugin from '@format.dev/compile/webpack'

export default {
	// ...
	plugins: [
		formatWebpackPlugin()
	]
}

The plugin can be configured by passing options.

webpack.config.mjs

import formatWebpackPlugin from '@format.dev/compile/webpack'

export default {
	// ...
	plugins: [
		formatWebpackPlugin({ ...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/web'

// 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({ apiKey })
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/web'

// 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({ apiKey: env.FORMAT_API_KEY })
		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

targetThe output target for the compiled bundle.

Type

"node" | "browser" | "worker"

Default value

"node"

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

Type

"static" | "dynamic" | "none"

assetsOutDirSpecify a subdirectory for the assets.zip.

Details

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"

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

Type

boolean

Default value

false

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

Type

boolean

Default value

true

bundleNameA 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"

cleanWhether to clear the Format output directory before recompiling.

Type

boolean

Default value

true

outDirOverride 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

configPathExplicit 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.

webpack.config.mjs

import formatWebpackPlugin from '@format.dev/compile/webpack'

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

Was this page helpful?