repository·master·Indexed 20 days ago
https://github.com/stripe/stripe-jsA loading utility and wrapper for Stripe.js that allows developers to interact with the Stripe JavaScript SDK using ES modules or CommonJS patterns. It provides the loadStripe function to asynchronously initialize the Stripe object and includes TypeScript declarations. The package is pinned to specific Stripe.js runtime versions (e.g., v9 corresponds to dahlia) and requires loading the script from https://js.stripe.com to remain PCI compliant.
This package provides TypeScript declarations for Stripe.js and supports TypeScript versions >= 3.1.
Important Note on API Types: The type declarations for objects returned by Stripe.js methods will always track the latest version of the Stripe API. If your backend is using an older version of the Stripe API, you may need to update your API version or manually override the type definitions to avoid mismatches.
Each version of the @stripe/stripe-js package is pinned to a specific version of the underlying Stripe.js runtime. Updates to this package primarily affect the loadStripe helper and TypeScript definitions, not the runtime features of Stripe.js itself.
| @stripe/stripe-js | Stripe.js |
|---|---|
| <6 | v3 |
| v6 | acacia |
| v7 | basil |
| v8 | clover |
| v9 | dahlia |
To leverage Stripe's advanced fraud detection, Stripe.js should be loaded on every page of your site, not just the checkout page. You can achieve this using one of two methods:
Import the module in your root file (e.g., index.js or App.js). This causes the Stripe.js script tag to be inserted into the document immediately upon page load.
import '@stripe/stripe-js';Add the Stripe.js script tag directly to the <head> of every page. If a script tag is already present, the loadStripe function will use the existing one instead of inserting a new one.
<!-- Somewhere in your site's <head> -->
<script src="https://js.stripe.com/dahlia/stripe.js" async></script>Install the Stripe.js module using npm to allow importing Stripe.js as a CommonJS or ES module.
Note on PCI Compliance: To remain PCI compliant, you must load Stripe.js directly from https://js.stripe.com. This package does not host the script; it wraps the global Stripe function provided by the Stripe.js script. You cannot bundle the Stripe.js script itself or host it on your own servers.
npm install @stripe/stripe-jsIf you want to defer loading the Stripe.js script until loadStripe is actually called (avoiding the automatic script insertion on import), use the @stripe/stripe-js/pure entry point.
This is useful for code-splitting or when you want explicit control over when the network request for Stripe.js occurs.
// CommonJS module import
const {loadStripe} = require('@stripe/stripe-js/pure');
// ES module import
import {loadStripe} from '@stripe/stripe-js/pure';
// Stripe.js will not be loaded until `loadStripe` is called
const stripe = await loadStripe('pk_test_TYooMQauvdEDq54NiTphI7jx');The loadStripe function returns a Promise that resolves with a newly created Stripe object once Stripe.js has loaded. It accepts the same parameters used when directly initializing a Stripe instance (such as your publishable API key).
If called in a server environment, loadStripe will resolve to null.
If you have a Content Security Policy (CSP) in place, ensure you include https://js.stripe.com in your directives.
import {loadStripe} from '@stripe/stripe-js';
const stripe = await loadStripe('pk_test_TYooMQauvdEDq54NiTphI7jx');To disable advanced fraud detection signals, you must use the @stripe/stripe-js/pure import and call loadStripe.setLoadParameters before calling loadStripe.
// CommonJS module import
const {loadStripe} = require('@stripe/stripe-js/pure');
// ES module import
import {loadStripe} from '@stripe/stripe-js/pure';
loadStripe.setLoadParameters({advancedFraudSignals: false});
const stripe = await loadStripe('pk_test_TYooMQauvdEDq54NiTphI7jx');You can import the pure Stripe.js module using ES module syntax. This entrypoint re-exports all functionality from the underlying pure.mjs distribution file, providing access to loadStripe and other core Stripe functions.
import { loadStripe } from '@stripe/stripe-js';In a CommonJS environment, you can import the Stripe.js library by requiring the package. This entrypoint exports the compiled distribution of the library, providing access to the loadStripe function and other core utilities.
const stripe = require('@stripe/stripe-js');The primary way to use this library is by calling the loadStripe function. This function handles the asynchronous loading of the Stripe.js script and initializes the Stripe instance. It returns a Promise that resolves to a StripeConstructor (the Stripe object) or null.
Because loadStripe manages a singleton promise internally, calling it multiple times will return the same promise, ensuring the script is only loaded once.
import { loadStripe } from '@stripe/stripe-js';
// Use your publishable key here
const stripePromise = loadStripe('pk_test_your_key');
// Use the promise to access the stripe instance
const stripe = await stripePromise;To use the pure version of Stripe.js in a CommonJS environment, you can require the module directly. This entrypoint exports the core Stripe.js functionality from the distributed pure build.
const stripe = require('@stripe/stripe-js');The loadStripe function has an additional method, setLoadParameters, which allows you to configure the parameters used when loadStripe is eventually called.
Important Constraints:
setLoadParameters before calling loadStripe.loadStripe has already been invoked, calling setLoadParameters with new values will throw an error: "You cannot change load parameters after calling loadStripe".setLoadParameters with the exact same values that were previously set, the function will return without error and without updating the state.import { loadStripe } from '@stripe/stripe-js';
// 1. Set parameters before calling loadStripe
loadStripe.setLoadParameters({
// ... LoadParams configuration
});
// 2. Then initialize Stripe
const stripe = await loadStripe('pk_test_...');