@basetime/a2w-template

Standalone React library for rendering Add to Wallet pass templates (Apple Wallet and Google Wallet) in the browser. Extracted from the Add to Wallet monorepo so it can be embedded in other projects without pulling in the rest of the @a2w/frontend or @a2w/shared workspaces.

Installation

This package is published from the Add to Wallet monorepo and re-uses the monorepo's pnpm workspace tooling.

pnpm add @basetime/a2w-template

Peer dependencies (host app must provide):

• react ^18
• react-dom ^18
• @emotion/react ^11
• @emotion/styled ^11
• @emotion/cache ^11

Usage

Render a pass by providing a TemplateSlice to PassContext. No state management is required for read-only rendering; the library falls back to sensible defaults and no-op editing actions when no PassStateContext is mounted.

import { PassContext, PassSwitcher, type TemplateSlice } from '@basetime/a2w-template';

const TemplatePreview = ({ template }: { template: TemplateSlice }) => (
  <PassContext.Provider
    value={{
      template,
      category: null,
      onClick: () => {},
    }}
  >
    <PassSwitcher onClick={() => {}} />
  </PassContext.Provider>
);

To enable in-place editing (changing field values, swapping images, picking barcodes, etc.), wrap the consumer in a PassStateContext.Provider with the current UI / template state and the action methods that should mutate it:

import {
  PassStateContext,
  type PassStateContextValue,
} from '@basetime/a2w-template';

const value: PassStateContextValue = {
  ui: { device: 'phone', os: 'apple', /* ...other UI fields... */ },
  template: { past: [], present: template, future: [] },
  appleUpdate: (pass) => { /* persist to your store */ },
  appleUpdateField: (fieldName, index, data) => { /* ... */ },
  // ...other action methods
};

<PassStateContext.Provider value={value}>
  <TemplatePreview template={template} />
</PassStateContext.Provider>;

Without a provider, PassSwitcher still renders the pass; only editing is unavailable.

Server-Side HTML Rendering

For server runtimes (for example workers or Node SSR), use the server subpath:

import { renderTemplateToHtml } from '@basetime/a2w-template/server';
import type { TemplateSlice } from '@basetime/a2w-template';

const htmlFragment = renderTemplateToHtml(template as TemplateSlice);

renderTemplateToHtml returns an HTML fragment that includes:

• Apple preview (front only)

Public exports

• PassSwitcher - top-level pass renderer that picks Apple or Google based on the active OS in PassStateContext (defaults to apple).
• ApplePass, ApplePassBack, AppleField, ApplePassContainer - Apple rendering primitives.
• GooglePass, GooglePassBack, GooglePassBackControls - Google rendering primitives.
• PassContext, PreviewContext, DeviceContext, OSContext - render-time contexts.
• PassStateContext, usePassState, defaultPassStateContextValue, PassStateContextValue - editing state and action methods.
• TemplateSlice, Device, FieldName, OS and other state types.
• @basetime/a2w-template/server - server-only SSR helpers, including renderTemplateToHtml.

Building

• pnpm build - bundle for the in-monorepo runtime (esbuild ESM).
• pnpm build:npm - bundle for npm distribution.
• pnpm build:types - emit .d.ts files into dist/.
• pnpm watch - rebuild on change.
• pnpm lint - ESLint.
• pnpm test - Jest.

License

UNLICENSED — internal use only until officially published.