passkit-generator

The library uses an application and model architecture to separate static assets from dynamic data.

• Model: Contains static objects like logos, backgrounds, and icons. You can provide a model via a Folder Model (a directory/template) or a Buffer Model (a set of buffers).
• Application/Runtime: Handles dynamic data such as translations, barcodes, and serialNumber. This data is patched into pass.json or generated at runtime (e.g., manifest.json, signature, and translation files).

This separation allows you to use a pre-defined model as a template, making it efficient to generate many unique passes from a single set of static assets.

The pass.json file defines the identity and structure of the pass. At a minimum, it requires teamIdentifier and passTypeIdentifier.

When creating a pass, you can override or add keys to the pass.json object via the options object in the constructor or PKPass.from() method. You can also use pass.localize(locale, data) to handle translations.

Example pass.json structure:

{
	"formatVersion": 1,
	"passTypeIdentifier": "pass.<bundle id>",
	"teamIdentifier": "<your team identifier>",
	"organizationName": "<your organization name>",
	"description": "A localizable description of your pass.",
	"boardingPass": {}
}

In this Firebase example, the models folder is configured to be deployed alongside the function files (via firebase.json, predeploy, and postdeploy scripts).

Trade-offs to consider:

• Deployment Size: Including models in the function deployment increases upload memory, deployment time, and potentially cold-startup times.
• Alternatives: You may want to consider using a Buffer Model or hosting models on Firebase Storage.
• Firebase Storage Note: If using Firebase Storage, be aware of free bandwidth quotas; exceeding these will result in usage charges.

The self-hosted examples are built using Express.js and use tsx for automatic TypeScript compilation. To run the web server, follow these steps:

1. Install dependencies from the root or the examples directory using pnpm install. This links the passkit-generator package from the parent workspace.
2. Navigate to the examples/self-hosted directory.
3. Execute the following command:

pnpm example

All examples run on 0.0.0.0:8080. You can access them at http://localhost:8080/:example/:modelName, where :example is the endpoint name and :modelName is a name found within the models folder.

To ensure generated passes are openable, you must override the passTypeIdentifier and teamIdentifier so they match your Apple certificates. You can do this using one of two methods:

1. Manual Edit: Edit the pass.json file within the specific model you intend to run.
2. Query String: Pass both passTypeIdentifier and teamIdentifier as query parameters in the URL when querying the example endpoint.

Warning: Omitting this step will result in unopenable passes.

To ensure generated passes are openable, you must override the passTypeIdentifier and teamIdentifier to match your Apple certificates. If these are omitted, the pass will not open.

You can configure these in two ways:

1. Manually: Edit the pass.json file of the specific model you intend to run.
2. Via Query String: Pass both fields as parameters in the URL query string when requesting the example endpoint.

Note on Certificates: The examples point to a certificates folder in the project root which is not provided. You must edit both the certificate paths and the model paths in the examples to point to your local certificate files.

To run the Firebase cloud function emulator on your local machine, use the following command:

pnpm serve

Once running, you will receive a local function URL. You can test the function by sending a POST request to that URL with a JSON body containing the pass parameters.

After installing dependencies, you can start the worker in a local development environment using the provided npm script.

npm install
npm run example

Install the library via npm to start generating Apple Wallet passes in your Node.js application.

$ npm install passkit-generator --save

To deploy your function to Firebase, run:

pnpm deploy

If the deployment fails, the CLI may not provide detailed error messages. Check the functions/firebase-debug.log file for comprehensive error details. If you encounter synchronization errors, wait a moment and try deploying again, as backend resources might still be provisioning.