@h1dd3nsn1p3r/pdf-invoice

中文文档
1.0.15发布于 2026/02/15MITTypeScriptESM + CJS近 30 天下载 4487

Simple yet powerful node JS library that generates PDF invoice on the fly.

原始使用文档
文档目录17 节
  1. Installation
  2. Use
  3. Payload Data
  4. Company
  5. Invoice
  6. Customer
  7. Items
  8. Fees
  9. QR Code
  10. Note
  11. Generate PDF
  12. Configuration
  13. Strings
  14. Fonts
  15. Types
  16. Changelog:
  17. Contributing

PDF Invoice

📑 Simple yet powerful JavaScript library that generates PDF invoice, estimates & payment receipts from a JSON data. It can be used in any Node JS/Bun JS environment.

Installation

via npm:

npm install @h1dd3nsn1p3r/pdf-invoice

via yarn:

yarn add @h1dd3nsn1p3r/pdf-invoice

via pnpm:

pnpm add @h1dd3nsn1p3r/pdf-invoice

Use

Once installed, you can import either using require or import:

const { PDFInvoice } = require("@h1dd3nsn1p3r/pdf-invoice");

or ES6 import:

import { PDFInvoice } from "@h1dd3nsn1p3r/pdf-invoice";

PDFInvoice is a class that takes the payload as an argument. The payload is the data that you want to show on the invoice. For more information check the Payload data example.

Payload Data

The payload is the data that you want to show on the invoice. It is an object with the following structure:

const payload = {
    company: {
        logo: "<svg>...</svg>", // Optional. SVG logo of your company.
        name: "Festrol Corp.",
        address: "1711 W. El Segundo Blvd, Hawthorne, Canada - 90250",
        phone: "Tel: (+11) 245 543 903",
        email: "Mail: [email protected]",
        website: "Web: https://www.festrolcorp.io",
        taxId: "Tax ID: 1234567890", // Optional.
        bank: "IBAN: 1234567890AC", // Optional.
    },
    customer: {
        name: "John Doe",
        company: "Xero Inc.", // Optional.
        address: "1234 Main Street, New York, NY 10001",
        phone: "Tel: (555) 555-5555",
        email: "Mail: [email protected]",
        taxId: "Tax ID: 1234567890", // Optional.
    },
    invoice: {
        number: 1721, // String or number.
        date: "25/12/2023", // Default is current date.
        dueDate: "25/12/2023", // Default is current date.
        status: "Paid!",
        locale: "es-ES", // BCP 47 language tag. Default is "en-US".
        currency: "EUR", // ISO 4217 currency code. Default is "USD".
        path: "./invoice.pdf", // Required. Path where you would like to generate the PDF file.
        fee: 10, // Amount of fee to be added to the invoice (not percentage)
        orderDiscount: 10, // Amount of order discount (not percentage)
    },
    items: [
        {
            name: "Cloud VPS Server - Starter Plan",
            quantity: 1,
            price: 400,
            discount: 19, // Percentage of discount.
            tax: 0, // Tax percentage. Default is 0.
        },
        {
            name: "Domain Registration - example.com",
            quantity: 1,
            discount: 19, // Percentage of discount.
            price: 20,
            tax: 0, // Tax percentage. Default is 0.
        },
        {
            name: "Maintenance Charge - Yearly",
            quantity: 1,
            discount: 0, // Percentage of discount.
            price: 300,
            tax: 0, // Tax percentage. Default is 0.
        },
    ],
    qr: {
        data: "https://www.festrolcorp.io",
        width: 100, // Default is 50.
    },
    note: {
        text: "Thank you for your business.",
        italic: false, // Default is true.
    },
};

Note: If the string is long, then you can use \n to break the line. For example:

const payload = {
    company: {
        name: "Festrol Corp.",
        address: "1711 W. El Segundo Blvd, Hawthorne, \n Canada - 90250",
        phone: "Tel: (+11) 245 543 903",
        email: "Mail: [email protected]",
    },
};

Let's understand each of the fields in the payload.

Company

This is the information about your company. It is an object with the following structure:

const company = {
    logo: "<svg>...</svg>", // Optional. SVG logo of your company.
    name: "Festrol Corp.", // Optional or required if logo is not supplied.
    address: "1711 W. El Segundo Blvd, Hawthorne, \n Canada - 90250", // Optional.
    phone: "Tel: (+11) 245 543 903", // Optional.
    email: "[email protected]", // Optional.
    website: "Web: https://www.festrolcorp.io" // Optional.
    taxId: "Tax ID: 1234567890", // Optional.
    bank: "IBAN: 1234567890AC", // Optional.
}

For now, only svg logo can be used. If you wish to use logo & do not want the company name, then do not pass the name field. Rest of the fields are optional.

