TypeScript Troubleshooting

PSPDFKit for Web ships with a TypeScript declaration file for first-level support of TypeScript projects.

Ideally, when compiling your TypeScript project, everything should work without issues. However, in some cases you might observe errors pointing to PSPDFKit, such as the following error that occurs during compilation time (i.e. when tsc runs):

ERROR in node_modules/pspdfkit/dist/index.d.ts:4906:31 - error TS1005: ',' expected.

4906 declare type InsetJSON = [left: number, top: number, right: number, bottom: number];
                                   ~

ℹ️ Note: The error shown above might look different for you; it’s merely a reference to the general output thrown by TypeScript that might appear when integrating PSPDFKit for Web into your project.

This happens because our TypeScript declaration file relies on a newer version of TypeScript than the one you’re currently using.

Please try one of the approaches outlined below to solve this specific issue.

Upgrading Your TypeScript Version

If possible for your specific project, upgrading your TypeScript version to the most recent one should fix the issue.

If instead, you’d like to upgrade to the minimum necessary version of TypeScript that correctly parses the PSPDFKit declaration file, look for the specific TypeScript error code that you’re observing (e.g. TS1005), and search the internet to find the TypeScript release that shipped with that change.

Unfortunately, it isn’t trivial to update TypeScript versions for some projects. We’ve seen this being the case for teams relying on older versions of the Angular framework. In these cases, you can try one of the following approaches.

Patching the Declaration File That PSPDFKit Ships With

In most cases, there are only a few bits of conflicting syntax between the PSPDFKit declarations and your TypeScript version. For these cases, you can manually adapt our declarations as needed and mostly keep all the benefits of the type declarations.

Using patch-package (Recommended Approach)

patch-package is a tool for performing manual changes to npm dependencies while allowing you to apply regular updates to the underlying dependencies. In this case, you can use it to change the type declarations shipped by PSPDFKit.

1. Go to the location of the .d.ts file in your PSPDFKit installation (usually node_modules/pspdfkit/dist/index.d.ts).

2. Perform the necessary changes to the file so that it’s compatible with your TypeScript version.

For instance, take our example from above:

declare type InsetJSON = [
  left: number,
  top: number,
  right: number,
  bottom: number
];

It relies on a feature called labeled tuple elements, which were introduced in TypeScript 4.0. An alternative for earlier TypeScript versions is to drop the labels:

declare type InsetJSON = [number, number, number, number];

3. Follow the setup instructions for patch-package.

4. Run npx patch-package pspdfkit.

5. Use Git to add the patch generated by patch-package and commit the changes:

git add patches/pspdfkit+2022.1.2.patch
git commit -m "fix type declarations in PSPDFKit"

Resolving Types for PSPDFKit to a Different Path

If using patch-package isn’t feasible, you can replace the declaration file from PSPDFKit for Web with a different one. Here’s how you can copy the original index.d.ts file that PSPDFKit ships with and modify it to adapt it to the current version that you’re shipping with.

1. Copy the declaration file from PSPDFKit to a location in your project:

$ cp node_modules/pspdfkit/dist/index.d.ts src/pspdfkit.d.ts

2. Apply the fix necessary.

3. Modify your tsconfig.json file with something like the following:

{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "pspdfkit": ["src/pspdfkit.d.ts"]
    }
  }
}

Replace src/pspdfkit.d.ts with the location of your modified copy of the PSPDFKit declaration type.

Check the TypeScript handbook for more information about the paths setting.

Please note that this approach might provoke some issues later on when you update the version of PSPDFKit for Web, since types might have changed since the current one and your declaration files might reflect incorrect values. For this reason, after each PSPDFKit update in your project, be sure to include the changes to the declaration file that the new PSPDFKit for Web version ships with.

Downgrading the Declaration File

You can use a tool like downlevel-dts to try to downgrade the declaration file from PSPDFKit to TypeScript 3.4.

1. Follow the instructions in the project and run the tool pointing to the declaration file that PSPDKFit ships with (usually under node_modules/pspdfkit/dist/index.d.ts).

2. Copy the resulting declaration file to your project.

3. Modify your tsconfig.json file with something like the following:

{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "pspdfkit": ["src/pspdfkit.d.ts"]
    }
  }
}

Replace src/pspdfkit.d.ts with the location of the transpiled copy of the PSPDFKit declaration type.

Skipping Type Declarations for PSPDFKit

As a last resource, you can generate a new blank declaration file for the pspdfkit module and skip all declarations we offer.

1. Create a new declaration file — e.g. pspdfkit.d.ts — as part of your project. If you already have an existing declaration file, you can skip this step.

2. Add the declare module "pspdfkit"; line to it.

3. Modify your tsconfig.json file with something like the following:

{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "pspdfkit": ["src/pspdfkit.d.ts"]
    }
  }
}

Replace src/pspdfkit.d.ts with the correct path to your declaration file.

Please note that this is a last resort, and when doing this, all type declarations for PSPDFKit for Web in your project will be lost.