Installation

Source Repository: convertcom/javascript-sdk | Wiki | npm

Install via npm or Yarn

npm install --save @convertcom/js-sdk

Or:

yarn add @convertcom/js-sdk

Bundle Formats

The package provides entry points in multiple formats:

CDN (unpkg)

You can also load the SDK via unpkg (evaluation purposes only):

<script src="https://unpkg.com/@convertcom/js-sdk/lib/index.js"></script>

<!-- or minified -->
<script src="https://unpkg.com/@convertcom/js-sdk/lib/index.min.js"></script>

Importing the SDK

ES6

For modern frontend frameworks (React, Vue, Angular). Must be transpiled for browsers.

import ConvertSDK from '@convertcom/js-sdk';

If your bundler resolves the CommonJS entry point rather than the ES module one, this default import is a namespace object and the constructor sits on .default — see Which shape the default import has below for the form that covers both.

ESM

For ES Module packages ("type": "module" in package.json). Must be transpiled for browsers.

import ConvertSDKModule from '@convertcom/js-sdk';
const ConvertSDK = (ConvertSDKModule as any).default ?? ConvertSDKModule;

CommonJS

For Node.js environments. Must be transpiled for browsers.

const {default: ConvertSDK} = require('@convertcom/js-sdk');

UMD

Works directly in browsers.

<script src="https://unpkg.com/@convertcom/js-sdk/lib/index.umd.min.js"></script>

const {default: ConvertSDK} = window.ConvertSDK;

Which shape the default import has

The ?? ConvertSDKModule fallback above is not defensive padding. ConvertSDK is the package's export default, but the package ships every bundle format from the table above and has no exports map, so which entry point your toolchain resolves decides what the default import is:

• CommonJS (main → lib/index.js) — built with named exports, so the constructor is on .default. This is the shape require('@convertcom/js-sdk').default returns, and the one Node's own loader gets when it resolves the package by main.
• ES modules (module → lib/index.mjs) — the export default survives as a real default export, so the default import is the constructor and .default is undefined.
• UMD (browser → lib/index.umd.min.js) — named exports again, hence window.ConvertSDK.default.

Frontend bundlers that honor module — Vite, and the frameworks built on it — land on the second case, so a .default extraction there yields undefined. A server-rendering framework can hit both cases from a single source file, because it builds that file once for the browser and once for Node. Writing .default ?? Module covers every case and is what this repository's own framework examples do.

Next Steps

• Initialization -- configure and start the SDK
• Quickstart -- full working example