Invoice

This is the information about the invoice. It is an object with the following structure:

const invoice = {
    number: 1721, // Required.
    date: "25/12/2023", // Optional. Default is current date.
    dueDate: "25/12/2023", // Optional. Default is current date.
    status: "Paid!", // Optional. Default is "Due pending!".
    locale: "es-ES", // Optional. Default is "en-US".
    currency: "EUR", // Optional. Default is "USD".
    fees: [
        {
            label: "Delivery Charge",
            amount: 10, // Number (not percentage)
            operation: "+",
        },
        {
            label: "Payment Processing",
            amount: 3.2, // Number (not percentage)
            operation: "-",
        },
    ], // Customer and business fees (Optional)
    orderDiscount: 10, // Optional. Total order discount (not percentage).
};

The invoice number is required. It might be a int that you use to track your invoices. In most cases, it is a unique number that reference the order ID or invoice sequence number in your database. Rest of the fields are optional.

The locale is the BCP 47 language tag. Default is en-US. You can find the list of language tags here. The currency is the ISO 4217 currency code. Default is USD. You can find the list of currency codes here. For more information on locale and currency, refer to Mozilla Int Number documentation.

If path is supplied in the payload, then the PDF will be generated at that location. For example:

const file = "invoice" + "-#" + 1729 + "-" + new Date().getTime(); // invoice-#1729-1630480000000
const location = path.join(__dirname, "/invoices/" + file + ".pdf");
const invoice = {
    path: location, // Required.
};

If path is not supplied in the payload, then the PDF will be generated in current working directory with the name invoice.pdf.

Customer

This is the information about your customer. It is an object with the following structure:

const customer = {
    name: "John Doe", // Required.
    company: "Xero Inc.", // Optional.
    address: "1234 Main Street, New York, \n NY 10001", // Optional.
    phone: "Tel: (555) 555-5555", // Optional.
    email: "[email protected]", // Optional.
    taxId: "Tax ID: 1234567890", // Optional.
};

The name of the customer is required. Rest of the fields are optional.

Items

Items are the products or services that you are selling. It is an array of objects with the following structure:

const items = [
    {
        name: "Cloud VPS Server - Starter Plan", // Required.
        quantity: 1, // Required.
        price: 400, // Required.
        tax: 0, // Optional. Tax percentage. Default is 0.
        discount: 0, // Optional. Item discount percentage. Default is 0.
    },
    {
        name: "Domain Registration - example.com", // Required.
        quantity: 1, // Required.
        price: 20, // Required.
        tax: 0, // Optional. Tax percentage. Default is 0.
        discount: 0, // Optional. Item discount percentage. Default is 0.
    },
    {
        name: "Maintenance Charge - Yearly", // Required.
        quantity: 1, // Required.
        price: 300, // Required.
        tax: 0, // Optional. Tax percentage. Default is 0.
        discount: 0, // Optional. Item discount percentage. Default is 0.
    },
];

The name, quantity and price of the item is required. Rest of the fields are optional. Although if you have single item in the invoice, you need to pass it as an object. For example:

const items = [
    {
        name: "Cloud VPS Server - Starter Plan", // Required.
        quantity: 1, // Required.
        price: 400, // Required.
        tax: 0, // Optional. Tax percentage. Default is 0.
        discount: 0, // Optional. Item discount percentage. Default is 0.
    },
];

Fees

The fee option was initially introduced in version 1.0.12 and was revised in version 1.0.15. Check this discussion #53 for more information.

Fees are optional and are applied to the sub total amount of the invoice. The operation field can be either + or -, depending on whether you want to add or subtract the fee from the sub-total amount. The amount field specifies the fee amount. The label field defines the fee label, which will be displayed on the invoice just below the sub total amount.

QR Code

If you want to add a QR code to the invoice, then you can use this field. It is an object with the following structure:

const qr = {
    data: "https://www.festrolcorp.io/", // Required. The data that you want to encode in the QR code.
    width: "100", // Optional. Default is 50.
};

The data field is required. It is the data that you want to encode in the QR code. The width field is optional. It is the width of the QR code in pixels. Default is 50. The recommended width of QR is 30 - 100.

Note

Use this field if you want to add a note to the invoice. It is an string with the following structure:

const note = "Thank you for your business.";

Generate PDF

Once you have the payload ready, you can generate the PDF using the following code:

const { PDFInvoice } = require("@h1dd3nsn1p3r/pdf-invoice");

const handleInvoice = async (): Promise<void> => {
    const payload = {
        // Prepare payload.
    };

    /**
     * Create the invoice.
     */
    const invoice = new PDFInvoice(payload);
    const pdf = await invoice.create(); // Returns promise, await it.

    console.log(pdf); // Full path to the PDF file.
};

