Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 27 additions & 7 deletions .ai/specs/SPEC-003-2026-02-10-expo-config-plugin-contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Define a clear contract for plugin inputs and native modifications:

- Plugin entrypoint composes iOS and Android plugin steps.
- iOS step adds merchant identifiers to entitlements when configured.
- Android step toggles Google Pay metadata in main application manifest.
- Android step adds or removes Google Pay metadata in the main application manifest when `enableGooglePay` is set, and leaves it alone otherwise.

## Architecture

Expand All @@ -27,8 +27,8 @@ Source files:

Execution model:

1. Expo prebuild runs plugin with user props.
2. `withGooglePay` mutates Android manifest metadata.
1. Expo prebuild runs plugin with user props. A plugin listed without options gets `undefined`; the entrypoint (`index.ts`) defaults it to `{}`, so `withGooglePay` and `withApplePay` always receive an object.
2. `withGooglePay` mutates Android manifest metadata if `enableGooglePay` is set.
3. `withApplePay` mutates iOS entitlements if merchant IDs provided.
4. Native project files generated by Expo include required capability flags.

Expand All @@ -45,24 +45,27 @@ interface ReactNativePayPluginProps {

Normalized behavior:

- `merchantIdentifier` accepts string or array; internal logic normalizes to array.
- Both props are optional, and so is the options object itself.
- `merchantIdentifier` accepts string or array; `withApplePay` normalizes it once to an array without empty values.
- Duplicate merchant IDs are not re-added.
- `enableGooglePay` defaults to `false`.
- `enableGooglePay` has no default: `true`, `false` and omitted are three different instructions (see the Android contract).

## API Contracts

### iOS Contract (`withApplePay`)

- If `merchantIdentifier` is missing, no entitlement mutation is performed.
- If `merchantIdentifier` is missing or has no non-empty IDs, no entitlement mutation is performed.
- If provided, values are added to `com.apple.developer.in-app-payments`.
- Existing entitlement values are preserved and extended.
- An ID that does not start with `merchant.` adds a prebuild warning (`WarningAggregator.addWarningIOS`) and is still added.

### Android Contract (`withGooglePay`)

- When `enableGooglePay=true`, add metadata:
- name: `com.google.android.gms.wallet.api.enabled`
- value: `true`
- When `enableGooglePay=false`, remove that metadata from main application.
- When `enableGooglePay` is omitted (or `null`), do not touch the manifest, so an entry added by another plugin (Stripe, for example) or by the project stays.

## UI/UX

Expand All @@ -72,6 +75,8 @@ Not applicable (build-time configuration only).

Supported user config examples:

- No options (changes nothing):
- `"@gmisoftware/react-native-pay"`
- Apple Pay only:
- `{ merchantIdentifier: "merchant.com.example.app" }`
- Google Pay only:
Expand All @@ -93,6 +98,10 @@ Expected consumer workflow:
- Rejected to avoid forcing config for apps that do not use Google Pay.
3. **Throw on missing merchant identifier**
- Rejected because Android-only apps should be valid.
4. **Default `enableGooglePay` to `false`**
- Replaced on 2026-10-27: removing the entry whenever the option was omitted deleted entries added by other plugins.
5. **Throw on a merchant identifier without the `merchant.` prefix**
- Rejected in favor of a warning, so a prebuild that worked before keeps working.

## Implementation Approach

Expand All @@ -107,6 +116,12 @@ When changing plugin behavior:

No migration required for initial baseline documentation.

2026-10-27 (`enableGooglePay` no longer defaults to `false`):

- Backward compatibility impact: apps that omitted `enableGooglePay` and relied on the plugin removing `com.google.android.gms.wallet.api.enabled` now keep that entry.
- Required app config updates: set `enableGooglePay: false` to keep removing it. Other configs need no change.
- Prebuild regeneration guidance: run `npx expo prebuild --clean`.

Future plugin contract changes must include:

- Backward compatibility impact
Expand All @@ -121,11 +136,16 @@ Future plugin contract changes must include:

## Open Questions

- Should plugin validate merchant identifier format and warn early?
- Should Google Pay metadata support custom boolean value typing beyond string `"true"`?

## Changelog

### 2026-10-27

- The plugin runs when listed without options: the entrypoint defaults `undefined` props to `{}`. Previously prebuild failed with `Cannot read properties of undefined (reading 'enableGooglePay')`.
- `enableGooglePay` is tri-state. Previous behavior: omitted meant `false` and removed the Google Pay metadata. New behavior: omitted (or `null`) leaves the manifest untouched.
- `withApplePay` warns about merchant IDs without the `merchant.` prefix, which resolves the open question about validating them.

### 2026-02-10

- Initial contract for Expo plugin behavior, inputs, and native mutations.
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,14 @@ All notable changes to this project are documented in this file.

### Fixed

- **Expo plugin: works without options and keeps an existing Google Pay manifest entry.** Listing
`"@gmisoftware/react-native-pay"` without an options object crashed `expo prebuild` with
`Cannot read properties of undefined (reading 'enableGooglePay')`. When `enableGooglePay` was
omitted, the plugin also removed `com.google.android.gms.wallet.api.enabled` from the Android
manifest, even if another plugin, such as Stripe's, had added it. The plugin now adds the entry
when `enableGooglePay` is `true`, removes it when it is `false`, and leaves the manifest alone
when it is omitted. Prebuild also warns when a `merchantIdentifier` does not start with
`merchant.`.
- **iOS: `ApplePayButton` keeps its `PKPaymentButton` across re-renders.** Every prop update
removed the button and created a new one, so an `onPress` with a new identity on each render
rebuilt it on every parent re-render. It is now rebuilt only when `buttonType` or `buttonStyle`
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Install the correct Nitro version first; the payment library depends on it.
## Expo plugin behavior

- **merchantIdentifier** — Optional in the plugin config. If omitted, Apple Pay entitlements are not added (use for Android-only or when you add Apple Pay later).
- **enableGooglePay** — Defaults to **false**. Set to **true** to enable Google Pay on Android.
- **enableGooglePay** — Optional. Set to **true** to enable Google Pay on Android, or **false** to remove the Google Pay manifest entry. If omitted, the plugin leaves the Android manifest as it is.

## Platform support

Expand Down Expand Up @@ -56,7 +56,7 @@ Use `Platform.OS` (or equivalent) to render the correct button and to pass platf
No. The library works in bare React Native too. The Expo plugin only simplifies adding Apple Pay entitlements and Google Pay metadata; in a bare project you configure those in Xcode and Android Studio yourself.

**Can I use only Apple Pay or only Google Pay?**
Yes. Omit `enableGooglePay` (or set false) for iOS-only; omit plugin `merchantIdentifier` for Android-only. In code, only render the button for the platform you support.
Yes. Omit `enableGooglePay` for iOS-only (`false` removes an entry another plugin added); omit plugin `merchantIdentifier` for Android-only. In code, only render the button for the platform you support.

**Which gateways are supported for Google Pay?**
Any gateway that supports the [Google Pay API](https://developers.google.com/pay/api/android) and the gateway token format. Commonly used: Stripe, Braintree, Square, Adyen, Authorize.net, Checkout.com. Set `googlePayMerchantId`, `googlePayGateway`, and `googlePayGatewayMerchantId` accordingly.
Expand Down
6 changes: 4 additions & 2 deletions docs/docs/setup/expo-plugin.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,10 +24,12 @@ Add the plugin to `app.json` or `app.config.js`:

## Options

Both options are optional. Listed without options (`"plugins": ["@gmisoftware/react-native-pay"]`), the plugin changes nothing.

| Option | Type | Description |
|--------|------|-------------|
| `merchantIdentifier` | `string` or `string[]` | Apple Pay Merchant ID(s). If omitted, Apple Pay entitlements are not added. |
| `enableGooglePay` | `boolean` | If `true`, adds the Google Pay metadata to the Android manifest. Default: `false`. |
| `merchantIdentifier` | `string` or `string[]` | Apple Pay Merchant ID(s). If omitted, Apple Pay entitlements are not added. Each ID should start with `merchant.`; prebuild warns when one does not. |
| `enableGooglePay` | `boolean` | `true` adds the Google Pay metadata (`com.google.android.gms.wallet.api.enabled`) to the Android manifest. `false` removes it. If omitted, the manifest is left as it is, so an entry added by another plugin (Stripe, for example) stays. |

## Examples

Expand Down
113 changes: 113 additions & 0 deletions package/src/plugin/__tests__/index.integration.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,113 @@
import {
AndroidConfig,
withPlugins,
type ExportedConfig,
type ExportedConfigWithProps,
} from 'expo/config-plugins'
import withReactNativePay from '../index'
import type { ReactNativePayPluginProps } from '../type'

const GOOGLE_PAY_META_NAME = 'com.google.android.gms.wallet.api.enabled'

function createManifest(
existingValue?: string
): AndroidConfig.Manifest.AndroidManifest {
return {
manifest: {
$: { 'xmlns:android': 'http://schemas.android.com/apk/res/android' },
queries: [],
application: [
{
'$': { 'android:name': '.MainApplication' },
'meta-data': existingValue
? [
{
$: {
'android:name': GOOGLE_PAY_META_NAME,
'android:value': existingValue,
},
},
]
: [],
},
],
},
}
}

// Same entry shapes Expo resolves from app.json: a bare name or [name, props]
function applyPlugin(props?: ReactNativePayPluginProps): ExportedConfig {
const config = {
name: 'app',
slug: 'app',
_internal: { projectRoot: __dirname },
}
return withPlugins(config, [
props === undefined ? withReactNativePay : [withReactNativePay, props],
])
}

async function runManifestMods(
config: ExportedConfig,
manifest: AndroidConfig.Manifest.AndroidManifest
): Promise<AndroidConfig.Manifest.AndroidManifest> {
const mod = config.mods?.android?.manifest
if (!mod) {
return manifest
}
const result = await mod({
...config,
modResults: manifest,
} as ExportedConfigWithProps<AndroidConfig.Manifest.AndroidManifest>)
return result.modResults
}

function googlePayValue(manifest: AndroidConfig.Manifest.AndroidManifest) {
return AndroidConfig.Manifest.getMainApplicationMetaDataValue(
manifest,
GOOGLE_PAY_META_NAME
)
}

describe('withReactNativePay with Expo mods', () => {
it('runs when listed without options and changes nothing', async () => {
const config = applyPlugin()

expect(config.mods?.android?.manifest).toBeUndefined()
expect(config.mods?.ios?.entitlements).toBeUndefined()
expect(config.mods?.ios?.infoPlist).toBeUndefined()
})

it('keeps an existing Google Pay entry when enableGooglePay is omitted', async () => {
const config = applyPlugin({ merchantIdentifier: 'merchant.com.test' })

const manifest = await runManifestMods(config, createManifest('true'))

expect(googlePayValue(manifest)).toBe('true')
})

it('adds the Google Pay entry once when enableGooglePay is true', async () => {
const config = applyPlugin({ enableGooglePay: true })

expect(
googlePayValue(await runManifestMods(config, createManifest()))
).toBe('true')

const manifest = await runManifestMods(config, createManifest('true'))
const metaData =
AndroidConfig.Manifest.getMainApplicationOrThrow(manifest)['meta-data']
expect(
metaData?.filter(
(item) => item.$['android:name'] === GOOGLE_PAY_META_NAME
)
).toHaveLength(1)
})

it('removes the Google Pay entry when enableGooglePay is false', async () => {
const config = applyPlugin({ enableGooglePay: false })

const manifest = await runManifestMods(config, createManifest('true'))

expect(googlePayValue(manifest)).toBeNull()
})
})
12 changes: 12 additions & 0 deletions package/src/plugin/__tests__/index.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -34,4 +34,16 @@ describe('withReactNativePay', () => {
)
expect(result).toEqual({ name: 'my-app', googlePay: true, applePay: true })
})

it('passes empty props when listed without options', () => {
const inputConfig = { name: 'my-app' }

withReactNativePay(inputConfig as any, undefined)

expect(mockWithGooglePay).toHaveBeenCalledWith(inputConfig, {})
expect(mockWithApplePay).toHaveBeenCalledWith(
{ name: 'my-app', googlePay: true },
{}
)
})
})
43 changes: 41 additions & 2 deletions package/src/plugin/__tests__/withApplePay.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,12 @@ const mockWithInfoPlist = jest.fn(
action('modResults' in config ? config : { modResults: config })
)

