# @maistik/nuxt-pdf
[](https://www.npmjs.com/package/@maistik/nuxt-pdf)
[](https://www.npmjs.com/package/@maistik/nuxt-pdf)
[](./LICENSE)
[](https://nuxt.com)
A powerful Nuxt 3 & 4 module for **server-side PDF generation** using [Handlebars](https://handlebarsjs.com/) templates. Generate beautiful, data-driven PDFs with support for multiple rendering providers (Gotenberg, Browserless, Puppeteer) and built-in internationalization.
Everything runs server-side in Nitro/Node — no PDF code is shipped to the browser.
---
## Table of Contents
- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Project Structure](#project-structure)
- [Configuration Reference](#configuration-reference)
- [Providers](#providers)
- [Internationalization (i18n)](#internationalization-i18n)
- [Built-in Helpers](#built-in-helpers)
- [Custom Helpers](#custom-helpers)
- [Partials](#partials)
- [Automatic Data Enrichment](#automatic-data-enrichment)
- [Composable API — `usePdf()`](#composable-api--usepdf)
- [Server API — `POST /api/pdf`](#server-api--post-apipdf)
- [PDF Options](#pdf-options)
- [Development](#development)
- [Troubleshooting](#troubleshooting)
- [License](#license)
---
## Features
- 🎨 **Handlebars templates** — lightweight templating, no Vue/SSR overhead
- 🌍 **Internationalization** — built-in i18n with the `{{t}}` helper and nested keys
- 🔄 **Provider-agnostic** — Gotenberg, Browserless, or Puppeteer, switchable via config
- 🎯 **SSR-safe** — rendering happens entirely server-side in Nitro/Node
- 🧩 **Composable API** — simple `usePdf()` for `generate()` and `download()`
- 🧮 **Rich helper library** — currency, dates, numbers, math, string and comparison helpers
- 🛠️ **Custom helpers** — define your own helpers in `nuxt.config` (works in production)
- 📐 **Print-aware** — `@page`, page breaks, and `@media print` styling
- 🎪 **Playground** — demo app with Invoice & Sales Report templates in 3 languages
---
## Requirements
| Requirement | Version |
| ----------- | ------- |
| Nuxt | `3.x` or `4.x` |
| Node.js | `18`, `20`, or `22` (CI-tested; `22` recommended) |
| Handlebars | `^4.7` (peer-installed alongside the module) |
A Chromium/Chrome runtime is required **only** for the `puppeteer` provider. The
`gotenberg` and `browserless` providers run the browser remotely.
---
## Installation
```bash
# pnpm
pnpm add @maistik/nuxt-pdf handlebars
# npm
npm install @maistik/nuxt-pdf handlebars
# yarn
yarn add @maistik/nuxt-pdf handlebars
```
> `handlebars` is a peer dependency so your app and the module share a single
> instance. `puppeteer` ships as a dependency and is only loaded at runtime when
> the `puppeteer` provider is selected.
---
## Quick Start
### 1. Register the module
```ts
// nuxt.config.ts
export default defineNuxtConfig({
modules: ['@maistik/nuxt-pdf'],
pdf: {
provider: 'puppeteer', // 'gotenberg' | 'browserless' | 'puppeteer'
components: ['pdf'], // where your .hbs templates live
sharedComponents: ['pdf/partials'], // where your .hbs partials live
enableI18n: true,
defaultLocale: 'en',
availableLocales: ['en', 'es'],
i18nMessages: {
en: { invoice: { title: 'Invoice', total: 'Total' } },
es: { invoice: { title: 'Factura', total: 'Total' } },
},
},
})
```
### 2. Create a template
Create `pdf/Invoice.hbs` in your project root:
```handlebars
{{#each items}}
| {{this.description}} |
{{formatCurrency this.price}} |
{{/each}}
{{t "invoice.total"}}: {{formatCurrency total}}
```
### 3. Generate the PDF
```vue
```
---
## Project Structure
Template directories are resolved relative to your **project root** (not `srcDir`),
so the same layout works for both Nuxt 3 and Nuxt 4 (which moves `srcDir` to `app/`):
```
your-project/
├─ nuxt.config.ts
├─ pdf/ # `components` → templates
│ ├─ Invoice.hbs # referenced as "Invoice"
│ ├─ SalesReport.hbs # referenced as "SalesReport"
│ └─ partials/ # `sharedComponents` → partials
│ ├─ header.hbs # used as {{> header}}
│ └─ footer.hbs # used as {{> footer}}
└─ ...
```
- Templates are discovered **recursively** by their `.hbs` extension.
- A template's **name is its filename without extension** (`Invoice.hbs` → `"Invoice"`).
- Partials are registered under their filename and used with `{{> name}}`.
---
## Configuration Reference
All options live under the `pdf` key in `nuxt.config.ts`.
| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| `provider` | `'gotenberg' \| 'browserless' \| 'puppeteer'` | `'gotenberg'` | Active rendering backend. |
| `components` | `string[]` | `['pdf']` | Directories (relative to project root) scanned for `.hbs` templates. |
| `sharedComponents` | `string[]` | `['pdf/partials']` | Directories scanned for `.hbs` partials. |
| `enableI18n` | `boolean` | `true` | Enables the `{{t}}` helper and locale message lookup. |
| `defaultLocale` | `string` | `'en'` | Locale used when none is passed to `generate()`. |
| `availableLocales` | `string[]` | `['en']` | Locales exposed to the client via `getAvailableLocales()`. |
| `i18nMessages` | `Record>` | `{}` | Nested translation messages keyed by locale. |
| `providers` | `object` | see below | Per-provider connection settings. |
| `defaultOptions` | `PdfOptions` | see below | Default render options merged with per-call options. |
| `customHelpers` | `Record` | `{}` | Extra Handlebars helpers (see [Custom Helpers](#custom-helpers)). |
Default providers and defaultOptions
```ts
providers: {
gotenberg: { url: 'http://localhost:3000' },
browserless: { url: 'https://chrome.browserless.io', apiKey: '' },
puppeteer: {
launchOptions: {
headless: true,
args: ['--no-sandbox', '--disable-setuid-sandbox'],
},
},
},
defaultOptions: {
format: 'A4',
margin: { top: 20, bottom: 20, left: 20, right: 20 }, // millimetres
landscape: false,
printBackground: true,
pageBreak: {
before: ['always'],
after: ['always'],
avoid: ['.no-break'],
},
},
```
> **Margins are expressed in millimetres.** The Gotenberg provider converts them
> to inches automatically.
---
## Providers
Switch backends by changing `provider` and supplying the matching `providers` entry.
### Puppeteer (local / on-prem)
Best for development and single-server deployments. Uses the Chromium bundled with
Puppeteer by default; point it at a system Chrome with `executablePath`.
```ts
pdf: {
provider: 'puppeteer',
providers: {
puppeteer: {
launchOptions: {
headless: true,
args: ['--no-sandbox', '--disable-setuid-sandbox'],
// Optional — defaults to Puppeteer's bundled Chromium:
// executablePath: process.env.CHROME_PATH,
},
},
},
}
```
> `launchOptions` is passed straight to `puppeteer.launch()`. `--no-sandbox` is
> commonly required inside containers, but only disable the sandbox in trusted
> environments.
### Gotenberg (Docker)
Ideal for containerized stacks. Run Gotenberg alongside your app:
```bash
docker run --rm -p 3000:3000 gotenberg/gotenberg:8
```
```ts
pdf: {
provider: 'gotenberg',
providers: {
gotenberg: { url: 'http://gotenberg:3000' },
},
}
```
### Browserless (cloud / self-hosted)
Great for serverless deployments where you don't manage a browser:
```ts
pdf: {
provider: 'browserless',
providers: {
browserless: {
url: 'https://chrome.browserless.io',
apiKey: process.env.BROWSERLESS_API_KEY,
},
},
}
```
| Provider | Where Chrome runs | Best for |
| -------- | ----------------- | -------- |
| `puppeteer` | In-process, local | Dev, on-prem, full control |
| `gotenberg` | Separate container | Docker / Kubernetes |
| `browserless` | Remote service | Serverless / managed |
---
## Internationalization (i18n)
Provide nested messages per locale and look them up with the `{{t}}` helper using
dot-separated keys:
```ts
i18nMessages: {
en: { invoice: { title: 'Invoice', total: 'Total' } },
fr: { invoice: { title: 'Facture', total: 'Total' } },
}
```
```handlebars
{{t "invoice.title"}}
```
- The locale is chosen per call (`generate(..., locale)`), falling back to
`defaultLocale`.
- Missing keys render the **key itself** (e.g. `invoice.unknown`) so gaps are visible.
- The same locale drives `Intl`-based helpers (`formatCurrency`, `formatDate`,
`formatNumber`).
---
## Built-in Helpers
These helpers are always registered, regardless of configuration.
### Internationalization
```handlebars
{{t "invoice.title"}}
```
### Currency
```handlebars
{{formatCurrency 1234.56}}
{{formatCurrency 1234.56 "EUR"}}
{{formatCurrency amount currency="GBP"}}
```
### Dates
```handlebars
{{formatDate date}}
{{formatDate date "full"}}
{{formatDate date format="long"}}
```
### Numbers
```handlebars
{{formatNumber 1234.56}}
{{formatNumber 0.15 style="percent"}}
{{formatNumber n minimumFractionDigits=2}}
```
> `formatNumber` forwards any hash arguments to
> [`Intl.NumberFormat`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat).
### Math
```handlebars
{{add 10 5}}
{{subtract 10 5}}
{{multiply 10 5}}
{{divide 10 5}}
{{percentage 25 100}}
{{lineTotal qty price}}
```
### Strings
```handlebars
{{upper "hello world"}}
{{lower "HELLO WORLD"}}
{{capitalize "hello world"}}
{{truncate "Long text here" 10}}
```
### Comparison
Work both inline (returning a boolean) and as block helpers:
```handlebars
{{#if (eq status "paid")}}Paid{{/if}}
{{#eq a b}}equal{{else}}different{{/eq}}
{{#ne a b}}not equal{{/ne}}
{{#gt total 1000}}High value{{/gt}}
```
---
## Custom Helpers
Define your own Handlebars helpers in `nuxt.config.ts`. They are compiled into a
server-side module at build time, so **they work in development *and* production**:
```ts
pdf: {
customHelpers: {
// Simple value transformation
shout: (value: string) => `${String(value ?? '').toUpperCase()}!`,
// Repeat a string
repeat: (str: string, times: number) => String(str).repeat(times || 1),
// Block helper with conditional logic
ifEquals(this: unknown, a: unknown, b: unknown, options: any) {
return a === b ? options.fn(this) : options.inverse(this)
},
},
}
```
```handlebars
{{shout "hello"}}
{{repeat "★" 5}}
{{#ifEquals status "active"}}Active{{else}}Inactive{{/ifEquals}}
```
> ⚠️ **Custom helpers must be self-contained.** Only each function's *source* is
> serialized into the runtime module — a helper cannot reference variables, imports,
> or values from the surrounding `nuxt.config.ts` scope. Keep all logic inside the
> function body.
---
## Partials
Create reusable fragments in any `sharedComponents` directory:
```handlebars
```
Use them in templates, passing parameters as needed:
```handlebars
{{> header title="My Document" subtitle="Generated Report"}}
```
---
## Automatic Data Enrichment
For convenience, the module derives some fields based on the **template name**:
**Invoice templates** (name contains `invoice`) receive, when `items[]` is present:
- `subtotal` — sum of `quantity × price` across items
- `tax` — `subtotal × (taxRate ?? 0.1)`
- `total` — `subtotal + tax`
- `dueDate` — `issueDate + paymentTerms` days (when both are provided)
**Sales report templates** (name contains `salesreport`) receive, when `salesData[]`
is present:
- `quarters` — quarterly totals derived from each entry's `date`/`amount`
- `rating` — performance rating from total sales (`Excellent` / `Good` / `Average` /
`Needs Improvement`)
> Provide these values yourself if you don't want them computed — your data is
> spread first, then enriched.
---
## Composable API — `usePdf()`
```ts
const {
generate, // (template, data, options?, locale?) => Promise
download, // (template, data, options?, filename?, locale?) => Promise
getAvailableLocales, // () => string[]
getDefaultLocale, // () => string
} = usePdf()
```
| Method | Signature | Notes |
| ------ | --------- | ----- |
| `generate` | `(template, data, options?, locale?) => Promise` | Returns an `application/pdf` `Blob`. |
| `download` | `(template, data, options?, filename?, locale?) => Promise` | Browser-only — creates and clicks a download link. |
| `getAvailableLocales` | `() => string[]` | Reads `availableLocales` from public runtime config. |
| `getDefaultLocale` | `() => string` | Reads `defaultLocale` from public runtime config. |
When no `locale` is passed, `defaultLocale` is used.
---
## Server API — `POST /api/pdf`
The composable calls a server route that you can also hit directly (e.g. from other
services). The module registers it automatically.
**Request**
```http
POST /api/pdf
Content-Type: application/json
```
```json
{
"template": "Invoice",
"ctx": {
"data": { "invoiceNumber": "INV-001", "items": [] },
"options": { "format": "A4" },
"locale": "en"
}
}
```
**Response** — binary `application/pdf` body.
**Status codes**
| Code | Meaning |
| ---- | ------- |
| `200` | PDF generated; body is the PDF bytes. |
| `400` | Missing/invalid `template` or `ctx`. |
| `404` | `template` does not match any discovered `.hbs` file. |
| `500` | Rendering or provider failure (details are logged server-side, not leaked). |
---
## PDF Options
Passed as the `options` argument to `generate()`/`download()` and merged over
`defaultOptions`:
```ts
interface PdfOptions {
format?: 'A4' | 'Letter' | 'Legal'
margin?: {
top?: number // millimetres
bottom?: number
left?: number
right?: number
}
landscape?: boolean
printBackground?: boolean
pageBreak?: {
before?: string[]
after?: string[]
avoid?: string[]
}
}
```
### Print-aware CSS
Templates are plain HTML/CSS, so you can use print rules directly:
```css
@page { size: A4; margin: 20mm; }
.page-break { page-break-before: always; }
@media print {
.no-break { page-break-inside: avoid; }
}
```
---
## Development
This repository uses **pnpm**.
```bash
pnpm install # install dependencies
pnpm dev # run the playground with HMR
pnpm dev:build # build the playground (Nitro)
pnpm build # build the module
pnpm lint # eslint
pnpm test:unit # vitest unit tests
pnpm test:e2e # playwright end-to-end tests
pnpm test # unit + e2e
```
The `playground/` app demonstrates Invoice and Sales Report templates in English,
Spanish, and French, plus a custom helper and provider configuration examples.
---
## Troubleshooting
**Template `"X"` not found (404).** The `template` must match a `.hbs` filename
(without extension) inside one of your `components` directories. Remember the lookup
is by filename, not path.
**Puppeteer can't find Chrome.** Either rely on Puppeteer's bundled Chromium (omit
`executablePath`) or set `CHROME_PATH`/`executablePath` to a valid Chrome binary. In
containers you'll usually need `args: ['--no-sandbox']`.
**Gotenberg/Browserless errors.** Confirm the `url` is reachable from the server and,
for Browserless, that `apiKey` is set.
**My custom helper does nothing.** Ensure it's a function and fully self-contained —
it cannot close over values defined elsewhere in `nuxt.config.ts` (only the function
source is serialized).
---
## License
[MIT](./LICENSE)
---
## Support
- 📖 [Documentation](https://github.com/Maistik-Studio/nuxt-pdf)
- 🐛 [Issue Tracker](https://github.com/Maistik-Studio/nuxt-pdf/issues)
- 💬 [Discussions](https://github.com/Maistik-Studio/nuxt-pdf/discussions)