Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Proposal of a convention about npm modules distribution. #575

Closed
vilic opened this issue Aug 31, 2014 · 16 comments

Comments

Projects
None yet
6 participants
@vilic
Copy link
Contributor

commented Aug 31, 2014

There was an discussion about generating ambient declarations for external CommonJS modules: http://typescript.codeplex.com/workitem/2080

But even if typescript generates the definitions as we what we want, we'll still need to add references manually, which is not doing better job than JS libs with NuGet DefinitelyTyped packages.

I propose that when we publish a typescript package via npm, publish the .d.ts file(s) generated with the current style along with it.

So that we can manage to write a tool (or add a feature to something like WebEssentials) to watch related node_modules directory, resolve the definition references and create wrapped definition file(s) under scripts/typings folder.

Thoughts?

@RyanCavanaugh

This comment has been minimized.

Copy link
Member

commented Sep 8, 2014

I'm not sure exactly what this means? Is this a proposal for community behavior, or a change in TypeScript?

@vilic

This comment has been minimized.

Copy link
Contributor Author

commented Sep 8, 2014

@RyanCavanaugh this time it's for community behavior. (Or I need to post it elsewhere?)

@poelstra

This comment has been minimized.

Copy link

commented Sep 25, 2014

Note that the TypeScript Definition Manager (tsd) is also in the process of 'standardising' this, see https://github.com/DefinitelyTyped/tsd#link-to-package-manager-bundled-definitions

Ideally, TypeScript should produce external typings (when "-m commonjs" is supplied), but until then, one can use e.g. https://github.com/grunt-ts/dts-bundle as a (quick&dirty) tool to convert TypeScript's existing internal typings to external ones.

@vilic

This comment has been minimized.

Copy link
Contributor Author

commented Sep 25, 2014

@poelstra thanks for your links, it's good to know there's already main stream tools working on this. :D

@xealot

This comment has been minimized.

Copy link

commented Nov 3, 2014

We have recently run into the situation where trying to use several Typescript projects that depend on one another can become quite a nightmare. This extends almost solely from the fact that when using external (real) modules the definition files are created per module and there isn't any clear way to concat them, compile them or otherwise export them for use in another project.

We will be investigating your links @poelstra, thank you.

I also wanted to ask if anything has changed regarding this particular situation.

@poelstra

This comment has been minimized.

Copy link

commented Nov 4, 2014

We started off trying to use the NPM-way of having many small modules, but this was too much hassle. We're still using CommonJS (solely), but are building almost everything as one big NPM module.

We've open-sourced one package for now (https://github.com/SpiritIT/timezonecomplete, shameless plug ;)), for which we also submitted typings to DefinitelyTyped, as the "tsd link" functionality didn't seem usable at the time. We're using dts-bundle for generating these typings, which tends to work great in practice.

So even in our main TypeScript project, we're effectively treating that package as any other 'plain' Javascript package, and 'manually' apply the DT typings. This is suboptimal, but it works.

I think the only strangeness we've had is that VS's IntelliSense occasionally forgets what members the enums in Timezonecomplete have, whereas the commandline compiler accepts the code just fine. Not sure why yet.

If you found a better workflow for using TypeScript modules, I'm very interested in hearing about it!

@xealot

This comment has been minimized.

Copy link

commented Dec 2, 2014

I want to mention that this most likely has a strong relationship to:
#17

@mhfrantz

This comment has been minimized.

Copy link

commented Mar 30, 2015

We're interested in a cleaner solution than ts-pkg-installer, which we wrote to address TypeScript modularity in the NPM/TSD ecosystem.

https://github.com/RedSeal-co/ts-pkg-installer

We also use dts-bundle, which complements ts-pkg-installer in that it generates a declaration file that can be installed with ts-pkg-installer.

@mhegazy

This comment has been minimized.

Copy link

commented Mar 31, 2015

@vladima has proposal in #2338 for managing typings as part of resolving node_modules. the idea is that the package.json would have a "types" as a property, and the typescript compiler will look up that file and use it if it exists. would that work?

@vilic

This comment has been minimized.

Copy link
Contributor Author

commented Mar 31, 2015

@mhfrantz I am also designing a package manager for TypeScript. Hoping it could be compatible with NPM and other package managers like bower. And I would like it to support some simple pre-compile features for supporting libraries with or without module system. https://github.com/vilic/tying

@mhfrantz

This comment has been minimized.

Copy link

commented Mar 31, 2015

@mhegazy, having reference paths work with node_modules/package.json would be ideal. The most brittle part of the reference path feature is the necessity of specifying the exact location of files. Resolving reference paths within node_modules makes the most sense from the NodeJS standpoint.

It is important to incorporate DefinitelyTyped declarations as well, as all type information is not embedded within the NodeJS module itself.

It is also important to de-dupe the declarations.

@mhegazy

This comment has been minimized.

Copy link

commented Mar 31, 2015

Thanks @mhfrantz for the feedback, a few comments:

The most brittle part of the reference path feature is the necessity of specifying the exact location of files. Resolving reference paths within node_modules makes the most sense from the NodeJS standpoint.

The proposal in #2338 looks in node_modules and reads package.json

It is important to incorporate DefinitelyTyped declarations as well, as all type information is not embedded within the NodeJS module itself.

Any proposals on how to do that, and how would that be diffrent from something like what tsd is doing today.

It is also important to de-dupe the declarations.

What are the rules? any proposals on how this should be done?

@mhfrantz

This comment has been minimized.

Copy link

commented Apr 1, 2015

@mhegazy If you look at what ts-pkg-installer is trying to do, it builds a TSD config file so that if multiple modules depend on the same declaration, they will all resolve to the same file. This is awkward, since it involves building config files, and then running the TSD utility on the result.

If it were incorporated into TSC, then perhaps reference paths would contain simple names, like a module name. It could look in node_modules first, and then in typings.

For example, suppose you see this:

///<reference path="mocha"/>

This is a reference to the module "mocha", which (today) has no TypeScript declaration of its own. Thus, it would resolve to typings/mocha/mocha.d.ts.

@mhegazy

This comment has been minimized.

Copy link

commented Apr 1, 2015

so what is the proposal, add <root>/typings as an implicit include path? though I am not a fan of include paths in general.

@mhfrantz

This comment has been minimized.

Copy link

commented Apr 1, 2015

@mhegazy It is not as simple as adding <root>/typings as an include path, since the logic for determining the exact *.d.ts file name varies. Given a reference to "@scope/foo":

  • If we find a module in node_modules called "@scope/foo", and its package.json contains a "types" section, then use that *.d.ts file.
  • If we find a module in typings called "@scope/foo", then use foo.d.ts in that directory.

Thus the proposal is to support both NPM packages written in TypeScript with embedded type declarations as well as NPM packages whose type declarations come via TSD. This can be accomplished with a single, coherent reference path syntax that is agnostic of the distinction between these two cases.

@poelstra

This comment has been minimized.

Copy link

commented Apr 20, 2015

@mhfrantz Just re-read this thread, and noticed that I seem to have run into a similar issue as what you describe (de-dupeing declarations, and supporting TSD case).

I created #2839 with a proposal for a solution, would it fit to your use-case too?

@vilic vilic closed this Sep 10, 2015

@microsoft microsoft locked and limited conversation to collaborators Jun 18, 2018

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
You can’t perform that action at this time.