const mockAddWarningIOS = jest.fn()

jest.mock('expo/config-plugins', () => ({
WarningAggregator: {
addWarningIOS: (...args: any[]) => mockAddWarningIOS(...args),
},
withEntitlementsPlist: (config: any, action: (input: any) => any) =>
mockWithEntitlementsPlist(config, action),
withInfoPlist: (config: any, action: (input: any) => any) =>
Expand Down Expand Up @@ -57,9 +62,13 @@ describe('withApplePay', () => {
})
})

it('does not modify config when merchantIdentifier is missing', () => {
it.each([
['is missing', {}],
['is an empty list', { merchantIdentifier: [] }],
['has only empty IDs', { merchantIdentifier: [''] }],
])('does not modify config when merchantIdentifier %s', (_label, props) => {
const config = { name: 'app' }
const result = withApplePay(config as any, {})
const result = withApplePay(config as any, props)
expect(result).toBe(config)
expect(mockWithEntitlementsPlist).not.toHaveBeenCalled()
expect(mockWithInfoPlist).not.toHaveBeenCalled()
Expand All @@ -80,4 +89,34 @@ describe('withApplePay', () => {
},
})
})

it('warns about merchant identifiers without the merchant. prefix and still adds them', () => {
const result = withApplePay({} as any, {
merchantIdentifier: ['merchant.com.ok', 'com.example.app', ''],
})

expect(mockAddWarningIOS).toHaveBeenCalledTimes(1)
expect(mockAddWarningIOS).toHaveBeenCalledWith(
'@gmisoftware/react-native-pay',
expect.stringContaining('"com.example.app"'),
expect.any(String)
)
expect(result).toEqual({
modResults: {
'com.apple.developer.in-app-payments': [
'merchant.com.ok',
'com.example.app',
],
'ReactNativePayApplePayMerchantIdentifiers': [
'merchant.com.ok',
'com.example.app',
],
},
})
})

it('does not warn about valid merchant identifiers', () => {
withApplePay({} as any, { merchantIdentifier: 'merchant.com.test' })
expect(mockAddWarningIOS).not.toHaveBeenCalled()
})
})
13 changes: 13 additions & 0 deletions package/src/plugin/__tests__/withGooglePay.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -63,4 +63,17 @@ describe('withGooglePay', () => {
expect(result).toEqual({ modResults: { name: 'app' } })
expect(mockAddMetaDataItemToMainApplication).toHaveBeenCalled()
})

