Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ import { Client } from 'lago-javascript-client';
✗ const { Client } = require('lago-javascript-client');
The library primarily uses ES Modules. While Node.js has some CJS-ESM interoperability, using `import` is the recommended and type-safe approach.
getLagoError
✓ import { getLagoError } from 'lago-javascript-client';
✗ const { getLagoError } = require('lago-javascript-client');
Used for robust error handling and type extraction from API responses. Follows the ESM import pattern.
Client
✓ import { Client } from 'https://deno.land/x/lago/mod.ts';
For Deno environments, import directly from the Deno Land URL.
This quickstart demonstrates how to initialize the Lago client, configure it for Node.js compatibility (if needed), and perform an asynchronous API call to create a billable metric with proper error handling.
import { Client, getLagoError } from 'lago-javascript-client';
import fetch from 'node-fetch'; // Required for Node.js < 18 or without --experimental-fetch
// Initialize the client with your API key.
// For Node.js < 18, you might need to pass a custom fetch instance.
const lagoClient = Client(process.env.LAGO_API_KEY ?? '', { customFetch: fetch });
async function createBillableMetric() {
const billableMetric = {
billableMetric: {
name: 'api_calls',
code: 'api_calls',
aggregation_type: 'count',
description: 'Number of API calls made.'
}
};
try {
// Example: Creating a new billable metric
const { data } = await lagoClient.billableMetrics.createBillableMetric(billableMetric);
console.log('Successfully created billable metric:', data);
} catch (error) {
// Use getLagoError for structured error handling and type inference
const lagoError = await getLagoError(error);
console.error('Error creating billable metric:', lagoError.message, lagoError.response);
}
}
createBillableMetric();
Debug
Known issues
breakingThe Lago JavaScript Client relies on the Fetch API. Node.js versions prior to 18 do not support Fetch natively. Attempting to use the client without a polyfill or the `--experimental-fetch` flag will result in runtime errors.fixFor Node.js < 18, either start Node.js with `--experimental-fetch` or install and pass `node-fetch` as a custom fetch implementation: `import fetch from 'node-fetch'; const lagoClient = Client('key', { customFetch: fetch });` affects: <1.0.0
gotchaThe package is built with `dnt` to support multiple runtimes (Node.js, Deno, Cloudflare Workers). This means its primary module format is ESM. While some interoperability exists, mixing `require()` with this library can lead to unexpected behavior or require additional configuration.fixAlways use ES Module `import` syntax (`import { Client } from 'lago-javascript-client';`) for consistency and full TypeScript support. affects: >=1.0.0
deprecatedThe previous `lago-nodejs-client` package is deprecated in favor of `lago-javascript-client` which offers TypeScript support and broader runtime compatibility. Users of the old package should migrate.fixUpdate your `package.json` to `lago-javascript-client` and refactor imports and usage according to the new client's API.
affects: <1.0.0 (lago-nodejs-client)
breakingThe underlying Lago API, which this client wraps, has undergone significant changes in how 'groups' are handled, replaced by 'filters', and has made `external_subscription_id` mandatory for events. Several legacy API fields have also been deprecated. These changes will impact how you define and send billing data.fixRefer to the official Lago API documentation (doc.getlago.com) for the specific changes and update your data models and API calls accordingly, especially regarding billable metrics, plans, fees, customer usage, and events. Users were advised to update before July 9, 2024.
affects: N/A (API level)
Errors
Common errors & fixes
ReferenceError: fetch is not defined
Node.js version is older than 18, or the `--experimental-fetch` flag is not used, and no polyfill for `fetch` is provided.
fixUpgrade Node.js to version 18 or higher, or install `node-fetch` and pass it as a `customFetch` option to the `Client` constructor. Alternatively, run Node.js with `node --experimental-fetch your-script.js`.
TypeError: (0 , lago_javascript_client__WEBPACK_IMPORTED_MODULE_0__.Client) is not a function
This error often occurs in environments where CommonJS `require()` is implicitly or explicitly trying to load an ES Module library that primarily uses named exports, or when bundlers mishandle the module type.
fixEnsure you are using ES Module `import { Client } from 'lago-javascript-client';` syntax throughout your project. Verify your `tsconfig.json` (if TypeScript) and bundler configuration (`module` and `moduleResolution`) are set for `ESNext` or `NodeNext` to properly handle ESM. Audit
Dependencies
node-fetchoptionalPolyfill for Fetch API on Node.js versions below 18 or without the `--experimental-fetch` flag enabled.