Templates and the registry

A PDF template is a Vue Single File Component under pdfs/. Nuxt PDF discovers the file and creates one typed entry in the server-only #pdf registry.

Use Pdf* components inside PDF templates. In development, using one in an application component reports an error. Move it under pdfs/, or replace it with an HTML component.

Template discovery

The relative file path becomes the registry key:

Three directories have a different purpose and do not become registry entries:

A project template replaces a same-key template from an extended Nuxt layer. Duplicate keys in the same layer fail during module setup.

One definition per template

Each discovered template calls definePdf() exactly once at the top level of <script setup>. It declares metadata and development preview data:

<script setup lang="ts">
type ReportProps = {
  id: string
  title: string
}

defineProps<ReportProps>()

definePdf<ReportProps>({
  title: props => props.title,
  filename: props => `report-${props.id}.pdf`,
  sampleData: { id: 'sample', title: 'Sample report' },
})
</script>

title and filename can be strings or synchronous functions of the render props. sampleData and named scenarios are removed from production output. They never become a server data source.

The definePdf reference lists every option and its metadata precedence.

Typed rendering

Import the generated registry from server code:

import { pdf } from '#pdf'

export default defineEventHandler(async () => {
  const result = await pdf.report.render({
    id: 'Q2-2026',
    title: 'Quarterly report',
  })

  return result.response()
})

The registry infers the required props from defineProps<ReportProps>(). Load request, database, and API data before render(), then pass the resolved values as props.

Use renderPdf(key, props) when the template key is only known at runtime. The registry reference documents its overloads, result methods, and errors.