Node.js

Generate PDFs from a Node.js server using Format Studio.

Format compiles your documents into a renderer bundle that you import directly in your Node.js server.

Installation

To add Format to an existing codebase or repo, you can use npx format init to automate the setup. This will add your Format config, the npm scripts, the gitignore entries, and the packages. Each step will confirm before editing anything.

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

# Inside your repo directory, run the Format project init script
npx format init --root-dir ./format

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

# Inside your repo directory, run the Format project init script
pnpm dlx format init --root-dir ./format

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

# Inside your repo directory, run the Format project init script
yarn dlx format init --root-dir ./format

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

# Inside your repo directory, run the Format project init script
bun x format init --root-dir ./format

Running the init script will bootstrap your project and make it Format-ready. We use the --root-dir option to separate your Format documents and code from your existing app, but this is fully configurable if you would like to use a different folder structure.

If you'd prefer to add all the initial required files manually, you can follow the manual installation steps.

Developer workflow

Learn how building PDFs fits into your development workflow.

Launch Format Studio

Open Format Studio using the npm script added earlier.

# Either:
npm run dev

# Or this, if npm run dev was taken:
npm run format:dev

# Either:
pnpm run dev

# Or this, if pnpm run dev was taken:
pnpm run format:dev

# Either:
yarn dev

# Or this, if yarn dev was taken:
yarn format:dev

# Either:
bun run dev

# Or this, if bun run dev was taken:
bun run format:dev

You will be prompted to sign in to Format or create an account. Format Studio will then be launched on: http://localhost:1234. You can now start designing and building your PDF templates in format/documents, testing out dynamic data, styles and layouts.

Launch your server

In a new terminal, run your Node.js server. This command will be specific to your existing setup.

# However you start your server. For instance:
npm start

# However you start your server. For instance:
pnpm start

# However you start your server. For instance:
yarn start

# However you start your server. For instance:
bun start

Compile your renderer

When you want to test your PDF via your server-side route, compile your documents.

# Either:
npm run compile

# Or this, if npm run compile was taken:
npm run format:compile

# Either:
pnpm run compile

# Or this, if pnpm run compile was taken:
pnpm run format:compile

# Either:
yarn compile

# Or this, if yarn compile was taken:
yarn format:compile

# Either:
bun run compile

# Or this, if bun run compile was taken:
bun run format:compile

This produces a renderer bundle in format/_generated that you import in your route handlers. The output directory is configurable with the --out-dir flag. You will need to run compile again for your route to render the latest version of your documents.

See the CLI reference for the full list of compile options.

Useful

format compile caches builds and skips recompilation when your documents haven't changed.

Follow the guide below to add a route that generates PDFs from your documents. Hit that route and instantly get a PDF returned.

Example usage (HTTP server)

Below is a simple example of how to use Format with Node.js.

This example creates an HTTP server that generates the invoice PDF and returns an inline PDF to the browser. The browser will display the PDF in the built-in PDF viewer.

src/index.ts

import { createServer } from 'node:http'
import { invoice } from '../format/_generated'
import { FormatClient } from '@format.dev/client'

const server = createServer(async (req, res) => {
	if (req.url === '/invoice') {
		const doc = await invoice.render({ customerName: 'Ada Lovelace' })

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

		res.writeHead(200, {
			'Content-Type': 'application/pdf',
			'Content-Disposition': 'inline; filename="invoice.pdf"'
		})

		const reader = response.body.getReader()

		while (true) {
			const { done, value } = await reader.read()

			if (done) {
				res.end()
				break
			}

			res.write(value)
		}

		return
	}

	res.writeHead(404)
	res.end('Not found')
})

server.listen(3000)

See the Renderer API reference for the full method documentation.

Was this page helpful?