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

Exploring through objects extensively and expanding all their values within Angular

Accessing data retrieved from an API Subscribe method in Angular from an external source

Employ various iterations of the leaflet library

Expose sub-modules within npm packages for added functionality

"Is it possible in Typescript to set the parameters of a returning function as required or optional depending on the parameters of the current

Guide on merging paths in distinct modules within an Angular project

Using the HTTP Post method to retrieve a file object: a step-by-step guide

Creating a Versatile Data Retrieval Hook in TypeScript for APIs with Diverse Response Formats

A guide to sending epoch time data to a backend API using the owl-date-module in Angular

The combination of TypeScript decorators and Reflect metadata is a powerful tool for

Error: The "res.json" method is not defined in CustomerComponent

Oops! There seems to be an issue with the code: "TypeError: this

SonarLint is suggesting that the parameter currently in use should either be removed or renamed

Using interfaces for typecasting in TypeScript

Tips for fixing the HTTP error 431 in Next.js with Next-Auth

Refreshing Angular 9 component elements when data is updated

Creating unique components with Angular2 and Ionic

NPM ERROR: npm ERR! failed to identify the executable for execution

The replacer argument of the JSON.stringify method doesn't seem to work properly when dealing with nested objects

When it comes to semantic versioning, which release number gets incremented when a module introduces compatibility improvements without causing any disruptions?