Did you know that PayPal publishes type definitions for our JavaScript SDK? And you don’t even need to be using TypeScript to benefit. They’re included as part of the paypal-js npm package. In this post I’ll cover what the package includes and how to make use of the TypeScript definitions to speed up the development of your PayPal applications whether or not you’re authoring your code in TypeScript.

npm install @paypal/paypal-js

The paypal-js module makes it easy to load the PayPal JavaScript SDK asynchronously. It provides a 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:

TypeScript Hints

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.

The red squiggly line indicates a type mismatch

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.

Inside the PayPal JS SDK type definition file

Opting in to Additional Functionality

While the JS SDK type definitions are fairly comprehensive, the actual supported methods depend on the components query param passed in to your JavaScript SDK <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?

The 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 or 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.

Even the global paypal namespace is typed

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

All of the types we maintain for the PayPal JavaScript SDK are exported directly from the root of the paypal-js module and can be imported individually:

Both the 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.

Conclusion

With type hints available you’ll be much more productive when writing applications with the PayPal JavaScript SDK. You should be able to get more done without leaving your IDE and when you do need to see documentation, in many cases you can find what you need in the type definitions themselves. In other cases a direct link will be made available to the best documentation for a given method. Whether or not you use TypeScript in your app you can benefit from these new type definitions. Install the @paypal/paypal-js module and try it out today.