Get access and install

Get access to the @igpapi packages, point the @igpapi scope at GitHub Packages, install a platform package and effect, and you are ready for your first program. Requires Node.js >= 22, an IGPAPI_LICENSE_TOKEN environment variable and TypeScript 7 or newer. The iOS package is not the priority direction: it is implemented less exhaustively than the Android one, and the guides and screen pages describe Android.

Get access

A licence gives you three things:

• read access to the @igpapi packages on GitHub Packages for your GitHub account;
• your licence token, IGPAPI_LICENSE_TOKEN, which the packages check when they load;
• support from the author.

To get a licence, or for any question, write to the author: email [email protected], or Telegram @bowzee.

The GitHub account whose token you use below must be the one that was granted access to the packages. A token of any other account is refused by the registry with a 403 or a 404.

Installation

The @igpapi packages live on GitHub Packages, under the @igpapi scope at https://npm.pkg.github.com. Three steps: get a token, point the scope at the registry, install.

1. Get a token

Authenticate the scope with a classic personal access token with the read:packages scope. That is the token the npm registry of GitHub Packages takes (GitHub's own documentation; a fine-grained token is not accepted there). Create one under Settings → Developer settings → Personal access tokens → Tokens (classic), store it as a secret, and let your environment provide NPM_TOKEN. The configs below read the token from the environment, so the token itself is never written to a file.

2. Point the scope at the registry

Put the scope in the file your package manager reads:

• npm reads the project's .npmrc.
• pnpm reads .npmrc too, but it refuses an environment variable in the credentials of a project .npmrc (it ignores the line and the registry answers 401). So the scope goes in the project's .npmrc, and the token line in your user-level ~/.npmrc, where the variable is expanded.
• Yarn 2 and later (Berry) reads .yarnrc.yml and ignores .npmrc entirely. Yarn 4 must be 4.17.0 or newer: before 4.14.1, Node 24.15.0 fails to load the packages out of Plug'n'Play with EBADF: bad file descriptor, and 4.14.1 to 4.16.0 do not know the npmMinimalAgeGate setting of the file below. That setting is there because Yarn 4.10 and later hold back a version published less than a day ago: without it, a fresh release of an @igpapi package, or of the native transport package they pin (@igpapi/transport), is refused as "quarantined" for its first day. It is set for the @igpapi scope only. Yarn 2 and 3 use the second file: Plug'n'Play cannot load the packages there (no Yarn 3 release fixes it), so it sets nodeLinker: node-modules, and they have no release hold.
• Yarn 1 (Classic) is not covered here.

npm, in the project .npmrc:

# .npmrc — npm
@igpapi:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NPM_TOKEN}

pnpm, in the project .npmrc:

# .npmrc — pnpm
@igpapi:registry=https://npm.pkg.github.com

pnpm, and the token line in your user-level ~/.npmrc:

# ~/.npmrc — pnpm
//npm.pkg.github.com/:_authToken=${NPM_TOKEN}

Yarn 4, in .yarnrc.yml:

# .yarnrc.yml — Yarn 4
npmScopes:
  igpapi:
    npmRegistryServer: 'https://npm.pkg.github.com'
    npmAlwaysAuth: true
    npmAuthToken: '${NPM_TOKEN}'
    npmMinimalAgeGate: 0

Yarn 2 and 3, in .yarnrc.yml:

# .yarnrc.yml — Yarn 2 and 3
nodeLinker: node-modules
npmScopes:
  igpapi:
    npmRegistryServer: 'https://npm.pkg.github.com'
    npmAlwaysAuth: true
    npmAuthToken: '${NPM_TOKEN}'

3. Install the platform and effect

The packages declare effect a peer dependency (^4.0.6): the Effect of your project is the one copy the packages use, so a program's tags, errors and layers are the same classes on both sides. Any effect that satisfies ^4.0.6 works; the lines below name the version this release was built with.

Then, with npm, pnpm or Yarn:

# npm
npm install @igpapi/android [email protected]
# or
npm install @igpapi/ios [email protected]

# pnpm
pnpm add @igpapi/android [email protected]
# or
pnpm add @igpapi/ios [email protected]

# Yarn
yarn add @igpapi/android [email protected]
# or
yarn add @igpapi/ios [email protected]

@igpapi/android installs @igpapi/core, the native transport package @igpapi/transport and the media codecs with it. The @igpapi/transport package is the native transport the platform packages depend on; you never install or import it, and you never import @igpapi/core either: @igpapi/android re-exports the names a program needs.

Your project

The packages are ESM-only, and every example in this guide uses import and top-level await. Set the project up for that:

• package.json has "type": "module".
• tsconfig.json uses TypeScript 7 or newer with "module": "nodenext" and "moduleResolution": "nodenext".
• Run a .ts file with npx tsx main.ts, or compile it with tsc and run the result with node.

Set IGPAPI_LICENSE_TOKEN

Put the licence token in the environment of the process that runs your program:

export IGPAPI_LICENSE_TOKEN='your licence token'

Without it the package refuses to start and says Please, provide license token as IGPAPI_LICENSE_TOKEN environment variable.

Check your install

Save this as check.ts and run it:

import { AndroidIgpapi } from '@igpapi/android';

// Prints "function" when the package loads and the licence token is accepted.
console.log(typeof AndroidIgpapi.install);

It prints function. If it prints the licence-token message instead, set IGPAPI_LICENSE_TOKEN; if the install failed with a 403 or a 404, the token or the account has no access (see Get access).

Next

• Your first program
• How the Simulator works