Skip to content

Latest commit

 

History

History
125 lines (86 loc) · 4.18 KB

AGENTS.md

File metadata and controls

125 lines (86 loc) · 4.18 KB

AGENTS.md

This file provides guidance to AI agents and contributors working on this Capacitor plugin.

Quick Start

# Install dependencies
bun install

# Build the plugin (TypeScript + Rollup + docgen)
bun run build

# Full verification (iOS, Android, Web)
bun run verify

# Format code (ESLint + Prettier + SwiftLint)
bun run fmt

# Lint without fixing
bun run lint

Development Workflow

  1. Install - bun install (never use npm)
  2. Build - bun run build compiles TypeScript, generates docs, and bundles with Rollup
  3. Verify - bun run verify builds for iOS, Android, and Web. Always run this before submitting work
  4. Format - bun run fmt auto-fixes ESLint, Prettier, and SwiftLint issues
  5. Lint - bun run lint checks code quality without modifying files

Individual Platform Verification

bun run verify:ios
bun run verify:android
bun run verify:web

Example App

If an example-app/ directory exists, you can test the plugin locally:

cd example-app
bun install
bun run start

The example app references the plugin via file:... Use bunx cap sync <platform> to sync native platforms.

Project Structure

  • src/definitions.ts - TypeScript interfaces and types (source of truth for API docs)
  • src/index.ts - Plugin registration
  • src/web.ts - Web implementation
  • ios/Sources/ - iOS native code (Swift)
  • android/src/main/ - Android native code (Java/Kotlin)
  • dist/ - Generated output (do not edit manually)
  • Package.swift - SwiftPM definition
  • *.podspec - CocoaPods spec

iOS Package Management

We always support both CocoaPods and Swift Package Manager (SPM). Every plugin must ship a valid *.podspec and Package.swift. Do not remove or break either integration — users depend on both.

API Documentation

API docs in the README are auto-generated from JSDoc in src/definitions.ts. Never edit the <docgen-index> or <docgen-api> sections in README.md directly. Instead, update src/definitions.ts and run bun run docgen (also runs as part of bun run build).

Versioning

The plugin major version follows the Capacitor major version (e.g., plugin v8 for Capacitor 8). We only ship breaking changes when a new Capacitor native major version is released. All other changes must be backward compatible.

Changelog

CHANGELOG.md is managed automatically by CI/CD. Do not edit it manually.

Pull Request Guidelines

We welcome contributions, including AI-generated pull requests. Every PR must include:

Required Sections

  1. What - What does this PR change?
  2. Why - What is the reason for this change?
  3. How - How did you approach the implementation?
  4. Testing - What did you test? How did you verify it works?
  5. Not Tested - What is not yet tested or needs further validation?

Rules

  • No breaking changes unless aligned with a new Capacitor major release.
  • Run bun run verify and bun run fmt before opening a PR. CI will catch failures, but catching them locally saves time.
  • If you are an AI agent, that is perfectly fine. Just be transparent about it. We care that the code is correct and helpful, not who wrote it.
  • We review PRs on a best-effort basis. We may request changes — you are expected to address them for the PR to be merged.
  • We use automated code review tools (CodeRabbit, and others). You will need to respond to their feedback and resolve any issues they raise.
  • We have automatic releases. Once merged, your change will ship in the next release cycle.

PR Template

## What
- [Brief description of the change]

## Why
- [Motivation for this change]

## How
- [Implementation approach]

## Testing
- [What was tested and how]

## Not Tested
- [What still needs testing, if anything]

Common Pitfalls

  • Always rename Swift/Java classes and package IDs when creating a new plugin from a template — leftover names cause registration conflicts.
  • We only use Java 21 for Android builds.
  • Keep temporary files clean: delete or mark with deleteOnExit after use.
  • dist/ is fully regenerated on every build — never edit generated files.
  • Use Bun for everything. Do not use npm or npx. Use bunx if you need to run a package binary.