stripe-js

@stripe/stripe-js is the official loading wrapper that lets you import Stripe.js as an ES module or CommonJS module instead of relying on a hand-written script tag. It exposes a single loadStripe helper that returns a promise resolving to a fully initialized Stripe object, handling script injection, version pinning, and PCI-compliant loading from js.stripe.com for you.

Because Stripe.js must be served directly from Stripe’s domain to stay PCI compliant, this package never bundles the payment library itself — it wraps the global Stripe constructor and ships TypeScript definitions that track the latest Stripe API. That makes it the standard entry point for adding Stripe Elements, Payment Intents, and advanced fraud detection to any modern JavaScript or TypeScript web application.

What You Get

• A promise-based loadStripe(publishableKey) helper that resolves to an initialized Stripe object
• Automatic insertion of the Stripe.js script tag from js.stripe.com, with reuse of any existing tag
• A side-effect-free @stripe/stripe-js/pure entry point for deferred loading and load-parameter control
• Bundled TypeScript definitions that track the latest Stripe API and Elements
• Server-side safety — loadStripe resolves to null when called outside the browser

Common Use Cases

• Mounting Stripe Elements to collect card and payment details in a React, Vue, or vanilla web app
• Confirming Payment Intents and Setup Intents on the client during checkout
• Enabling Stripe’s advanced fraud detection by loading Stripe.js on every page
• Deferring Stripe.js loading until checkout to minimize third-party requests on other pages

Under The Hood

Architecture

The package is a small, single-purpose loader split across three source files in src/. shared.ts holds the core: loadScript guards a module-level stripePromise singleton so Stripe.js is fetched at most once, calling findScript/injectScript to reuse or create a <script src="https://js.stripe.com/..."> tag and wiring load/error listeners that resolve to window.Stripe; initStripe then validates the publishable key, compares the runtime release train, and calls _registerWrapper for telemetry. index.ts is the default entry that eagerly kicks off loadScript on import (after a microtask) so the tag lands early, while pure.ts is the deferred variant that only loads on the first loadStripe call and adds setLoadParameters.

Tech Stack

Written almost entirely in TypeScript (~92%), the package has zero runtime dependencies and is built with Rollup (rollup.config.js) plus Babel to emit both CommonJS (lib/index.js) and ES module (lib/index.mjs) bundles, with @rollup/plugin-replace inlining the package version into _VERSION. Type declarations live under types/ and are copied into the published output. Tooling includes ESLint, Prettier, and @arethetypeswrong/cli for package-export correctness, targeting Node >= 12.16 and TypeScript >= 3.1.

Code Quality

Code quality is high for a library this size. Each source module has a colocated Jest test (index.test.ts, pure.test.ts, shared.test.ts) and the test script chains unit tests, type-snapshot tests, are-the-types-wrong checks, and tsc typechecking. Error handling is explicit and user-facing — clear thrown Error messages for invalid keys and load parameters, a cause-wrapped ‘Failed to load Stripe.js’ rejection, and cache reset on failure so a retry can re-inject the script. Naming is consistent and the public surface is deliberately tiny.

API Design

The developer experience is excellent: the entire public API is essentially loadStripe(publishableKey) returning a typed promise, which removes nearly all boilerplate compared with hand-managing a script tag. The /pure entry point and setLoadParameters give an escape hatch for deferred loading and fraud-signal control without complicating the common path, and isomorphic safety (resolving to null on the server) means the same import works in SSR. Documentation in the README is thorough, with runnable examples and an examples/ directory.