npm install @paypal/paypal-js
loadScript() method that will inject the SDK
<script> tag into your page and returns a promise which will resolve after the script loads successfully. Using this utility makes it easier to handle errors and also reload the script when parameters change, such as when updating the currency.
Here’s a basic usage example:
A soon as you type
paypal inside of the
loadScript callback, you’ll begin to see the TypeScript autocompletion. This is supported for both TS and JS files and should look like this:
It shows you all of the possible properties on the PayPal namespace. Using the keyboard arrows or mouse you can navigate around and see more detail about the currently highlighted field.
This kind of code completion is helpful in a lot of situations. Here’s another example:
TypeScript is able to show us all of the options we can pass into
paypal.Buttons() including their return types. Our IDE (VSCode in this case) is showing us that the
createOrder option takes a callback that can take in a
Record (a standard JS object) with a
string as a key and an
unknown value (basically whatever we want to pass in), as well as a
CreateOrderActions object as its second parameter. It will return a
Promise that holds a
string value, which is the order id. It also links directly to the createOrder docs for more information.
If I start filling in the method, but miss any required parts or the return type my IDE will point that out with a red squiggly line.
When I hover over the text it will give me detailed information about the missing arguments. I can also cmd-click on the
createOrder method and it will take me directly to the TypeScript definition, where I can inspect it in more detail.
Opting in to Additional Functionality
While the JS SDK type definitions are fairly comprehensive, the actual supported methods depend on the
<script> tag. By default,
Buttons is included, but none of the other options. That’s why you see the
? on the end of most of the fields. They’re all optional. In order to access
paypal.getFundingSources(), for example, you’ll need to pass
components: "funding-eligibility" as an option into the
loadScript() method. Please see the script configuration guide for more details on selecting which components you need.
Can I use TypeScript Definitions without LoadScript?
loadScript() method isn’t strictly required to enable TypeScript in your application. If you want to avoid bringing that dependency into your app, you can use the
import type syntax instead of
import and you’ll get all of the TypeScript benefits at build-time, without adding to your bundle size. When you
import type from the
paypal-js module, not only will the
loadScript module be typed, the global
window.paypal variable will be include type definitions as well.
In the example above, I imported the
PayPalNamespace type, but you can even import the
loadScript type and it will work just as well without adding any extra code to your JS bundle.
Embracing Types Further
paypal-js module and can be imported individually:
myIntent variable and
postal_code property are mistyped and will show an error similar to the one below:
There are dozens of PayPal related types that can be used in your application. As you start diving into the type definitions you’ll find extensive documentation about each of the properties and their purpose, which can further help you build out your applications.
@paypal/paypal-js module and try it out today.