Skip to content

AGENTS.md

Latest commit

 

History

History
80 lines (63 loc) · 5.54 KB

AGENTS.md

File metadata and controls

80 lines (63 loc) · 5.54 KB

Agents Guide

Repository Structure

This is a React Native SDK with three platform targets:

  • JS/TS: src/ — TypeScript source, components, hooks, modules
  • Expo plugin: src/plugin/ — Expo config plugin (modifies native projects during expo prebuild)
  • Codegen specs: src/specs/ — React Native codegen specs (native module interfaces)
  • iOS: ios/ — iOS-specific source (Swift, Objective-C)
  • Android: android/src/main/java/com/adyenreactnativesdk/ — Android-specific source (Kotlin)
  • Example app: example/ — includes iOS/Android test targets

Build & Test Commands

Before anything else in a fresh clone, run npm start. This bootstraps the project and installs Husky git hooks (linters + JS tests run on every commit). Skipping this will cause commit hooks to fail. If packages fail to resolve, do not attempt to override the registry (e.g. do not add --registry https://registry.npmjs.org). Inform the user instead — the environment may use a private registry.

  • JS tests: yarn test
  • Typecheck: yarn typecheck
  • Lint: yarn lint
  • iOS build: CI runs via Xcode (see .github/workflows/)
  • Android build: CI runs via Gradle (see .github/workflows/)
  • If swiftformat and ktlint are not installed, inform the user.

Git & GitHub

  • Remote operations: Use gh CLI for all GitHub operations. Before pushing, always set the remote URL to use the current gh CLI token: git remote set-url origin https://x-access-token:$(gh auth token)@github.com/Adyen/adyen-react-native.git
  • Working directory: At the start of every new session, ask the user whether to work in the current directory or a separate worktree. For parallel feature work, use git worktree add.
  • Default branch: develop, not main.
  • Branch hygiene: Start new work from latest origin/develop on a dedicated branch.
  • Staging: NEVER use git add -A or git add . — only stage the specific files relevant to the commit.
  • Commit message format: <type>: <imperative description> — types: feat, fix, chore, refactor, test, docs, deprecate, remove.
  • Ticket number: Always ask the user for the ticket number before creating a PR.
  • PR strategy: Prefer small, focused PRs. If a task involves large changes, suggest splitting into a chain of dependent PRs — each buildable and reviewable on its own.
  • After commit: Push immediately.
  • PR description: Include a short summary of what changed and why, the ticket number, and any testing notes.
  • PR review responses: When addressing review comments, reply to each individual comment with the specific commit hash that fixes it (e.g. "Fixed in commit abc1234 — description of change"). Mark invalid comments as such with an explanation.
  • Comment threads: Before posting a reply to a PR comment thread, check how many distinct users have commented. If more than one user is in the thread (an ongoing conversation), ask the user before replying. Only reply directly if it's a single comment or multiple follow-up comments from the same reviewer.

Refactoring Conventions

  • Before adding or refactoring native modules, events, or class hierarchies, review docs/Architecture.md to understand the existing structure and patterns.
  • Cross-platform consistency: Check for mismatched class names, error codes, and enum values across all three platforms.
  • Before renaming symbols with sed, verify there are no unintended substring matches — e.g. s/Event/PaymentEvent/g will correctly rename EventName but also corrupt coreEvent into corePaymentEvent. Use whole-word matching or targeted per-symbol replacements.
  • After moving a file to a new package/directory, update the package declaration (Kotlin) and update imports in every consumer (Kotlin and JS/TS).
  • When renaming a class, also rename local variables that reference the old name (e.g. submitMap → submitData when SubmitMap → SubmitData).
  • Always update tests: After any rename or restructure, grep for old references in all test targets, not just the main source. Test locations:
    • JS: src/**/__tests__/
    • iOS: example/ios/AdyenExampleTests/
    • Android: android/src/test/java/com/adyenreactnativesdk/

Code Style

TypeScript / JavaScript

  • Declare constants above the functions that use them.
  • Run yarn lint after editing.
  • Never add new npm packages without first checking with the user and providing a list of compelling arguments why the dependency is necessary.

Swift (iOS)

  • Run swiftformat ios after editing.

Kotlin (Android)

  • Run ktlint android -F after editing.

All platforms

  • Match naming conventions of each platform (Swift, Kotlin, TypeScript).
  • Copyright headers: New files must include the Adyen copyright header. Use the current year. Match the format from existing files in the same directory.
  • Never manually edit generated files — edit the source/template and re-run generation.
  • When in doubt: Search for similar patterns in the existing codebase before implementing. Ask questions rather than making assumptions.

Verification Checklist

Before considering work complete:

  1. Tests written/updated and passing (yarn test)
  2. All checks pass (yarn lint, yarn typecheck)
  3. Swift files formatted (swiftformat ios)
  4. Kotlin files formatted (ktlint android -F)
  5. Cross-platform naming verified (JS, iOS, Android aligned)
  6. Old references updated in all three test targets
  7. If public API changed: reviewed for breaking changes and discussed with user