What is the best way to manage optional peer dependency types while releasing a TypeScript package?

Question

What is the best way to manage optional peer dependency types while releasing a TypeScript package?

I'm trying to figure out the best way to handle optional peer dependencies when publishing a TypeScript package on npm. My package provides a function that can accept input from either one of two peer dependencies. How should I define these optional peer dependencies?

import { ExternalFoo } from 'foo';
import { ExternalBar } from 'bar';

export const customPackage = (source: ExternalFoo | ExternalBar) => {
    /* ... */
}

Is there a way to ensure that users of my package won't encounter errors if they have only one of the required dependencies installed, but not both?

typescript npm publish

Answer 1

Answer №1

With the introduction of Typescript 3.8, a new syntax is available:

import type { ExternalFoo } from "foo";

If you are simply using the library for type information, there may no longer be a need to list it as a dependency or an optionalDependency. Instead, you could consider specifying it as a peerDependency, ensuring that users have compatible versions with your library. Including it as a devDependency can also be beneficial.

It's important to note that this import will only appear in the generated d.ts files and not in the transpiled .js code. However, if the library is not installed by users, the type will default to any, potentially affecting your own typing. This could lead to issues such as:

customPackage = (source: any | ExternalBar) =>
// equivalent to customPackage = (source: any) =>

In scenarios where the library is missing, the type annotation won't properly utilize related types even if they are present. While there is a method to reduce dependency on external libraries, challenges still exist in maintaining type annotations that remain robust regardless of their presence.

To explore solutions for handling missing types, refer to this answer.

For more details on Type-Only Imports and Exports in Typescript 3.8, visit the reference page.

Answer 2

With the introduction of Typescript 3.8, a new syntax is available:

import type { ExternalFoo } from "foo";

If you are simply using the library for type information, there may no longer be a need to list it as a dependency or an optionalDependency. Instead, you could consider specifying it as a peerDependency, ensuring that users have compatible versions with your library. Including it as a devDependency can also be beneficial.

It's important to note that this import will only appear in the generated d.ts files and not in the transpiled .js code. However, if the library is not installed by users, the type will default to any, potentially affecting your own typing. This could lead to issues such as:

customPackage = (source: any | ExternalBar) =>
// equivalent to customPackage = (source: any) =>

In scenarios where the library is missing, the type annotation won't properly utilize related types even if they are present. While there is a method to reduce dependency on external libraries, challenges still exist in maintaining type annotations that remain robust regardless of their presence.

To explore solutions for handling missing types, refer to this answer.

For more details on Type-Only Imports and Exports in Typescript 3.8, visit the reference page.

Answer 3

Answer №2

After exploring various solutions, I have discovered a robust approach that works well with the latest versions of TypeScript (as of late 2021):

// @ts-ignore -- defining an optional interface to gracefully handle scenarios where `foo` is not available
import type { Foo } from "foo";
import type { Bar } from "bar";

// Determines the argument type based on the availability of `foo`
type Argument = any extends Foo ? Bar : (Foo | Bar);

export function customPackage(source: Argument): void {
  ...
}

You can experiment with this solution yourself. If the foo module is present, the method will accept arguments of type Foo or Bar, and if it is not available, it will only allow Bar (not any).

Answer 4

After exploring various solutions, I have discovered a robust approach that works well with the latest versions of TypeScript (as of late 2021):

// @ts-ignore -- defining an optional interface to gracefully handle scenarios where `foo` is not available
import type { Foo } from "foo";
import type { Bar } from "bar";

// Determines the argument type based on the availability of `foo`
type Argument = any extends Foo ? Bar : (Foo | Bar);

export function customPackage(source: Argument): void {
  ...
}

You can experiment with this solution yourself. If the foo module is present, the method will accept arguments of type Foo or Bar, and if it is not available, it will only allow Bar (not any).

Answer 5

Answer №3

Unfortunately, TypeScript currently struggles to fully support your specific scenario.

To summarize your situation:

Your dependency on foo and bar is optional, assuming that your consumers will use one of them with your library.
You are solely utilizing the type information from these libraries without any code dependencies, and you prefer not to add them as dependencies in your package.json.
Your customPackage function is public.

However, due to point 3, you must include these types in your library typings, which contradicts points 1 and 2 since it requires adding foo and bar as dependencies.

If the typings for foo and bar come from DefinitelyTyped (e.g., package @types/foo and @types/bar), adding them as dependencies in your package.json should resolve the issue.

Alternatively, if the typings are distributed with the libraries themselves, you can either add the libraries as dependencies (against your preference) or generate replicas of the types such as ExternalFoo and ExternalBar.

This approach would disconnect your reliance on foo and bar.

Another option is to reevaluate your library and consider the implications of including foo and bar as dependencies. Depending on your library's nature, this may not be as detrimental as anticipated.

Personally, I tend to opt for declaring the types independently, given JavaScript's dynamic nature.

Answer 6

Unfortunately, TypeScript currently struggles to fully support your specific scenario.

To summarize your situation:

Your dependency on foo and bar is optional, assuming that your consumers will use one of them with your library.
You are solely utilizing the type information from these libraries without any code dependencies, and you prefer not to add them as dependencies in your package.json.
Your customPackage function is public.

However, due to point 3, you must include these types in your library typings, which contradicts points 1 and 2 since it requires adding foo and bar as dependencies.

If the typings for foo and bar come from DefinitelyTyped (e.g., package @types/foo and @types/bar), adding them as dependencies in your package.json should resolve the issue.

