@stripe/stripe-js
Stripe.js loading utility
About
Stripe.js loading utility
Live mirror of the GitHub README. Updated whenever the repo's default branch changes.
Stripe.js as a CommonJS module or ES module
This package allows Stripe.js to be imported as a CommonJS module or ES module.
Note: To be
PCI compliant,
you must load Stripe.js directly from https://js.stripe.com. You cannot
include it in a bundle or host it yourself. This package wraps the global
Stripe function provided by the Stripe.js script as an ES module.
Calling loadStripe always loads the latest version of Stripe.js, regardless of
which version of @stripe/stripe-js you use. Updates for this package only
impact tooling around the loadStripe helper itself and the TypeScript type
definitions provided for Stripe.js. Updates do not affect runtime availability
of features of Stripe.js.
Minimum requirements
- Node.js: v12.16
- TypeScript: v.3.1.1
Installation
Use npm to install the Stripe.js module:
npm install @stripe/stripe-js
Versioning
Each @stripe/stripe-js version is pinned to a specific
Stripe.js version. The
pinned versions are as follows:
| @stripe/stripe-js | Stripe.js |
|---|---|
| <6 | v3 |
| v6 | acacia |
| v7 | basil |
| v8 | clover |
| v9 | dahlia |
Usage
loadStripe
This function returns a Promise that resolves with a newly created Stripe
object once Stripe.js has loaded. It takes the same parameters passed when
directly
initializing a Stripe instance. If
necessary, it will load Stripe.js for you by inserting the Stripe.js script tag.
If you call loadStripe in a server environment it will resolve to null.
import {loadStripe} from '@stripe/stripe-js';
const stripe = await loadStripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
We’ve placed a random API key in this example. Replace it with your actual publishable API keys to test this code through your Stripe account.
For more information on how to use Stripe.js, please refer to the Stripe.js API reference or learn to accept a payment with Stripe.
If you have deployed a Content Security Policy, make sure to include Stripe.js in your directives.
TypeScript support
This package includes TypeScript declarations for Stripe.js. We support projects using TypeScript versions >= 3.1.
Some methods in Stripe.js accept and return objects from the
Stripe API. The type declarations in
@stripe/stripe-js for these objects in will always track the
latest version of the Stripe API. If
you would like to use these types but are using an older version of the Stripe
API, we recommend
updating to the latest version,
or ignoring and overriding the type definitions as necessary.
Note that we may release new minor and patch versions of
@stripe/stripe-js with small but backwards-incompatible fixes to the type
declarations. These changes will not affect Stripe.js itself.
Ensuring Stripe.js is available everywhere
To best leverage Stripe’s advanced fraud functionality, ensure that Stripe.js is loaded on every page, not just your checkout page. This allows Stripe to detect suspicious behavior that may be indicative of fraud as customers browse your website.
By default, this module will insert a <script> tag that loads Stripe.js from
https://js.stripe.com. This happens as a side effect immediately upon
importing this module. If you utilize code splitting or only include your
JavaScript app on your checkout page, the Stripe.js script will only be
available in parts of your site. To ensure Stripe.js is available everywhere,
you can perform either of the following steps:
Import as a side effect
Import @stripe/stripe-js as a side effect in code that will be included
throughout your site (e.g. your root module). This will make sure the Stripe.js
script tag is inserted immediately upon page load.
import '@stripe/stripe-js';
Manually include the script tag
Manually add the Stripe.js script tag to the <head> of each page on your site.
If an existing script tag is already present, this module will not insert a new
one. When you call loadStripe, it will use the existing script tag.
<!-- Somewhere in your site's <head> -->
<script src="https://js.stripe.com/dahlia/stripe.js" async></script>
Importing loadStripe without side effects
If you would like to use loadStripe in your application, but defer loading the
Stripe.js script until loadStripe is first called, use the alternative
@stripe/stripe-js/pure import module:
// 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');
Disabling advanced fraud detection signals
If you would like to
disable advanced fraud detection
altogether, use loadStripe.setLoadParameters:
// 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');
The loadStripe.setLoadParameters function is only available when importing
loadStripe from @stripe/stripe-js/pure.
Stripe.js Documentation
Contributing
If you would like to contribute to Stripe.js, please make sure to read our contributor guidelines.
Quick facts
npm install @stripe/stripe-jsHow Sourcemap Explorer detects @stripe/stripe-js
We catch @stripe/stripe-js from two complementary signals: bundled source paths and the embedded package.json. Modern bundlers (webpack, Vite, esbuild, Rollup, Turbopack) preserve the original node_modules/@stripe/stripe-js/ paths inside the JavaScript sourcemap's sources[] array — that's the canonical signal. When the matching package.json is also captured in sourcesContent[], we read the exact version field — patch number included. No regex guessing, no version inference.
- 1
Confirm the site exposes sourcemaps
In DevTools Network, check the response headers of any application script for `SourceMap` or `X-SourceMap`. Failing that, fetch the script's last 4 KB and look for a `//# sourceMappingURL=` comment.
- 2
Find the package in the bundle
Open DevTools → Network → reload. Click any application script and look at its sourcemap. Inside, search `sources[]` for entries matching `node_modules/@stripe/stripe-js/` — every match confirms the package is bundled. The matching `sourcesContent[i]` for `node_modules/@stripe/stripe-js/package.json` gives you the exact installed version.
- 3
Read the version directly from package.json
Run `jq -r '. as $m | $m.sources | to_entries[] | select(.value | endswith("node_modules/@stripe/stripe-js/package.json")) | $m.sourcesContent[.key] | fromjson | .version' bundle.js.map`. Sourcemap Explorer automates the same query in the popup.
Recent versions
FAQ
What is @stripe/stripe-js used for?
Stripe.js loading utility
How can I tell if a website is using @stripe/stripe-js?
Open the page in Chrome with the Sourcemap Explorer extension installed and read the Stack tab. We catch `@stripe/stripe-js` from two complementary signals: `node_modules/@stripe/stripe-js/` paths inside the JavaScript sourcemap, and the embedded `package.json` we read for exact-version detection. Without the extension you can do the same lookup manually in DevTools — the steps are listed in the "How Sourcemap Explorer detects" section above.
What is the latest version of @stripe/stripe-js?
9.4.0, as published on the npm registry. The "Recent versions" table on this page lists the most recent 8 releases with their release dates. Sourcemap Explorer reports the version actually bundled into a site, which can lag the latest release by months on real-world deployments.
Where can I read more?
Project homepage: https://stripe.com/docs/js. Source code: https://github.com/stripe/stripe-js. Published on npm: https://www.npmjs.com/package/@stripe/stripe-js. Licensed as MIT.
Keep reading on Sourcemap Explorer
Practical guides
Alternative tools
Detected by Sourcemap Explorer
When a bundle ships sourcemaps, we read the embedded package.json for @stripe/stripe-js and report the precise version. Without sourcemaps, an import / require in the page's scripts is enough to flag it.