Getting Started

The @pdfsamurai/pdfsamurai-js library lets you generate PDFs from your templates in the browser or on a Node.js server. All processing happens locally — your dynamic data never leaves your infrastructure.

Installation

npm install @pdfsamurai/pdfsamurai-js

Setup

Before using the library, you need an API key and a developer key from your Dashboard. See Integration — Developer keys for how to create one.

Set both keys once with configure():

import { configure } from "@pdfsamurai/pdfsamurai-js";

configure({
  apiKey: "your-api-key",
  developerKey: "your-developer-key",
});

Generate your first PDF

import { configure, generatePdf } from "@pdfsamurai/pdfsamurai-js";

configure({
  apiKey: "your-api-key",
  developerKey: "your-developer-key",
});

const pdf = await generatePdf({
  templateId: "your-template-id",
  dynamicData: {
    customerName: "John Doe",
    orderNumber: "12345",
  },
});

generatePdf returns a Blob in the browser and a Buffer in Node.js. You can use the result to download the file, save it to disk, attach it to an email, or send it as an HTTP response.

Browser example

import { configure, generatePdf } from "@pdfsamurai/pdfsamurai-js";

configure({
  apiKey: "your-api-key",
  developerKey: "your-developer-key",
});

const pdf = await generatePdf({
  templateId: "your-template-id",
  dynamicData: { customerName: "John Doe" },
});

// Download the PDF
const url = URL.createObjectURL(pdf);
const a = document.createElement("a");
a.href = url;
a.download = "document.pdf";
a.click();
URL.revokeObjectURL(url);

Node.js example

import { writeFileSync } from "fs";
import { configure, generatePdf } from "@pdfsamurai/pdfsamurai-js";

configure({
  apiKey: "your-api-key",
  developerKey: "your-developer-key",
});

const pdf = await generatePdf({
  templateId: "your-template-id",
  dynamicData: { customerName: "John Doe" },
});

writeFileSync("document.pdf", pdf);

Authentication

The library requires two credentials:

• API key — authenticates your user account. Can be set globally with configure() or passed per call.
• Developer key — identifies your app or integration. Set once globally with configure().

import { configure, generatePdf } from "@pdfsamurai/pdfsamurai-js";

configure({
  apiKey: "your-api-key",
  developerKey: "your-developer-key",
});

// All subsequent calls use the global keys
const pdf = await generatePdf({
  templateId: "your-template-id",
  dynamicData: { customerName: "John Doe" },
});

You can override the API key on any individual call:

const pdf = await generatePdf({
  templateId: "your-template-id",
  dynamicData: { customerName: "Jane Doe" },
  apiKey: "other-api-key",
});

tip

Store your keys in environment variables instead of hardcoding them:

configure({
  apiKey: process.env.PDFSAMURAI_API_KEY,
  developerKey: process.env.PDFSAMURAI_DEVELOPER_KEY,
});

Error handling

The library throws PdfSamuraiError when something goes wrong. Each error includes a code property to help you identify the issue:

import { generatePdf, PdfSamuraiError } from "@pdfsamurai/pdfsamurai-js";

try {
  const pdf = await generatePdf({
    templateId: "your-template-id",
    apiKey: "your-api-key",
  });
} catch (error) {
  if (error instanceof PdfSamuraiError) {
    console.error(error.code, error.message);
  }
}

See the API Reference for the full list of error codes.

Next steps

• API Reference — all functions, parameters, and error codes
• URL Access Policy — control which URLs templates can fetch when using dynamic images
• Server Usage — considerations for running in Node.js servers