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
vilicvane opened this issue Aug 31, 2014 · 16 comments
Closed

Proposal of a convention about npm modules distribution. #575

vilicvane opened this issue Aug 31, 2014 · 16 comments
Labels
Discussion Issues which may not have code impact

Comments

@vilicvane
Copy link
Contributor

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
Copy link
Member

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

@vilicvane
Copy link
Contributor Author

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

@RyanCavanaugh RyanCavanaugh added Discussion Issues which may not have code impact and removed Needs More Info The issue still hasn't been fully clarified labels Sep 8, 2014
@poelstra
Copy link

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.

@vilicvane
Copy link
Contributor Author

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

@xealot
Copy link

xealot 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
Copy link

poelstra 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
Copy link

xealot commented Dec 2, 2014

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

@mhfrantz
Copy link

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
Copy link
Contributor

mhegazy 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?

@vilicvane
Copy link
Contributor Author

@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
Copy link

@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
Copy link
Contributor

mhegazy 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
Copy link

mhfrantz 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
Copy link
Contributor

mhegazy 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
Copy link

mhfrantz 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
Copy link

@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?

@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.
Labels
Discussion Issues which may not have code impact
Projects
None yet
Development

No branches or pull requests

6 participants