Alternatively, if the typings are distributed with the libraries themselves, you can either add the libraries as dependencies (against your preference) or generate replicas of the types such as ExternalFoo and ExternalBar.

This approach would disconnect your reliance on foo and bar.

Another option is to reevaluate your library and consider the implications of including foo and bar as dependencies. Depending on your library's nature, this may not be as detrimental as anticipated.

Personally, I tend to opt for declaring the types independently, given JavaScript's dynamic nature.

Answer 7

Answer №4

Dealing with a complex scenario, I have discovered a solution that involves inserting a ts-ignore prior to importing the type that may not be present in the user's system:

// @ts-ignore
import type { Something } from "optional"
import type { AnotherThing } from "necessary"

This allows you to include the package in both peerDependencies and peerDependenciesMeta as optional.

Answer 8

Dealing with a complex scenario, I have discovered a solution that involves inserting a ts-ignore prior to importing the type that may not be present in the user's system:

// @ts-ignore
import type { Something } from "optional"
import type { AnotherThing } from "necessary"

This allows you to include the package in both peerDependencies and peerDependenciesMeta as optional.

Answer 9

Answer №5

Context

An issue arises when utilizing optional dependencies within a file that is accessible through the primary entrypoint of your package (e.g., ./index.ts).

Resolution

To address this problem, consider breaking down your code to have multiple entry points. For instance, maintain one primary entry point and include two optional modules – FooModule and BarModule – which users must import explicitly.

Snippet

This section illustrates the package definition and how the library is utilized (imports).

library's package.json

The package.json specifies several entry points (exports) along with their corresponding type definitions (typesVersions).

{
  "name": "my-package"
  "version": "1.0.0",
  "main": "./dist/index.js",
  "exports": {
    ".": "./dist/index.js",
    "./foo": "./dist/modules/foo/index.js",
    "./bar": "./dist/modules/bar/index.js"
  },
  "typesVersions"<span;>{
    "*": {
      "*": [
        "dist/index.d.ts"
      ],
      "foo": [
        "dist/modules/foo/index.d.ts"
      ],
      "bar": [
        "dist/modules/bar/index.d.ts"
      ]
    }
  },
}

how my-package is used in client code

By solely importing the FooModule, there is no requirement to install optional dependencies for the BarModule.

import { MyPackage } from 'my-package';
import { FooModule } from 'my-package/foo';

const myPackage = new MyPackage({ module: new FooModule() })

Answer 10

Context

An issue arises when utilizing optional dependencies within a file that is accessible through the primary entrypoint of your package (e.g., ./index.ts).

Resolution

To address this problem, consider breaking down your code to have multiple entry points. For instance, maintain one primary entry point and include two optional modules – FooModule and BarModule – which users must import explicitly.

Snippet

This section illustrates the package definition and how the library is utilized (imports).

library's package.json

The package.json specifies several entry points (exports) along with their corresponding type definitions (typesVersions).

{
  "name": "my-package"
  "version": "1.0.0",
  "main": "./dist/index.js",
  "exports": {
    ".": "./dist/index.js",
    "./foo": "./dist/modules/foo/index.js",
    "./bar": "./dist/modules/bar/index.js"
  },
  "typesVersions"<span;>{
    "*": {
      "*": [
        "dist/index.d.ts"
      ],
      "foo": [
        "dist/modules/foo/index.d.ts"
      ],
      "bar": [
        "dist/modules/bar/index.d.ts"
      ]
    }
  },
}

how my-package is used in client code

By solely importing the FooModule, there is no requirement to install optional dependencies for the BarModule.

import { MyPackage } from 'my-package';
import { FooModule } from 'my-package/foo';

const myPackage = new MyPackage({ module: new FooModule() })

What is the best way to manage optional peer dependency types while releasing a TypeScript package?

Answer №1

Answer №2

Answer №3

Answer №4

Answer №5

Context

Resolution

Snippet

library's package.json

how my-package is used in client code

Similar questions

What is the best way to combine properties from Type1 and Type2 to create a new type in Typescript?

Can two different versions of a library be utilized simultaneously in NPM?

What is the importance of adding the ".js" extension when importing a custom module in Typescript?

Unable to use global modules in NestJS without importing them

Is there a way to prevent npm from bootstrapping when pushing to Heroku using git?

All authentication logic in Angular encapsulated within the service

Encountering difficulties while setting up ESLint with Sublime Text

Error in TypeScript while running the command "tsd install jquery" - the identifier "document" could not be found

Accessing the state from a child functional component and then adding it to an array of objects in the parent component

Executing npm / http-server script

Having trouble retrieving an object property in HTML or TypeScript within an Angular framework?

I am unable to locate the module 'fs': I have exhausted all possible solutions to fix this problem

The color scheme detection feature for matching media is malfunctioning on Safari

I attempted to use ng add @angular/pwa, but encountered an error code that is baffling to me. Are there any steps I can take to resolve this issue?

Error: Attempting to access a property named '_updatedFibers' on an undefined object is not possible due to a TypeError

What is the reason for not opening the ndb debugger in the package.json file?

Encountering vulnerabilities during NPM installation, attempting to fix with 'npm audit fix' but unsuccessful

Travis CI's TypeScript build process detects errors before Mocha has a chance to catch them

Angular strictPropertyInitialization - best practices for initializing class members?

Typescript validation of tokens using Azure functions