it.each([
['enableGooglePay is omitted', {}],
['enableGooglePay is null', { enableGooglePay: null } as any],
])('leaves the manifest alone when %s', (_label, props) => {
const config = { name: 'app' }
const result = withGooglePay(config as any, props)

expect(result).toBe(config)
expect(mockWithAndroidManifest).not.toHaveBeenCalled()
expect(mockAddMetaDataItemToMainApplication).not.toHaveBeenCalled()
expect(mockRemoveMetaDataItemFromMainApplication).not.toHaveBeenCalled()
})
})
8 changes: 5 additions & 3 deletions package/src/plugin/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,15 @@ import type { ReactNativePayPluginProps } from './type'
import { withApplePay } from './withApplePay'
import { withGooglePay } from './withGooglePay'

const withReactNativePay: ConfigPlugin<ReactNativePayPluginProps> = (
const withReactNativePay: ConfigPlugin<ReactNativePayPluginProps | void> = (
config,
props
) => {
config = withGooglePay(config, props)
const options = props ?? {}

config = withApplePay(config, props)
config = withGooglePay(config, options)

config = withApplePay(config, options)

return config
}
Expand Down
9 changes: 9 additions & 0 deletions package/src/plugin/type.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,13 @@
export interface ReactNativePayPluginProps {
/**
* Apple Pay merchant ID(s), each starting with `merchant.`. If omitted, the
* Apple Pay entitlement is not added.
*/
merchantIdentifier?: string | string[]
/**
* `true` adds the Google Pay meta-data to the Android manifest and `false`
* removes it. If omitted, the manifest is left as it is, so an entry added
* by another plugin stays.
*/
enableGooglePay?: boolean
}
Loading
Loading