Recommendation for exposing multiple TypeScript modules from single NPM package

[joewood]

The module resolution logic in the handbook doesn't mention how nested modules are supported from a single npm package. There is an old issue discussing this that has been closed: #5804

Neither the solution here or simply trying to refer to modules beneath the root dir referred to by the typings or main path seems to work. Is there a documented best practice? The documentation says that ambient modules should not be used in the typings field in package.json.

Just to be clear, I want to write this in a consuming app:

import {stuff} from "my-npm-lib/submodule"

Where the package.json file in my-npm-lib has:

    "main": "lib/index.js",
    "typings": "lib/index.d.ts",

And the file structure in the my-npm-lib:

my-npm-lib\
    index.js
    index.d.ts
    submodule.js
    submodule.d.ts

Currently this complains with a module not found error. But this works, but shouldn't:

import {stuff} from "my-npm-lib/lib/submodule"

This is all with the module resolution setting set to node.

[mhegazy]

We need to add documentation, so leaving this issue open to track that, and marking it as such.

For the question, the recommendation is to generate the .d.ts with 1:1 mapping to your .js files, and place them next to the .js file in the published package, as you mentioned. the "typings" field specify the main entry point, matching "main" for the .js file.

I have a sample posted at https://github.com/mhegazy/npm-dependency-test, take a look and let me know if you have more questions.

[joewood]

Thanks @mhegazy
As I thought. The only real way of achieving submodules is to pollute the root directory. I think that's a limitation of JavaScript/npm too though, so not a massive deal.

One option to avoid the pollution is to use a postinstall script to only pollute the root dir after npm install. This works fine, but it doesn't work too well with npm link. Another option could be to just move the build files from a distribution dir to the root in postinstall. Anyway, right now I've just resorted to adding a files.exclude filter in vscode to hide the mess.

As you suggested, it would be great to update the handbook on best practices for distributing typescript built libraries, especially with respect to typings and dependent types.

[jcansdale]

@mhegazy I'm confused about why there is the need for a separate "typings" entry when the .d.ts is invariably next to the one referenced by "main". Why not simply look next to the "main" .js or at least look there as well?

[mhegazy]

Not sure i see the issue really. if you are adding "main" property in your package.json, should not be too much to ask to add "typings" as well.

[jcansdale]

@mhegazy It's more that is seems inconsistent. From my understanding, if you: import foo = require("foo.js"), TypeScript tools will automatically look for type definitions in "foo.d.ts". If however you: require("bar") and there is a "main": "foo.js" in bar/package.json, TypeScript tools won't automatically look for type definitions in "bar/foo.d.ts".

This is a shame because otherwise you could convert a JavaScript package into TypeScript by simply renaming the .js files to .ts and compiling with the definitions option. Unfortunately you need to know about the "typings" option otherwise your consumers won't see your type definitions. It just seems like an unnecessary gotcha. Why not support "main" relative as well as "typings"?

Does that make sense?

[mhegazy]

it does work for index.js -> index.d.ts. We could add support for main. but the idea was if you chose to change the defaults for your package by setting a main, then you should also consider what you want to put in typings, they may or may not be in the same place.

[jcansdale]

How about making it so that if typingsexists look for it there, otherwise look for it relative to main? Maybe there is one but I can't think of a good reason why you wouldn't want to look next to main if a typings entry doesn't exist. I'm thinking more for package authors who've written their package using TypeScript, rather than authors who want to add typings to their JavaScript package.

[mhegazy]

feel free to file a separate issue for this proposal.

[bogdanmanate]

This will definitely be a major improvement for Typescript development. I'm currently developing a library in TS and this library should be included in an Angular 2 application. I've also looked into angular repository to see how they are exporting the modules, but it seems that they bundle the modules in a single file.

[mhegazy]

here is the documentation for writing declaration files. please let us know if there are any missing scenarios.