Skip to main content

​
Prerequisites

Before installing UBL Builder, ensure you have:
1

Node.js

Node.js version 14 or higher installed
2

Package Manager

npm, yarn, or pnpm available in your project
3

TypeScript (Recommended)

TypeScript 4.0+ for full type safety benefits

​
Package Installation

Install UBL Builder using your preferred package manager: 
npm install ubl-builder

​
Package Details

Once installed, you’ll have access to:
  • Main Export: Invoice class for building UBL 2.1 invoices
  • Type Definitions: Full TypeScript types for all components
  • Aggregate Components: Pre-built UBL components for parties, addresses, taxes, etc.
  • Data Types: UBL Unqualified Data Types (UDT)
The package is distributed as compiled JavaScript with TypeScript declaration files, so it works in both TypeScript and JavaScript projects.

​
Importing the Library

​
TypeScript / ES Modules

import { Invoice } from 'ubl-builder';
import type { InvoiceLineParams, PartyParams } from 'ubl-builder';

​
CommonJS / Node.js

const { Invoice } = require('ubl-builder');

​
Available Exports

The main entry point exports: 
import {
  // Document Types
  Invoice,
  
  // Core Data Types
  CctAmountType,
  CctBinaryObjectType,
  
  // Common Components
  AddressLine,
  Address,
  
  // All UDT Types
  UdtTypes
} from 'ubl-builder';
Most aggregate components are accessed through the Invoice class methods rather than direct imports.

​
TypeScript Configuration

For optimal TypeScript support, ensure your tsconfig.json includes:
tsconfig.json
{
  "compilerOptions": {
    "target": "ES2015",
    "module": "commonjs",
    "lib": ["ES2015"],
    "declaration": true,
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "node",
    "resolveJsonModule": true
  }
}
Enable strict mode to catch potential issues at compile time!

​
Dependencies

UBL Builder includes the following dependencies (automatically installed):
PackageVersionPurpose
@xmldom/xmldom^0.8.10XML DOM implementation
xmlbuilder^15.1.1XML document construction
xpath0.0.29XPath query support
weeknumber^1.1.2Date utilities
These dependencies are bundled with the package. You don’t need to install them separately.

​
Verification

Verify your installation by running a simple test:
test.ts
import { Invoice } from 'ubl-builder';

const invoice = new Invoice('TEST-001', {});
console.log('UBL Builder installed successfully!');
Run the test: 
ts-node test.ts
You should see: UBL Builder installed successfully!

​
Development Setup

If you’re contributing to UBL Builder or want to build from source:
1

Clone the Repository

git clone https://github.com/pipesanta/ubl-builder.git
cd ubl-builder
2

Install Dependencies

npm install
3

Build the Project

npm run build
4

Run Tests

npm test

​
Development Scripts

package.json
{
  "scripts": {
    "build": "tsc",
    "test": "jest --config jestconfig.json",
    "format": "prettier --write \"src/**/*.ts\"",
    "lint": "tslint -p tsconfig.json"
  }
}

​
Troubleshooting

Ensure you’ve installed the package correctly:
npm install ubl-builder --save
Check that node_modules contains the ubl-builder directory.
Make sure your TypeScript version is 4.0 or higher:
npm install typescript@latest --save-dev
Enable esModuleInterop in your tsconfig.json.
The XML dependencies should be installed automatically. If you encounter issues:
npm install @xmldom/xmldom xmlbuilder xpath --save

​
Next Steps

Quickstart Guide

Build your first UBL invoice

API Reference

Explore all available methods and types

Build docs developers (and LLMs) love

Get started for freeTalk to us