Merge, split and modify PDF documents from server-side Node.js code using the PDFCrowd client. Processing runs on PDFCrowd's servers.
This guide uses SDK 7 or later, supported on Node.js 18 and later. Install the client with npm, or see other installation options.
npm install pdfcrowd
See upgrading to SDK 7 when updating an existing installation.
You can run the examples below with the displayed API credentials. Update the input URLs and filenames as needed.
Examples use ES modules. For CommonJS, replace the import
statements with require() and place awaited operations inside an
async function.
const pdfcrowd = require('pdfcrowd');
The package includes TypeScript declarations. TypeScript infers conversion results and callback parameters from the SDK types. Use a namespace import:
import * as pdfcrowd from 'pdfcrowd';
For TypeScript compiled as CommonJS, you can also use:
import pdfcrowd = require('pdfcrowd');
When compiling a default import to CommonJS, enable esModuleInterop.
If your project needs Node.js types, see TypeScript dependency setup.
Merge a cover, proposal, price list and contact page in that order, then save the PDF locally as offer.pdf:
import pdfcrowd from 'pdfcrowd'; try { const client = new pdfcrowd.PdfToPdfClient("demo", "demo"); client.addPdfFile("cover.pdf"); client.addPdfFile("proposal.pdf"); client.addPdfFile("price.pdf"); client.addPdfFile("contact.pdf"); const filePath = await client.convertToFile("offer.pdf"); console.log("Saved:", filePath); } catch (error) { // Handle the error in your application. console.error(String(error)); }
import pdfcrowd from 'pdfcrowd'; try { const client = new pdfcrowd.PdfToPdfClient("demo", "demo"); client.addPdfFile("cover.pdf"); client.addPdfFile("proposal.pdf"); client.addPdfFile("price.pdf"); client.addPdfFile("contact.pdf"); client.convertToFile("offer.pdf", (error, filePath) => { if (error) { // Handle the error in your application. console.error(error.toString()); return; } console.log("Saved:", filePath); }); } catch (error) { // Handle the error in your application. console.error(String(error)); }
The output file is ready after await completes successfully,
or when the file callback runs without an error.
Handle failures as shown in Handle Errors.
Place the first page of watermark.pdf over every page of proposal.pdf and save the PDF locally as company_offer.pdf:
import pdfcrowd from 'pdfcrowd'; try { const client = new pdfcrowd.PdfToPdfClient("demo", "demo"); client.setPageWatermark("watermark.pdf"); client.addPdfFile("proposal.pdf"); const filePath = await client.convertToFile("company_offer.pdf"); console.log("Saved:", filePath); } catch (error) { // Handle the error in your application. console.error(String(error)); }
import pdfcrowd from 'pdfcrowd'; try { const client = new pdfcrowd.PdfToPdfClient("demo", "demo"); client.setPageWatermark("watermark.pdf"); client.addPdfFile("proposal.pdf"); client.convertToFile("company_offer.pdf", (error, filePath) => { if (error) { // Handle the error in your application. console.error(error.toString()); return; } console.log("Saved:", filePath); }); } catch (error) { // Handle the error in your application. console.error(String(error)); }
Extract page 3 and pages 7 through the end of a PDF, then save them locally as output.pdf:
import pdfcrowd from 'pdfcrowd'; try { const client = new pdfcrowd.PdfToPdfClient("demo", "demo"); client.setAction("extract"); client.setPageRange("3,7-"); client.addPdfFile("13_pages.pdf"); const filePath = await client.convertToFile("output.pdf"); console.log("Saved:", filePath); } catch (error) { // Handle the error in your application. console.error(String(error)); }
import pdfcrowd from 'pdfcrowd'; try { const client = new pdfcrowd.PdfToPdfClient("demo", "demo"); client.setAction("extract"); client.setPageRange("3,7-"); client.addPdfFile("13_pages.pdf"); client.convertToFile("output.pdf", (error, filePath) => { if (error) { // Handle the error in your application. console.error(error.toString()); return; } console.log("Saved:", filePath); }); } catch (error) { // Handle the error in your application. console.error(String(error)); }
Pass your PDFCrowd username and API key to
PdfToPdfClient.
Find your credentials on the API Keys page.
Add each PDF before calling a conversion method. The default action joins the documents in the order they were added.
| Input | Method |
|---|---|
| Local PDF file | addPdfFile() |
| PDF bytes in memory | addPdfRawData() |
For encrypted input PDFs, set the document password with setInputPdfPassword() before conversion.
This is separate from your API key and the passwords used to protect the output PDF.
Read two local PDFs as bytes, merge them in order, and save the result locally as merged.pdf:
import pdfcrowd from 'pdfcrowd'; import fs from 'node:fs'; try { const client = new pdfcrowd.PdfToPdfClient("demo", "demo"); client.addPdfRawData(fs.readFileSync("cover.pdf")); client.addPdfRawData(fs.readFileSync("proposal.pdf")); const filePath = await client.convertToFile("merged.pdf"); console.log("Saved:", filePath); } catch (error) { // Handle the error in your application. console.error(String(error)); }
import pdfcrowd from 'pdfcrowd'; import fs from 'node:fs'; function handleError(error) { // Handle the error in your application. console.error(String(error)); } try { const client = new pdfcrowd.PdfToPdfClient("demo", "demo"); client.addPdfRawData(fs.readFileSync("cover.pdf")); client.addPdfRawData(fs.readFileSync("proposal.pdf")); client.convertToFile( "merged.pdf", (error, filePath) => { if (error) { handleError(error); return; } console.log("Saved:", filePath); } ); } catch (error) { handleError(error); }
Set conversion options on the client before calling a conversion method.
For example, client.setLinearize(true); optimizes the output PDF for progressive loading.
Common settings are listed below. See the method reference for all available options or browse Node.js examples.
| Purpose | Methods |
|---|---|
| Join, interleave, extract or delete pages | setAction(), setPageRange() |
| Watermark and background | setPageWatermark(), setPageBackground(), setMultipageWatermark(), setMultipageBackground() |
| Optimize for progressive loading | setLinearize() |
| Output protection | setEncrypt(), setUserPassword(), setOwnerPassword(), setNoCopy(), setNoPrint() |
| Metadata and attachments | setTitle(), setAuthor(), setUseMetadataFrom(), addAttachment() |
Use "extract" with a page range to keep selected pages, or "delete" to remove them.
The "shuffle" action interleaves pages from the input PDFs.
After adding the inputs and settings, choose how to receive the PDF:
| Output | Async/await | Callbacks |
|---|---|---|
| Local file | convertToFile() |
convertToFile() |
| Buffer in memory | convert() |
convert() supplies a stream; collect its chunks into a Buffer. |
| Readable stream | convertToStream() |
convert() passes the response stream to data(stream). |
For large results, file or stream output avoids collecting the entire result in memory.
When saving a stream, wait for pipeline to finish and handle any error
before using the file. See the
stream examples.
For return values and completion rules, see Promise results and Callbacks in the reference.
This example merges two PDFs, collects the result in a
Buffer,
and saves it locally as merged.pdf:
import pdfcrowd from 'pdfcrowd'; import fs from 'node:fs'; try { const client = new pdfcrowd.PdfToPdfClient("demo", "demo"); client.addPdfFile("cover.pdf"); client.addPdfFile("proposal.pdf"); function saveResult(result) { fs.writeFileSync("merged.pdf", result); } const result = await client.convert(); saveResult(result); } catch (error) { // Handle the error in your application. console.error(String(error)); }
import pdfcrowd from 'pdfcrowd'; import fs from 'node:fs'; function handleError(error) { // Handle the error in your application. console.error(String(error)); } try { const client = new pdfcrowd.PdfToPdfClient("demo", "demo"); client.addPdfFile("cover.pdf"); client.addPdfFile("proposal.pdf"); function saveResult(result) { fs.writeFileSync("merged.pdf", result); } const chunks = []; let failed = false; client.convert({ data: (stream) => stream.on('data', (chunk) => chunks.push(chunk)), error: (message, statusCode) => { failed = true; handleError(new pdfcrowd.Pdfcrowd.Error(message, statusCode)); }, end: () => { if (failed) return; try { saveResult(Buffer.concat(chunks)); } catch (error) { handleError(error); } } }); } catch (error) { handleError(error); }
When serving the result from a web application, use Content-Type: application/pdf.
Use try/catch around awaited conversions. In callback mode, handle errors in
the callback and catch synchronous validation errors from the initial call.
This example merges two PDFs,
logging the HTTP status and reason code when available:
import pdfcrowd from 'pdfcrowd'; try { const client = new pdfcrowd.PdfToPdfClient("demo", "demo"); client.addPdfFile("cover.pdf"); client.addPdfFile("proposal.pdf"); const filePath = await client.convertToFile("merged.pdf"); console.log("Saved:", filePath); } catch (error) { // Handle the error in your application. if (error instanceof pdfcrowd.Pdfcrowd.Error) { console.error("PDFCrowd error:", error.getStatusCode(), error.getReasonCode(), error.getMessage()); } else { console.error(String(error)); } }
import pdfcrowd from 'pdfcrowd'; function handleError(error) { // Handle the error in your application. if (error instanceof pdfcrowd.Pdfcrowd.Error) { console.error("PDFCrowd error:", error.getStatusCode(), error.getReasonCode(), error.getMessage()); } else { console.error(String(error)); } } try { const client = new pdfcrowd.PdfToPdfClient("demo", "demo"); client.addPdfFile("cover.pdf"); client.addPdfFile("proposal.pdf"); client.convertToFile( "merged.pdf", (error, filePath) => { if (error) { handleError(error); return; } console.log("Saved:", filePath); } ); } catch (error) { handleError(error); }
For stream output, handle errors both when obtaining the stream and when consuming it.
A pipeline reports failures while reading the response or writing the destination.
Conversion errors use pdfcrowd.Pdfcrowd.Error. Local file and stream operations
can also produce native errors; check the error type before using SDK-specific methods.
See the error-object reference for status, reason, and message accessors.
The SDK error's toString() includes available status and reason codes.
Use String(error) when logging an error of either type.
| Status | What it means | What to do |
|---|---|---|
400 | Invalid input, settings, or conversion failure | Read the reason code and correct the input or settings. |
401 | Missing credentials or an inactive license | Check your username, API key, and license status. |
403 | Suspended service or no credits remaining | Check your account and available credits. |
413 | Upload exceeds the 300 MB limit | Reduce the upload size. |
429 | Request rate limit reached | Wait and reduce the rate of new requests. |
430 | Concurrent request limit reached | Allow active requests to finish before starting more. |
503 | Temporary network issue | Check your retry policy before submitting another request. |
See all status and reason codes for specific explanations and Limits and Retries for retry behavior.
For job IDs, credit usage, and other conversion details, see the reference.
Request rate and concurrency limits depend on your license. Control how quickly
your application submits conversions and how many it runs at once. A
429 response concerns request rate; a 430 response
concerns requests already in progress. The maximum upload size is 300 MB.
The Node.js client automatically retries a request once when it receives HTTP
502 or 503. Use
setRetryCount()
to change that count, or set it to 0 to disable automatic retries.
Account for these retries when adding an application-level retry policy.
This example merges two PDFs with debug logging enabled and logs the debug log URL when available. Use the input and settings from the conversion you are investigating.
import pdfcrowd from 'pdfcrowd'; try { const client = new pdfcrowd.PdfToPdfClient("demo", "demo"); try { client.addPdfFile("cover.pdf"); client.addPdfFile("proposal.pdf"); client.setDebugLog(true); await client.convertToFile("merged.pdf"); } finally { const debugLogUrl = client.getDebugLogUrl(); if (debugLogUrl) console.info("Debug log:", debugLogUrl); } } catch (error) { // Handle the error in your application. console.error(String(error)); }
import pdfcrowd from 'pdfcrowd'; function handleError(error) { // Handle the error in your application. console.error(String(error)); } try { const client = new pdfcrowd.PdfToPdfClient("demo", "demo"); function finish(error) { if (error) handleError(error); const debugLogUrl = client.getDebugLogUrl(); if (debugLogUrl) console.info("Debug log:", debugLogUrl); } try { client.addPdfFile("cover.pdf"); client.addPdfFile("proposal.pdf"); client.setDebugLog(true); client.convertToFile("merged.pdf", finish); } catch (error) { finish(error); } } catch (error) { handleError(error); }
The debug log contains conversion settings and processing details. You can also find logs in your conversion history. A local or connection failure may occur before a conversion log is available.
| Problem | Check |
|---|---|
| The PDF cannot be read | Check file paths, read permissions and whether each input is a valid PDF. For encrypted inputs, use setInputPdfPassword(). |
| Pages are missing or in the wrong order | Check the order of added PDFs, the selected action and the page range. Use the default join action to append documents, or "shuffle" to interleave their pages. |
| The watermark hides the document | A watermark is placed over the page. Use a transparent watermark or setPageBackground() to place content behind the page. |
For help, contact support and include any available diagnostics, the client version, and enough detail to reproduce the problem.
The methods below were removed in SDK 7. For changes to Promise and callback usage, see the general upgrade notes.
| Removed method | Replacement |
|---|---|
setUserAgent() |
setClientUserAgent().
Use the same user-agent string for SDK requests to the API. |
error.getCode() |
error.getStatusCode()
returns the HTTP status code. |