Installation

The packages are ES modules only, with no CommonJS build. They need a runtime with ES2023: Node.js 22.12 or later, a current Bun or Deno, or a browser through a bundler.

Point the scope at the registry

Until the repository is public, the packages are published to GitHub Packages rather than to the npm registry. Tell your package manager where the @facturometro scope lives, in an .npmrc next to your package.json:

@facturometro:registry=https://npm.pkg.github.com

GitHub Packages needs a token even for reading. Create a personal access token with the read:packages scope and put it in your user-level ~/.npmrc, never in a file you commit:

//npm.pkg.github.com/:_authToken=<your token>

Bun and Deno read the same .npmrc files.

Install

pnpm

pnpm add @facturometro/einvoice

npm

npm install @facturometro/einvoice

yarn

yarn add @facturometro/einvoice

bun

bun add @facturometro/einvoice

deno

deno add npm:@facturometro/einvoice

The packages bring their own type declarations. TypeScript resolves them with moduleResolution set to bundler, node16 or nodenext.

Import

Everything is a named export of the umbrella package:

import { createInvoice, parse, serialize, validate, validateXml } from '@facturometro/einvoice';

The single packages export the same names:

import { createInvoice, Decimal } from '@facturometro/core';
import { parseInvoice } from '@facturometro/parser';
import { serialize } from '@facturometro/serializer';
import { en16931Ruleset, peppolRuleset, validate } from '@facturometro/validator';

The code lists and the runtime schema are subpath exports. Each code list is its own module, so importing the tax categories does not pull the 2162 unit codes into your bundle:

import { isTaxCategoryCode, TAX_CATEGORY_CODES } from '@facturometro/core/codelists/tax-category';
import { toXPath } from '@facturometro/einvoice/schema';

isTaxCategoryCode('S'); // true, and narrows the string to TaxCategoryCode
const codes = TAX_CATEGORY_CODES.length; // 10
const xpath = toXPath(['invoiceLine', 0, 'price', 'priceAmount'], 'Invoice');
// '/ubl:Invoice/cac:InvoiceLine[1]/cac:Price/cbc:PriceAmount'

Runtimes

Runtime	Support
Node.js ≥ 22.12	Supported. CI runs the tests and a smoke test of the packed packages on Node 24.
Bun, Deno	Supported by design (no Node.js APIs in the packages); not tested in CI.
Browsers	Supported by design through a bundler; not tested in CI.

The libraries never touch process, Buffer, the file system or the DOM, and CI builds them for a neutral platform, so any node: import fails the build.