TypeScript
Typed fluent builder
Sources, PDF options, metadata, webhooks, results, and errors are represented by exported TypeScript types.
Official Node.js and TypeScript SDK
Generate PDFs in Node.js.
Typed from request to result.
Render HTML, server-side templates, or BladePDF cloud templates with a TypeScript-first SDK built for Node.js applications.
Node.js 22+
TypeScript-first
ESM and CommonJS
Install
npm install @bladepdf/node
invoice.ts
javascript
import { BladePdf } from '@bladepdf/node';
const bladePdf = new BladePdf({
apiKey: process.env.BLADEPDF_API_KEY!,
});
const result = await bladePdf
.fromHtml(html)
.format('A4')
.printBackground()
.render();
await result.save('invoice.pdf');Node.js SDK
A complete server-side PDF API.
Build the render request, resolve local assets, and choose the delivery method through one typed interface.
Modules
ESM and CommonJS
Use the same named exports from modern ESM applications or existing CommonJS services.
Assets
Local asset resolution
Attach referenced stylesheets, images, fonts, JavaScript files, SVGs, and nested CSS dependencies from approved roots.
Delivery
Buffer, stream, or file
Buffer a result, pipe a Node.js Readable, write atomically to disk, or submit a stored background render.
Templates
HTML and cloud templates
Send pre-rendered HTML from any server-side template engine or render a published BladePDF cloud template with context.
Runtime
Server focused
The package targets Node.js 22 and later, uses native platform APIs, and has no runtime dependencies.
Local assets
Render the files referenced by your HTML.
Configure the filesystem roots that belong to the document. The SDK discovers required files, attaches them to the request, and rewrites their document references.
local-assets.ts
javascript
const html = [
'<link rel="stylesheet" href="/build/invoice.css">',
'<img src="/images/logo.svg#mark">',
].join('\n');
const bladePdf = new BladePdf({
apiKey,
assets: {
documentRoot: '/srv/app/public',
searchRoots: [
'/srv/app/public',
'/srv/app/storage',
],
},
});
await bladePdf
.fromHtml(html)
.renderToFile('invoice.pdf');
✓
Nested CSS dependencies
CSS url() values and @import rules are resolved recursively, including fonts and images referenced by imported stylesheets.
✓
Explicit filesystem permissions
Automatic discovery is limited to configured canonical roots, with traversal and symlink escapes rejected.
✓
Request-scoped transfer
Only assets referenced by the document or added explicitly with assetFile() and assetData() are attached.
✓
Stable document references
Query strings and fragments stay in rewritten HTML or CSS references, while multipart asset names remain clean.
JavaScript is attached only when referenced by script src; imports, fetch(), and runtime URLs are not inspected. External SVG files are attached as opaque files and their contents are not traversed.
Delivery
Choose the result shape your application needs.
All delivery methods use the same source, PDF options, asset pipeline, metadata, and cancellation signal.
render()
Buffer result
Receive a RenderResult containing the complete PDF Buffer, request id, and optional stored URL.
renderStream()
Node.js stream
Pipe a one-shot Readable through normal Node.js backpressure-aware stream utilities.
renderToFile()
Atomic file
Stream to a temporary sibling and replace the destination only after the PDF completes successfully.
storePdf().submit()
Background render
Submit a stored asynchronous render and receive its request id and reference.
HTML sources
Bring the rendering workflow you already use.
The SDK accepts HTML strings, so template rendering remains part of your Node.js application.
Raw HTML
Build or load the complete document markup and pass it directly to fromHtml().
Handlebars, EJS, and Pug
Render the template in your application, then pass the resulting HTML string to BladePDF.
React SSR and Nunjucks
Send server-rendered markup with an optional base directory for relative local assets.
Cloud templates
Call fromTemplate() with typed context when the published template lives in BladePDF.
Template engines and web frameworks remain application choices; the SDK does not add direct dependencies on them.
SDK capabilities
Production controls are part of the API.
The Node.js package exposes the controls needed to integrate rendering into services, jobs, and HTTP handlers.
AbortSignal, timeouts, and retries
Cancel delivery with AbortSignal and configure request timeouts and retry behavior for supported transient failures.
Custom fetch and dependency injection
Supply a custom fetch implementation or construct BladePdf from your own RenderClient and AssetResolver.
Request snapshots
Each delivery call captures its own immutable request state, so a builder can be reused safely.
Typed failures and request ids
Handle configuration, asset, write, and transport failures through exported error classes and request metadata.
Documentation
Continue with the Node.js SDK documentation.
The guides cover installation, configuration, API reference, assets, delivery, background renders, and webhook verification.
FAQ
Node.js SDK questions.
Is @bladepdf/node intended for browsers?
No. It is a server-only package for Node.js 22 and later. Keep API keys and filesystem access in server-side code.
Can I use Handlebars, EJS, Pug, React SSR, or Nunjucks?
Yes. Render the template inside your application and pass the resulting HTML to fromHtml(). The SDK deliberately does not depend on a template engine.
Do local assets need public URLs?
No. Configure documentRoot and searchRoots, and the SDK can attach referenced local CSS, images, fonts, JavaScript files, and SVGs to the render request.
Can I stream a PDF directly to an HTTP response?
Yes. renderStream() returns a one-shot Node.js Readable that can be connected with standard stream utilities.
How do background renders work?
Enable storage with storePdf(), configure an optional webhook, and call submit(). The submission contains a request id and reference for correlation.
Render your first PDF from Node.js.
Install the official package, send HTML, and choose a Buffer, stream, file, or background result.
npm install @bladepdf/node