connect-js

@stripe/connect-js is Stripe’s official loading and initialization wrapper for Connect embedded components. It injects the Connect.js script tag, bootstraps a connected-account session from a publishable key and a client-secret fetcher function, and hands back typed factory methods for creating native HTML custom elements such as account onboarding, payouts, disputes, balances, and tax settings. Platforms drop these elements directly into their own UI so connected sellers, contractors, or merchants can manage their Stripe account without leaving the host application.

The package itself ships almost no business logic — the real Connect.js runtime is fetched at request time from Stripe’s CDN, and this npm package only owns the TypeScript typings, script-injection/dedup logic, and the generic setter-method wiring that turns each custom element into a fully typed, event-driven component. A side-effect-free /pure entry point lets frameworks like Next.js defer script loading until loadConnectAndInitialize is actually called, avoiding SSR warnings.

What You Get

• A TypeScript-typed loadConnectAndInitialize(publishableKey, fetchClientSecret) entry point that bootstraps a connected-account session and returns a StripeConnectInstance
• Typed factory access to 21 prebuilt embeddable components (account-onboarding, payments, payouts, disputes-list, balances, financial-account, issuing-card, tax-registrations, and more) via instance.create(tagName)
• Automatic Connect.js script injection with detection/reuse of an already-loaded script or window.StripeConnect object, avoiding duplicate loads
• A side-effect-free @stripe/connect-js/pure import path for deferring script load in SSR frameworks like Next.js
• update() and logout() instance methods for pushing live configuration changes or tearing down a connected-account session

Common Use Cases

• Embedding a Stripe-hosted onboarding flow inside a marketplace’s own seller dashboard
• Giving connected accounts a self-serve payouts and balances view inside the platform’s own UI
• Building internal support tooling that embeds disputes, payments, and balance components for investigating a connected account
• Safely integrating Connect.js in SSR frameworks (Next.js, Remix) via the /pure deferred-loading entry point

Under The Hood

Architecture The package is a thin, single-purpose facade over Stripe’s externally-hosted Connect.js runtime rather than a self-contained UI library: src/index.ts kicks off a singleton script-load promise and re-exports all public types, src/init.ts owns the loadConnectAndInitialize/initStripeConnect logic and the create/update/logout/debugInstance instance API, and src/utils/scriptUtils.ts isolates the CDN script-injection and existing-script-detection logic. Crucially, the full catalog of 21 embeddable components and their setter methods is centralized as configuration in src/components/componentsAndSetters.ts (a “source of truth” array plus method-config maps), and initStripeConnect’s create() method generically wires setter methods onto each custom element from that config rather than hand-writing 21 separate component wrappers — a config-driven pattern that keeps the actual business logic surface small. The GA and preview component sets are maintained as fully parallel package trees (ga/, preview/), each with its own independent build and versioning, which trades some duplication for release-cadence isolation between stable and in-preview components.

Tech Stack Written in strict TypeScript (ES6 target, noUncheckedIndexedAccess, exactOptionalPropertyTypes, noImplicitAny, and related strict flags all enabled), built with Rollup (rollup-plugin-typescript2, rollup-plugin-babel) into CommonJS and ESM bundles plus .d.ts declarations, and published with zero runtime dependencies — the actual Connect.js code is fetched from connect-js.stripe.com at runtime rather than bundled into the npm package. Testing runs on Jest with jest-environment-jsdom for DOM/custom-element behavior, linting is ESLint with @typescript-eslint plus Prettier, and a GitHub Actions workflow (npm_auto_release.yml) automates npm publishing whenever ga/package.json or preview/package.json’s version field changes on master.

Code Quality Test coverage is comparatively thin for the surface area involved — two test files (index.test.ts, pure.test.ts) covering the script-loading promise chain and the /pure entry point, with no dedicated tests exercising most of the 21 individual embeddable components; most correctness responsibility for component rendering is delegated to the externally-loaded Connect.js runtime rather than tested in this repo. What the codebase does enforce strongly is type safety: strict compiler flags, a required @typescript-eslint/consistent-type-imports rule, and disabled/focused-test lint rules (jest/no-disabled-tests, jest/no-focused-tests) that prevent skipped tests from silently merging. Error handling favors loud, explicit messages (e.g. naming the exact npm package version in runtime errors) over silent fallbacks.

API Design The public surface is intentionally minimal: a single loadConnectAndInitialize({publishableKey, fetchClientSecret}) call handles script injection, session bootstrapping, and instance creation with no manual script tags or custom-element registration required from the integrator. instance.create(tagName) returns a real DOM element that can be appended directly, with setter/getter methods auto-attached and typed via ConnectHTMLElementRecord mapped types, giving IDE autocompletion per component. The /pure escape hatch is a well-documented, low-friction way to opt out of eager script loading for SSR frameworks, and runtime errors are unusually specific (naming the offending method and package version) which shortens integrator debugging time.