The repository is platform-first: each platform owns its toolchain, SDK version, changelog, samples, and distribution. Components are implementation/API ownership boundaries inside a platform, not independent releases.
| Platform | Component boundary | Distribution boundary |
|---|---|---|
| Swift | Targets under platforms/swift/Sources/, tests under Tests/ |
Root Package.swift products and ShopifyCheckoutKit.podspec subspecs |
| Android | Gradle feature modules under platforms/android/ |
One fused com.shopify:checkout-kit AAR from shopify-checkout-kit/ |
| React Native | Private workspace packages under platforms/react-native/components/ |
One @shopify/checkout-kit-react-native package with JS and native bindings |
| Web | Private workspace packages under platforms/web/components/ |
One @shopify/checkout-kit package with component subpaths, plus CDN assets |
The folder shapes follow native tooling; they need not be identical to enforce the same ownership rules:
- Components own their feature-specific code, API, and tests.
- Shared internals sit below components and must not import components or public facades. Extract shared code when it has actual consumers, not speculatively.
- Components may depend on another component when that is intentional and acyclic. For example, Swift accelerated checkouts depend on checkout.
- Distribution facades assemble components; components must not import back through those facades.
- JS component/internal packages are private build inputs. Bundle them into the
platform SDK; do not add them to the published runtime dependency graph.
scripts/check-sdk-packages.mjschecks manifest boundaries, and each JS platform's dependency-cruiser configuration checks source dependencies. - Protocol schemas and bindings live under
protocols/universal-commerce-protocol/embedded-checkout-protocol/. Keep wire contracts separate from feature presentation and merchant-facing behavior. platforms/shared/telemetry/holds a cross-platform contract, not a shared implementation. Each platform implements it using its own tooling.
Native/protocol packages have explicit published dependency pins. Adding a component does not change those release boundaries. React Native continues to consume published native SDKs by default; see its local SDK development guide for the narrow unreleased-API workflow.
Web components and shared modules use declared package exports when importing across ownership boundaries. Relative imports stay inside the owning component or module. React Native also requires package exports when accessing shared core; checkout may not depend on accelerated checkout, and other callers use the declared feature entrypoints. These source checks include type-only imports.
Shared telemetry may depend on protocol models, but must not depend on checkout core or components. Checkout owns the integration and depends on telemetry.
Run the checks from the repository root:
pnpm --dir platforms/web lint:dependencies
pnpm --dir platforms/react-native lint:dependenciesBoth commands run dependency-cruiser on the source and then test the real rules against isolated packages containing allowed and forbidden imports. The normal platform lint commands, including CI, run these checks. Web checks runtime reachability separately so a type-only reference cannot make an otherwise unshipped implementation appear reachable.
Native platforms use compiler boundaries. Kotlin internal is scoped to a
Gradle module. Swift internal is scoped to an SPM target, while package allows
intentional sharing such as accelerated checkout's presentation entrypoint.
CocoaPods subspecs combine these sources into one module, so they do not provide
the same implementation isolation as separate SPM targets.
There is no component generator yet. Use the checklists below; a future dev
generator should automate these conventions rather than create a new packaging
model. Paths and commands below are relative to the repository root unless noted.
For every platform:
- Decide the merchant-facing API and implementation ownership before extracting shared infrastructure.
- Add focused tests and demonstrate the component in the platform sample.
- Verify both source behavior and the SDK's built consumer surface. Keep compatibility floors and existing public API unchanged unless the change is intentional and documented.
- Document installation/API usage and update platform support information where relevant. Add a platform changeset for a consumer-visible change; private component changes ship with that platform's SDK version.
- Existing platform CI filters include new component directories automatically.
New jobs or shared cross-platform inputs need explicit routing changes and
tests in
scripts/test/changed_file_filters_test.rband, for macOS job selection,e2e/test/ios_ci_run_plan_test.rb. Do not create per-component workflows merely to mirror the directory tree.
- Add a target under
platforms/swift/Sources/<Module>/and a matching test target underplatforms/swift/Tests/. Keep shared targets underSources/Internal/. - Register targets, dependencies, resources, tests, and any merchant-facing
product in root
Package.swift. Keep compatibility floors explicit. - Wire CocoaPods sources, resources, and dependencies through the appropriate
root
ShopifyCheckoutKit.podspecsubspec. Not every internal target needs a public product/subspec. - Add each merchant-facing module to
MODULESinplatforms/swift/Scripts/api, then rundev swift api dumpand review its baseline underplatforms/swift/api/. - Update the sample's imports/product dependencies as needed. Run
dev swift lint,dev swift test,dev swift build, anddev swift api check. Validate the podspec withBUNDLE_GEMFILE=platforms/swift/Gemfile bundle exec pod lib lint ShopifyCheckoutKit.podspec --allow-warnings.
- Add a sibling feature module under
platforms/android/and include it insettings.gradle. Applyshopify.android-feature; declare a feature-owned namespace and uniqueresourcePrefix, and provideproguard-rules.pro. Useinternal/privatefor implementation declarations. - Add
include project(':<feature>')toshopify-checkout-kit/build.gradle. Do not applymaven-publishto a feature. The umbrella retains artifact coordinates, SDK metadata, and dependency policy;shopify.checkout-kit-publicationowns publication machinery. - The included feature list drives compile dependency metadata, sources and documentation archives, and final AAR class/resource validation. Keep the protocol external; do not bundle a second copy into a feature.
- Run
dev android api dump, review the new feature'sapi/<feature>.api, and commit it. Exclude generatedBuildConfigclasses through rootapiValidation.ignoredClasseswhere appropriate.dev android api checkand CI use the platform aggregate, so siblings are checked automatically. - The sample is a separate Gradle build. Include the feature in its settings and app dependencies when demonstrating it there.
- Run
dev android lint,dev android test, anddev android build. Runplatforms/android/scripts/check_publicationto verify a temporary sibling feature, the normal SDK artifact, and consumers using both Gradle module metadata and Maven POM metadata. This publishes only to a build-local verification repository, not Maven Central.
- Create
platforms/react-native/components/<component>/package.jsonwith a unique package name,private: true, placeholder version0.0.0, and explicit sourceexports. Declare actual component/core/peer dependencies. - Add the private package as a
workspace:*development dependency of the platform root.pnpm-workspace.yamlalready includescomponents/*; runpnpm installfrom the platform directory and commit lockfile changes. - Expose the merchant API through the platform's
src/index.ts. Keep private package imports behind declared exports. Update dependency-cruiser rules to protect the new entrypoint and any intentional component dependencies. - Add native bindings/codegen specs only where required. Keep shared native
transport/contracts in
internal/core; do not put every component's behavior there. Update native registration and codegen configuration as needed. - Add Jest tests, native integration tests where applicable, and a packed-package
consumer example under
test/package-consumer/. The local sample uses source packages; packed-package verification must work without workspace access. - Run
dev rn lint,dev rn test,dev rn build, anddev rn api dump; review/commit the public API report, then rundev rn api check. Review the packed-files snapshot and update it only for intended package-content changes.
- Create
platforms/web/components/<component>/package.jsonwith a unique package name,private: true, placeholder version0.0.0, and explicit API and registration exports. Keep registration insrc/register.tsand list it in the component'ssideEffects. - Add the private package as a
workspace:*development dependency of the platform root.pnpm-workspace.yamlincludescomponents/*; runpnpm installthere and commit lockfile changes. Shared implementation belongs ininternal/with explicit workspace membership when needed. - Re-export public classes/types from platform
src/index.tswithout registering elements. Add a platform registration entry, its public package subpath,sideEffects, Vite entry, and declaration wiring. Use the class'sregister()for registration and@tagnamefor the custom elements manifest. - Wire the CDN loader's supported components/imports and the chunk-URL injection
in
vite.cdn.config.ts. Both currently name checkout explicitly; adding a directory alone does not expose a new CDN component. - Review dependency-cruiser rules, including entrypoint reachability. Add unit, registration, package-consumer, and browser tests as appropriate. Verify that importing one component does not register unrelated elements.
- Run
dev web checkand reviewdev web snapshot compare. Update the snapshot only for intended package-content changes. This platform's check includes lint, unit/browser tests, npm package verification, and the sample build.