Tips for enabling users to import from subdirectories within my NPM package

Question

Tips for enabling users to import from subdirectories within my NPM package

Is there a way to allow users to import from subfolders of my TypeScript NPM package? For instance, if the TypeScript code is structured like this:

- lib
- src
  - server
  - react

Users should be able to import from the subfolders as package-name/react, package-name/server, etc.

My tsconfig.json configuration looks like this:

{
    "compilerOptions": {
      "target": "es5",
      "module": "commonjs",
      "declaration": true,
      "outDir": "./lib",
      "strict": true,
      "jsx": "react",
      "esModuleInterop": true
    },
    "include": ["src"],
    "exclude": ["node_modules", "**/__tests__/*"]
  }

I was able to achieve this when setting "outDir" to the project root, but it made the file structure messy. Can anyone suggest a solution for importing from submodules while keeping "outDir": "./lib"? Any helpful responses would be greatly appreciated. Thank you in advance.

typescript npm import subdirectory

Answer 1

Answer №1

To enable a specific entry point in the package.json file, you can utilize the exports field:

"exports": {
  "./server": "./lib/server",
  "./react": "./lib/react"
},

For more details, refer to: https://nodejs.org/api/packages.html#packages_package_entry_points

However, it's important to note that:

Warning: Implementing the "exports" field may restrict consumers from using undefined entry points, such as the package.json (e.g. require('your-package/package.json'). This could potentially cause disruptions.

UPDATE: TypeScript seems to overlook this field, but incorporating types like this might be helpful:

// server.d.ts
export * from "./lib/server";

// react.d.ts
export * from "./lib/react";

My Approach

I replicated your project structure and made modifications:

src/
  server.ts
  react.ts
lib/
  (generated output)
  server.d.ts
  server.js
  react.d.ts
  react.js
package.json
tsconfig.json
react.d.ts
server.d.ts

Add the following lines to package.json:

"exports": {
  "./server": "./lib/server",
  "./react": "./lib/react"
},

react.d.ts

export * from "./lib/react";

server.d.ts

export * from "./lib/server";

This approach worked for me. Now I was able to import "mypackage/server" in another context. If you haven't split the definition files yet, consider implementing these changes to test their effectiveness.

Answer 2

To enable a specific entry point in the package.json file, you can utilize the exports field:

"exports": {
  "./server": "./lib/server",
  "./react": "./lib/react"
},

For more details, refer to: https://nodejs.org/api/packages.html#packages_package_entry_points

However, it's important to note that:

Warning: Implementing the "exports" field may restrict consumers from using undefined entry points, such as the package.json (e.g. require('your-package/package.json'). This could potentially cause disruptions.

UPDATE: TypeScript seems to overlook this field, but incorporating types like this might be helpful:

// server.d.ts
export * from "./lib/server";

// react.d.ts
export * from "./lib/react";

My Approach

I replicated your project structure and made modifications:

src/
  server.ts
  react.ts
lib/
  (generated output)
  server.d.ts
  server.js
  react.d.ts
  react.js
package.json
tsconfig.json
react.d.ts
server.d.ts

Add the following lines to package.json:

"exports": {
  "./server": "./lib/server",
  "./react": "./lib/react"
},

react.d.ts

export * from "./lib/react";

server.d.ts

export * from "./lib/server";

This approach worked for me. Now I was able to import "mypackage/server" in another context. If you haven't split the definition files yet, consider implementing these changes to test their effectiveness.

Answer 3

Answer №2

To implement the following functionality, insert the exports entry below in your package.json file:

"exports": {
  "./": "./lib/"
},

Once the entry is added, you will be able to import from the lib subfolder or any file within the lib folder. However, for a subfolder within the lib folder, there must be an index.js file which will handle the imports.

The structure after typescript compilation that would work is as follows:

- lib
- src
  - server.js
  - react.js

- lib
- src
  - server
    - index.js
  - react
    - index.js

Note: Do ensure that the presence of a slash(/) at the end of the entry since it is crucial for subpath export to function properly.

Follow these example steps:

mkdir -p mod1/src/api mod2/src
cd mod1
npm init -y

mod1/tsconfig.json

{
    "compilerOptions": {
      "target": "es5",
      "module": "commonjs",
      "declaration": true,
      "outDir": "./lib",
      "strict": true,
      "jsx": "react",
      "esModuleInterop": true
    },
    "include": ["src"],
    "exclude": ["node_modules", "**/__tests__/*"]
}

mod1/package.json

{
  "name": "mod1",
  "version": "1.0.0",
  "description": "",
  "exports": {
    "./": "./lib/"
  },
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "MIT"
}

mod1/src/api/index.ts

export const api = function() : void {
  console.log('api');
}

mod1/src/react.ts

export const react = function() : void {
  console.log('react');
}

mod1/src/server.ts

export const server = function() : void {
  console.log('server');
}

Navigate to the mod2 directory

cd ../mod2
npm init -y
npm install ../mod1

mod2/src/index.js

const lib = require('mod1/server');
const { react } = require('mod1/react');
const { api } = require('mod1/api');
lib.server();
react();
api();

Note: The process was tested using node version 14.4.0 and tsc version 4.2.4

Answer 4

To implement the following functionality, insert the exports entry below in your package.json file:

"exports": {
  "./": "./lib/"
},

Once the entry is added, you will be able to import from the lib subfolder or any file within the lib folder. However, for a subfolder within the lib folder, there must be an index.js file which will handle the imports.

The structure after typescript compilation that would work is as follows:

- lib
- src
  - server.js
  - react.js

- lib
- src
  - server
    - index.js
  - react
    - index.js

Note: Do ensure that the presence of a slash(/) at the end of the entry since it is crucial for subpath export to function properly.

Follow these example steps:

mkdir -p mod1/src/api mod2/src
cd mod1
npm init -y

mod1/tsconfig.json

{
    "compilerOptions": {
      "target": "es5",
      "module": "commonjs",
      "declaration": true,
      "outDir": "./lib",
      "strict": true,
      "jsx": "react",
      "esModuleInterop": true
    },
    "include": ["src"],
    "exclude": ["node_modules", "**/__tests__/*"]
}

mod1/package.json

{
  "name": "mod1",
  "version": "1.0.0",
  "description": "",
  "exports": {
    "./": "./lib/"
  },
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "MIT"
}

mod1/src/api/index.ts

export const api = function() : void {
  console.log('api');
}

mod1/src/react.ts

export const react = function() : void {
  console.log('react');
}

mod1/src/server.ts

export const server = function() : void {
  console.log('server');
}

Navigate to the mod2 directory

cd ../mod2
npm init -y
npm install ../mod1

mod2/src/index.js

const lib = require('mod1/server');
const { react } = require('mod1/react');
const { api } = require('mod1/api');
lib.server();
react();
api();

Note: The process was tested using node version 14.4.0 and tsc version 4.2.4

Answer 5

Answer №3

To streamline your repository structure during the publish process, consider moving your package.json file into the dist/lib folder. Take a look here for an example of how this can be done. Keep in mind that this approach may complicate yarn link and may not be compatible with yarn workspaces.

Another option is to utilize the exports key in package.json once support for it is implemented in TypeScript – see this link for more information.

Answer 6

To streamline your repository structure during the publish process, consider moving your package.json file into the dist/lib folder. Take a look here for an example of how this can be done. Keep in mind that this approach may complicate yarn link and may not be compatible with yarn workspaces.

Another option is to utilize the exports key in package.json once support for it is implemented in TypeScript – see this link for more information.

Tips for enabling users to import from subdirectories within my NPM package

Answer №1

Answer №2

Answer №3

Similar questions

Delay the execution until all promises inside the for loop are resolved in Angular 7 using Typescript

What could be causing the error within the 'react-code-blocks' library?

Tips for resolving the error: finding the right loader for handling specific file types in React hooks

Creating a Universal Resolver in Angular (2+) - A Step-by-Step Guide

The Angular material checkbox has a mind of its own, deciding to uncheck

What could be causing an error with NextJS's getStaticPaths when running next build?

The absence of a function implementation right after the declaration within a TypeScript class is a common issue that needs

Angular 2 - Issue: Parameters provided do not correspond to any signature of call target

What is the best way to integrate Next.js with Strapi (or the other way around)?

## We have encountered a problem with node-fibers ##

tips for accessing dynamic key pair value data in Angular

Exploring through objects extensively and expanding all their values within Angular

Looking for a solution to resolve the issue "ERROR TypeError: Cannot set property 'id' of undefined"?

The error message received when attempting to install Copay using npm is: unable to execute in working directory %s %s (working directory

Utilize the identical function within the reducer for numerous mat-slide-toggle and checkboxes in component.html

Angular Error: Potential security risk detected in resource URL context due to unsafe value being used

Error encountered while attempting to load SWC binary for win32/ia32 in a Next JS application

An Axios error message indicates ERR_NETWORK and ERR_EMPTY_RESPONSE

Leveraging Fastify's preHandler middleware functionality

Is it possible to implement a redirect in Angular's Resolve Navigation Guard when an error is encountered from a resolved promise?