pass-js

@walletpass/pass-js

A Node.js library for generating Apple Wallet passes with localizations, NFC, and web-service push updates. Written in TypeScript.

Installation

npm install @walletpass/pass-js
# or
yarn add @walletpass/pass-js

Get your certificates

To start, you'll need a certificate issued by the iOS Provisioning Portal. You need one certificate per Pass Type ID.

After adding this certificate to your Keychain, export it as a .p12 file (Keychain Access → My Certificates → right-click → Export), then convert it into a .pem file using the passkit-keys command:

./bin/passkit-keys ./pathToKeysFolder

Or directly with openssl:

openssl pkcs12 -in .p12 -clcerts -out com.example.passbook.pem -passin pass:

Then copy the .pem file into your keys directory.

The Apple Worldwide Developer Relations Certification Authority certificate is bundled with this package — you don't need to supply it yourself.

Start with a template

A template carries the fields, images, and localizations shared between your passes. Use it to stamp out individual passes.

Template.load and Template.fromBuffer are intended for trusted template assets. Do not pass attacker-controlled folders, ZIP buffers, or .pkpass bundles to these APIs; loading untrusted bundles can consume excessive memory and may crash or stall the process.

…

The first argument to the Template constructor is the pass style (coupon, eventTicket, etc.); the second is an optional object with any fields you want to set on the template.

You can access template fields directly:

template.passTypeIdentifier = 'pass.com.example.passbook';
template.teamIdentifier = 'MXL';

The following fields are required on every pass:

• passTypeIdentifier — the Apple Pass Type ID (has the pass. prefix)
• teamIdentifier — your Apple Developer team identifier

You can set any documented pass field on a template or pass instance — for example, backgroundColor, foregroundColor, labelColor, logoText, organizationName, suppressStripShine, and webServiceURL.

Load the signing key into the template:

await template.loadCertificate(
  '/etc/passbook/certificate_and_key.pem',
  'secret',
);
// …or set them directly from strings:
template.setCertificate(pemEncodedPassCertificate);
template.setPrivateKey(pemEncodedPrivateKey, optionalKeyPassword);

If you have images common to every pass (logos, icons, background art), add them once on the template:

// Add a single image with a specific density and locale
await template.images.add('icon', iconFilename, '2x', 'ru');
// Or load all images in all densities and locales at once
await template.images.load('./images');

Image input may be a file path or a Buffer. Format is enforced: only PNG is accepted.

For NFC reward-card signup flows, add PassKit personalization metadata and a 150 x 40 point personalization logo:

const template = new Template('storeCard', {
  passTypeIdentifier: 'pass.com.example.passbook',
  teamIdentifier: 'MXL',
});

template.nfc.message = 'member-id';
template.personalization = {
  description: 'Join Acme Rewards',
  requiredPersonalizationFields: [
    'PKPassPersonalizationFieldName',
    'PKPassPersonalizationFieldEmailAddress',
  ],
  termsAndConditions: 'Terms',
};
await template.images.add('personalizationLogo', personalizationLogoPng);

personalization.json and personalizationLogo*.png are emitted only when the final pass has NFC data, personalization metadata, and at least one personalization logo. If any piece is missing, the personalization files are left out of the generated bundle.

If you have a single directory that contains pass.json, the key com.example.passbook.pem, and all the images you need, one call does everything:

const template = await Template.load(
  './path/to/templateFolder',
  'secretKeyPassword',
);

Use the optional third argument to enable allowHttp — useful for development when your webServiceURL points at an HTTP (not HTTPS) server:

const template = await Template.load(
  './path/to/templateFolder',
  'secretKeyPassword',
  { allowHttp: true },
);

Create your pass

To create a new pass from a template:

const pass = template.createPass({
  serialNumber: '123456',
  description: '20% off',
});

Just like a template, you can assign pass fields directly:

pass.serialNumber = '12345';
pass.description = '20% off';

Apple's JSON schema represents structure fields (primary fields, secondary fields, etc.) as arrays whose items must have distinct key properties. To keep that ergonomic, this library exposes a Map-like API with an additional add method that does the logical thing:

pass.primaryFields.add({ key: 'time', label: 'Time', value: '10:00AM' });

Read one or all fields:

const dateField = pass.primaryFields.get('date');
for (const [key, { value }] of pass.primaryFields.entries()) {
  // …
}

Remove one or all fields:

pass.primaryFields.delete('date');
pass.primaryFields.clear();

Adding images to a pass works exactly like adding them to a template (see above).

Working with dates

If your fields contain dates, supply them as ISO 8601 strings with a timezone or as native Date instances:

…

Localizations

This library fully supports both string localization and image localization:

…

Localization applies to each field's label and value. See the Apple docs for details.

Generate the .pkpass file

To generate the pass as a Buffer:

import { writeFile } from 'node:fs/promises';

const buf = await pass.asBuffer();
await writeFile('pathToPass.pkpass', buf);

Or stream the Buffer directly as an HTTP response:

app.use(async (ctx, next) => {
  ctx.status = 200;
  ctx.type = constants.PASS_MIME_TYPE;
  ctx.body = await pass.asBuffer();
});

Troubleshooting with the Console app

If the pass file generates without errors but you can't open it on an iPhone, connect the iPhone to a Mac running macOS 10.14 or later and open the Console application. Select your device on the left, then watch for errors emitted while the system tries to add the pass.

Supply chain safety

• Zero runtime dependencies. @walletpass/pass-js ships with an empty dependencies map in package.json — everything it needs is either in the Node.js standard library or implemented in this repo. Nothing is pulled from npm when you install this package.
• Trusted publishing with provenance. Releases go to npm via npm Trusted Publishing (GitHub OIDC, no long-lived token). Every published tarball carries an npm provenance attestation linking it back to the exact GitHub commit and workflow run that built it — verifiable with npm audit signatures.

Stay in touch

• Author — Konstantin Vyatkin
• Email — tino [at] vtkn.io

License

@walletpass/pass-js is licensed under AGPL-3.0-or-later.