stripe-pwa-elements: Instructions file for Claude Code

CLAUDE.md - AI Assistant Guide for stripe-pwa-elements

This document provides comprehensive guidance for AI assistants working with the stripe-pwa-elements codebase.

Project Overview

stripe-pwa-elements is a web component library that provides Stripe payment elements for Progressive Web Apps. It uses Stencil.js (version 4.38+) to build framework-agnostic web components that can be used across any web platform.

• Repository: https://github.com/hideokamoto/stripe-pwa-elements
• License: MIT
• Version: 4.0.0
• Main Technology: Stencil.js 4.x (web components framework)
• Primary Dependencies: @stripe/stripe-js ^9.17.0, i18next for internationalization, ionicons

Repository Structure

stripe-pwa-elements/
├── .circleci/                  # CircleCI configuration
│   ├── config.yml             # CI pipeline (lint, type-check, tests, build)
│   └── test-suites.yml        # Test suite definitions for `circleci testsuite run`
├── .github/                    # GitHub configuration (no workflows; CI runs on CircleCI)
│   ├── CODE_OF_CONDUCT.md
│   └── CONTRIBUTING.md         # Contribution guidelines with commit conventions
├── docs/                       # Astro/Starlight documentation site
├── example/                    # Example HTML files demonstrating usage
│   ├── index.html
│   ├── example2.html
│   ├── example3.html          # Payment Element
│   ├── example4.html          # Link Authentication
│   ├── address-example.html   # Address Element
│   └── example-express-checkout.html  # Express Checkout
├── examples/
│   └── codesandbox/           # Vite demo app for CodeSandbox devboxes (card, address, express checkout)
├── plugins/
│   └── stripe-pwa-elements/   # Claude Code plugin (listed in .claude-plugin/marketplace.json)
│       └── skills/stripe-pwa-elements/  # Agent Skill: a single SKILL.md
├── scripts/
│   └── run-stencil-tests.sh   # Test runner invoked by .circleci/test-suites.yml
├── src/                        # Source code
│   ├── components/            # Web components (9 components)
│   │   ├── stripe-address-element/        # Address collection form
│   │   ├── stripe-card-element/           # Card Element component (card number, expiry, CVC)
│   │   ├── stripe-card-element-modal/     # Combined card element with modal
│   │   ├── stripe-currency-selector/      # Currency selector for Adaptive Pricing
│   │   ├── stripe-express-checkout-element/ # Express Checkout (Apple Pay, Google Pay, etc.)
│   │   ├── stripe-link-authentication-element/ # Email + Stripe Link authentication
│   │   ├── stripe-modal/                  # Modal wrapper component
│   │   ├── stripe-payment-element/        # Unified Payment Element
│   │   └── stripe-payment-request-button/ # Payment Request API button (Beta)
│   │       Each component has: *.tsx, *.scss, readme.md (auto-generated), test/
│   ├── services/              # Service layer (dependency injection)
│   │   ├── interfaces.ts      # IStripeService + element manager interfaces
│   │   ├── stripe-service.ts  # StripeServiceClass: Stripe.js init, Elements/Checkout state
│   │   ├── factory.ts         # ServiceFactory: DI wiring, default serviceFactory singleton
│   │   ├── card-element-manager.ts
│   │   ├── payment-element-manager.ts
│   │   ├── address-element-manager.ts
│   │   ├── link-authentication-element-manager.ts
│   │   ├── currency-selector-element-manager.ts
│   │   ├── express-checkout-element-manager.ts
│   │   └── *.spec.ts          # Unit tests for each manager
│   ├── utils/                 # Utility functions
│   │   ├── element-finder.ts  # DOM element lookup helpers
│   │   ├── error.ts           # StripeAPIError and error handling utilities
│   │   ├── i18n.ts            # Internationalization setup (i18next)
│   │   ├── platform.ts        # Platform detection utilities
│   │   ├── test-setup.ts      # Jest test environment setup
│   │   └── utils.ts           # General utilities (checkPlatform, etc.)
│   ├── style/                 # Global styles
│   │   ├── rest.scss          # CSS reset styles
│   │   └── theme.scss         # Theme variables
│   ├── components.d.ts        # Generated TypeScript definitions
│   ├── index.ts               # Entry point
│   ├── index.html             # Development/demo page
│   └── interfaces.ts          # TypeScript interfaces and types
├── stencil.config.ts          # Stencil build configuration
├── stencil.config.unit.ts     # Stencil config for unit tests
├── stencil.config.component.ts # Stencil config for component tests
├── tsconfig.json              # TypeScript configuration
├── eslint.config.js           # ESLint flat config (replaces .eslintrc.json)
├── .prettierrc.json           # Prettier configuration
├── package.json               # Project dependencies and scripts
└── readme.md                  # Project README