handleInvoice();

Once you call the create method, it will return a promise. You can either use async/await or .then() to handle the promise. The create method will return the path to the PDF file if the PDF is generated successfully. Otherwise, it will throw an error.

Configuration

If required you can change the configuration of the invoice. It is an object with the following structure:

Strings

All the text strings that are used in the invoice can be customized. For example:

const { PDFInvoice } = require("@h1dd3nsn1p3r/pdf-invoice");

const create = async (): Promise<void> => {
    const payload = {
        // ....
    };

    const config = {
        // Custom labels.
        string: {
            invoice: "F A C T U A",
            refNumber: "Referencia",
            date: "Fecha",
            dueDate: "Fecha de vencimiento",
            status: "Estado",
            billTo: "Facturar a",
            item: "Artículo",
            quantity: "Cantidad",
            price: "Precio",
            tax: "Impuesto",
            total: "Total",
            subTotal: "Subtotal",
            grandTotal: "Grand Total", // Added in v1.0.11
        },
    };

    // Create the invoice.
    const invoice = new PDFInvoice(payload, config);
    const pdf = await invoice.create();

    console.log(pdf);
};

Fonts

Following are the fonts that are available build-in with the library:

  • Helvetica
  • Times
  • Courier

All these three fonts includes regular, bold, italic and bold-italic styles. You can use them in the configuration object. For example:

const config = {
    // ....
    style: {
        font: "Helvetica", // "Helvetica", "Times", "Courier"
        fontSize: 10, // Optional. Default is 10.
        lineHeight: 1.8, // Optional. Default is 1.8.
        color: "#000000", // Optional. Default is black.
    },
};

Any font can be used with the font option by passing the fonts TTF files path. For example:

const config = {
    // ....
    font: {
        Noto: {
            normal: path.join(__dirname, "fonts/noto/regular.ttf"),
            italics: path.join(__dirname, "fonts/noto/italic.ttf"),
            bold: path.join(__dirname, "fonts/noto/bold.ttf"),
            bolditalics: path.join(__dirname, "fonts/noto/bold-italic.ttf"),
        },
    },
    style: {
        font: "Noto",
        fontSize: 10, // Optional. Default is 10.
        lineHeight: 1.8, // Optional. Default is 1.8.
        color: "#000000", // Optional. Default is black.
    },
};

If you need additional information do check the example. In the example, I have used "Noto" and the TTF files of Noto font are included in the fonts directory. If you have non-latin characters, then you can use any custom font that supports the characters.

Types

This library is written in TypeScript. If you need to import the types, then you can import them from global.d.ts file. Refer to Global types file for more information.

Example:

import type {
    CompanyInfo,
    CustomerInfo,
    InvoiceInfo,
    ItemInfo,
    QRInfo,
    InvoicePayLoad,
} from "@h1dd3nsn1p3r/pdf-invoice/global.d.ts";

Changelog:

Refer to releases section for more information.

Contributing

Pull requests are welcome, but please open an issue to discuss before making any changes.

版本与发布记录

@h1dd3nsn1p3r/pdf-invoice 共发布 15 个版本,首次发布于 2024/01/03;过去 12 个月发布了 3 个版本。

版本发布日期距今
1.0.15latest2026/02/159 个月前
1.0.142026/01/0910 个月前
1.0.132026/01/0710 个月前
1.0.122025/10/141.1 年前
1.0.102025/03/181.7 年前
1.0.92024/11/112 年前

关于 @h1dd3nsn1p3r/pdf-invoice 的常见问题

@h1dd3nsn1p3r/pdf-invoice 是什么?

Simple yet powerful node JS library that generates PDF invoice on the fly.

如何安装 @h1dd3nsn1p3r/pdf-invoice?

在项目目录运行 npm install @h1dd3nsn1p3r/pdf-invoice,或使用 pnpm add / yarn add / bun add。

@h1dd3nsn1p3r/pdf-invoice 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@h1dd3nsn1p3r/pdf-invoice 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@h1dd3nsn1p3r/pdf-invoice 可以商用吗?

@h1dd3nsn1p3r/pdf-invoice 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@h1dd3nsn1p3r/pdf-invoice 的下载量有多少?

根据 npm 官方下载统计,@h1dd3nsn1p3r/pdf-invoice 在 2026/10/17 – 2026/11/15 这 30 天内被下载 4,487 次,日均约 150 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@h1dd3nsn1p3r/pdf-invoice 还在维护吗?

最新版本 1.0.15 发布于 2026/02/15(9 个月前);至今共发布 15 个版本,其中过去 12 个月发布了 3 个;首次发布于 2024/01/03。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。