Tips for implementing absolute import paths in a library project

Question

Tips for implementing absolute import paths in a library project

In my workspace, I have a library with two projects: one for the library itself and another for a test application.

├── projects
    ├── midi-app
    └── midi-lib

Within the workspace's tsconfig.json file, I set up paths for @app and @lib:

"paths": {
  "@app/*": ["projects/midi-app/src/app/*"],
  "@lib/*": ["projects/midi-lib/src/lib/*"],
  "midi-lib": [
    "dist/midi-lib"
  ],
  "midi-lib/*": [
    "dist/midi-lib/*"
  ]
}

In addition, there is a

projects/midi-lib/tsconfig.lib.json

file that extends the main tsconfig.json settings:

"extends": "../../tsconfig.json",

The library has a public-api.ts file which includes:

export * from './lib/midi-lib.module';

I can successfully use this library in the test application. However, when I try importing it as a Node module into a separate client application within a different workspace, I encounter numerous errors related to unknown paths like Can't resolve '@lib/...'

How can I make sure the library paths are accessible in a client application? Or how can I handle the translation of these paths during the library packaging process?

Additionally, I am curious why the extension is not the other way around - why doesn't the main tsconfig.json file extend the

projects/midi-lib/tsconfig.lib.json

file instead?

Here is my approach to packaging and using the library:

To package the library, I add the following scripts to the parent package.json file:

"copy-license": "cp ./LICENSE.md ./dist/midi-lib",
"copy-readme": "cp ./README.md ./dist/midi-lib",
"copy-files": "npm run copy-license && npm run copy-readme",
"build-lib": "ng build midi-lib",
"npm-pack": "cd dist/midi-lib && npm pack",
"package": "npm run build-lib && npm run copy-files && npm run npm-pack",

After adding these scripts, I run the command: npm run package

Then, I install the dependency by running:

npm install ../midi-lib/dist/midi-lib/midi-lib-0.0.1.tgz

And import the module in the application module. In the app.module.ts file:

import { MidiLibModule } from 'midi-lib';
@NgModule({
  imports: [
    MidiLibModule

Lastly, I insert the component in a template:

<midi-midi-lib></midi-midi-lib>

Upon installing the library in a client application, I notice various .d.ts files under the node_modules/midi-lib directories:

├── bundles
├── esm2015
│   └── lib
│       ├── device
│       ├── keyboard
│   ...
│   └── upload

One example is the lib/service/melody.service.d.ts file:

import { SoundtrackStore } from '@lib/store/soundtrack-store';
import { ParseService } from '@lib/service/parse.service';
import { CommonService } from './common.service';
export declare class MelodyService {
    private soundtrackStore;
    private parseService;
    private commonService;
    constructor(soundtrackStore: SoundtrackStore, parseService: ParseService, commonService: CommonService);
    addSomeMelodies(): void;
    private addSoundtrack;
    private generateNotes;
}

This file references the @lib path mapping, which is not recognized in the client application.

I also tried using the baseUrl property as a workaround, but it didn't solve the issue since the baseUrl value was not specified during library installation.

Why does running npm run package to package the library not resolve the paths mappings?

angular typescript tsconfig angular-library tsconfig-paths

Answer 1

Answer №1

The establishment of the paths mapping in your tsconfig.json is specifically for compile-time purposes only. This does not impact the code generated by the TypeScript compiler itself. This could be the reason why you are experiencing an error at runtime. A suggestion was made to the TypeScript project, proposing that tsc should automatically translate module paths in the emitted code to align with the established mapping under paths. The response from the TS devs indicated that tsc is functioning as intended and the solution would require configuring a module loader that can perform a similar mapping at runtime as defined by paths.

Based on the details provided regarding your situation, here's what I believe you should consider doing:

If midi-app is primarily a test application without distribution requirements, you should be able to continue using the existing paths mapping without encountering issues. (Since there have been no mentioned problems while running this app, it appears that your tools are handling the runtime issue seamlessly.)

For midi-lib, it might be best to avoid relying on mappings set by paths and opt for relative paths instead. This approach ensures smoother consumption by others since this library is designed for external use. Consumers utilizing Webpack, Rollup, SystemJS, and similar tools will need to configure mappings specific to your library alongside their configurations.

Furthermore, the complexity of required configuration could escalate depending on how and where consumers utilize your library. While a global mapping may suffice when your package is the sole instance requiring such a mapping, scenarios involving multiple libraries necessitate intricate configurations to designate distinct mappings accordingly.

While the discussion has focused on module resolution during bundling or runtime loading, another consideration involves establishing specialized configurations within tsc compilation files which include .d.ts files.

By leveraging relative paths in your code, consumers of your library won't face challenges implementing unique configurations tailored to accommodate your library's requirements.

An exception to this strategy may apply if your intention is to publish your library as midi-lib. In such cases, modifying your paths map to reference midi-lib/* rather than @lib/* could be advantageous:

"midi-lib/*": ["projects/midi-lib/src/*"],

(Take note that the @ symbol holds no significance in relation to TypeScript. If your package warrants installation within a scope like @midi-project/midi-lib, ensure your tsconfig.json mapping includes the appropriate scope: "@midi-project/midi-lib/*": ...)

The objective is to establish a mapping enabling imports within your project just as consumers would import individual modules from your project. For instance, if a consumer fetches the ParseService module through

import { ParseService } from "midi-lib/lib/service/parse.service"

, prioritize employing the same import format wherever applicable. Ensuring uniform path usage between compile time and runtime (or bundling) operations streamlines functionality. While the translation from paths occurs during compile time via tsc, Node's module resolution algorithm (or its equivalents such as Webpack or Rollup) handle translations during runtime or bundling.

The reduction in manual efforts varies based on selected naming conventions and your library's structure.

In theory, a post ng build step could potentially substitute occurrences of @lib in module names within the output generated by ng build. However, challenges exist:

The process isn't a simple tool activation; familiarity with tools such as rollup along with custom configuration creation is essential.
Ideally, a readily available tool capable of transforming the necessary .d.ts files doesn't currently exist, necessitating personalized tool development.
Adapting Angular AOT compilation metadata affected by the switch requires custom interventions due to current tool unavailability for such modifications.
Potential complications emerge from future Angular version updates altering AOT compilation metadata formats or introducing new metadata types that demand adjustments. Personal encounters reflect similar upheavals following Angular upgrades affecting AOT compilation metadata procedures.

Answer 2