TypeScript Import Confusion - It Can't Be This Hard

Question

I have been working with TypeScript off and on for two years now. I am not an expert by any means, but I've spent some time in the eco-system: with VS2015 and node tools, with VSCode, and at the command line with tsc and typings (also used by VSCode).

And I have struggled with the correct way to get static typing and auto-complete etc in the code I've been writing.

I have a repo I maintain (EasyNodeQ) which was the start of my TypeScript experience and I sort of got that to a manageable place with ///reference and DefinitelyTyped. But any time I tried to use that within another project I had issues.

Things got a little better when I started using typings (rather than downloading the *.d.ts files myself) and especially with the ambient flag.

But I still have lots of issues trying to use that package within other projects. Depending on the approach I take, I get lots of Duplicate Identifier's, or module not found's or...

And this can range from Node definitions, to packages I use in both places (like node-uuid).

All I want to understand is this: how to I structure EasyNodeQ so that as I'm working on it, I get the static typings benefits of TypeScript but also have it be seamlessly included in other projects which can then also get these benefits?

Does that make sense?

The basic use cases are: npm install a package and get its typings, use my EasyNodeQ package and get its typings, work in a new project that uses EasyNodeQ and other packages and easily manage those typings.

Preferably in a VSCode or command line way...

This is with ES6 and the latest version of TypeScript (though an answer that works with ES5 would be nice - just not required).

I hope this makes sense. I've looked all over and I can't cobble together an answer that works.

UPDATE

I'm not convinced I've done this the "right" way, but it's working now so I thought I'd post the various things I've done (generally in the order I think they mattered and not inclusive because I may have forgotten some).

• I hadn't npm'd the dependency package (easynodeq) and was just using a git url in the package.json - so I created a proper npm package and now install that package from npm
• Instead of trying to use Bus.ts as both code and definition, I made Bus.js the "meat" of the npm, and built a Bus.d.ts file (also in the npm)
• Embraced typings, using non-ambient definitions where possible and a mix of ambient definitions downloaded (via git) from DefinitelyTyped and "--ambient" definitions for the rest (because I'm still confused about the difference). The ambient definitions ended-up being the majority: node, express, serve-static, express-serve-static-core, mime, amqplib, when vs just bluebird and node-uuid, even though most of them were found by "typings search ..." Am I doing something wrong?
• Modified package.json to also do "typings install"
• Cleaned-up the git repo

Answer 1

There are several ways to make this work today. As you mentioned, using Typings works for definitions that aren't natively included in their NPM packages. For ones that do, you can using the typings field in package.json and it'll work with node module resolution. When you combine this together, you can publish packages that use both typings.json and relies on packaged typings - though this now forces your consumers to be using Typings to install the definitions. None of this, however, works with "ambient" definitions as they can not be namespaced properly.

This may be useful: https://github.com/typings/typings/blob/master/docs/faq.md#should-i-use-the-typings-field-in-packagejson . There's also dozens of examples I have using both workflows: https://github.com/blakeembrey/change-case/blob/master/package.json#L6 which uses node module resolution all the way down and https://github.com/blakeembrey/popsicle/blob/master/typings.json which uses Typings instead. Using Typings is only possible because it works to create namespaced ambient modules for you, but they won't conflict.