Typings files in alpha.46

[thelgevold]

It appears that the Angular2, http and router typings files are no longer included in the npm package under bundles/typings.
Are they hosted somewhere else now?

[kylecordes]

It appears to me that these d.ts files reside at the top level of the NPM package. Happily, Visual Studio code appears to find them there just fine.

I'm sure there's some documentation somewhere explaining the following, but unfortunately I do not know where. It is unclear to me when sifting through MPM packages, which typing's go where. But I think the files you're talking about are the typings for Angular's dependencies, while the typings for Angular itself are where I pointed out.

[pkozlowski-opensource]

@thelgevold this is on purpose: we no longer distribute bundled typings for ng2 but rather allow TS to discover them from node_modules (typings are located next to source files).

See https://github.com/Microsoft/TypeScript/wiki/Typings-for-npm-packages for more info

[coryrylan]

Just a heads up to any Visual Studio (not VSCode) users, the default classic resolution wont work because moduleResolution: "node" must be set to find the angular2 type definitions. This means you are forced to set your project to use cjs and use relative paths on all modules.

[woppa684]

We don't use NPM because we are in an MSBuild environment in Visual Studio. All we used was the bundled d.ts file. Is using node mandatory now? Unfortunately that doesn't fit in our build chain ...

What we currently did was check in the typings file and the js file somewhere in the "thirdparty" part of our source code tree (it's huge). In the build step for "thirdparty" those files were just copied to the output folder. In our visual studio project we then made a link to the typings file in the build folder. This link ensures us 2 things: The typings work in our project and in the post-build step the js bundle belonging to this typings file is included in our web archive.

I have no clue how we should do this without a typings file. I feel a bit reluctant to check in an entire node_modules folder when all I need is a typings file and a corresponding js file. Can I build the previously bundled d.ts file myself? @pkozlowski-opensource

[thelgevold]

Thanks, I think this change makes sense now that I am aware of it :-)

@woppa684 : I think you can still keep your current workflow since you can cherry pick the typings files you need from the node module and add those to your third party folder.
You can then create a single typings file with references to each individual file:
See my sample here: https://github.com/thelgevold/angular-2-samples/blob/master/typings/tsd.d.ts

I get mine from the node module now, but you can put the files wherever you want.

[robwormald]

@woppa684 if you're not using NPM, how are you getting your hands on the ng2 distribution exactly?
Pretty much all of our tooling is focused on NPM (given that we don't ship definitions to definitelyTyped and only upload prebundled code to code.angularjs.org)

That's not to say we won't, but I don't think we have a story for this yet. Could you (and other non NPM types) describe a little your expected / normal workflows?

[woppa684]

Ok @robwormald, let me explain a bit ...First of all, let me say that It's hard to describe our build workflow without giving too much detail or violating some NDA ;)

As a software designer at Canon I am responsible for the user interfaces of several product lines of digital production printers. In our current product we have a variety of different user interfaces (java swing based, java struts based, angular 1.x based). Our future UI will be web-based and has to work on all kinds of devices and screen sizes. We want to use Angular2 for that obviously :)

Since we're working in a very large codebase with a lot of engineers we want to use TypeScript and integrate that with our current build enviroment. We all work with Visual Studio and MSBuild. Our MSBuild environment is relatively strict since we will not allow custom build scripts (ant, grunt etc) to run. If we want to add a custom build step (say, for example, add js minification) an extra option will be added to our own tab in the vs project properties to enable this (this will then trigger some tool that will do the minification in a post-build step).

All our thirdparty dependencies (so, for the entire platform) reside in a separate solution. Our UI subsystem has a dependency to that subsystem then of course. So, what we need to do in the build step for the "thirdparty" subsystem is make sure that the dependencies the "ui" subsystem needs are in place.
In our current setup we put a specific version of the library we need (and its typings file) in version control. In our UI project we then reference this typings file as a link. By doing this, also our build system knows what to pack, eventually, in the web archive we create. So, if I for example link to thirdparty/js/angular2/typings/angular2.d.ts it knows to include thirdparty/js/angular2/lib/* in our web archive in vendor/angular2. Providing a link to this d.ts file in a VS project makes MSBuild able to TypeScriptCompile the ts files.

I don't want engineers to be able to define their own dependencies other than linking to typings files somewhere else in the tree. I also don't want to have to download some node_modules folder I don't need on our build servers and on every engineers pc (that I then have to add to the .tfignore of course else it will probably get checked in some day). Another option is to automatically copy all source code to an intermediate folder and do the NPM install there but it seems like a real hassle to do that every single time. Also, like I said, it's not needed. We want to be dependent on a specific version of software (yes I know it can be specified) that we have in our own source control so that we can do a controlled upgrade when needed. Last but not least, this still doesn't help Visual Studio of course (where I need to link to the d.ts file).

I'm a bit lost... What is your plan for very large applications and build workflows then? How do they do it in, for example, AdWords? Currently I will stay on Alpha45 until we have a solution...

Oh, and to answer your question, I NPM installed angular2 locally and put the contents of the bundles folder in source control of course... :)

[robwormald]

@woppa684 thanks for the detailed explanation.

The preferred option for angular distribution going forward is going to be NPM. there's a few reasons for this, primarily that its used by the vast majority of the JS ecosystem already. That said, you could certainly do what you're doing (gross, though, for real... ;-)

Your actual question though is about typings, and that's a more complex thing. Typescript 1.6 introduced a new way of handling typings, and this is what we're working with. Rather than the "ambient" style modules, which look like:

declare module {}

typescript .d.ts files now mirror their source files - they're effectively ES6 version of d.ts files: (this is a snip from the http module:

import { RequestOptionsArgs, ConnectionBackend } from './interfaces';
import { Request } from './static_request';
import { RequestOptions } from './base_request_options';

export declare class Http {
    protected _backend: ConnectionBackend;
    protected _defaultOptions: RequestOptions;
    constructor(_backend: ConnectionBackend, _defaultOptions: RequestOptions);
    request(url: string | Request, options?: RequestOptionsArgs): any;
}

The first (incredibly great thing) this enables is developers to not have to mess with tsd or ///ref references. A developer starting with angular2 just does:

• tsc -init --experimentalDecorators
• npm install angular2
  and then they can simply:

import {Component} from 'angular2/angular2'

and everything pretty much works. This works because typescript's new module resolution algorithm works the same as NodeJS's, and so the NPM distribution looks like:

- angular2.js
- angular2.d.ts
-- src/foo.js
-- src/foo.d.ts

This algorithm currently assumes that your vendor code is in a node_modules folder, and so if you start shifting things around, resolution will probably fail. The TS is aware of this (JS users who prefer JSPM have the same issue) - and this issue microsoft/TypeScript#5039 is tracking progress on that - that would allow you to reconfigure the mapping as you pleased.

Now - the biggest change here is that instead of a monolithic single angular2.d.ts file, there's one d.ts file per source file - this, again, mirrors the direction of modern javascript. The ecosystem is moving away from shipping monolithic bundled blobs of code, towards distributing proper, modular code - this is something that is very much normal in modern webdev today, and it is likely to be the way of the future.

This changes the build strategy you mentioned (that is, compile everything in foo/* ) into a much more intelligent way of building. If I had a main file like

//main.ts
import {bootstrap} from 'angular2/angular2' //npm
import {SomeOtherDep} from 'my/awesome/dep' //npm
import {MyComponent} from './components/MyComponent' //local 

bootstrap(MyComponent);

Rather than saying "concat and minify all the stuff in vendor, and then concat all the stuff in ./ " - you simply say "build my application starting at main.ts" - and because the import/export syntax is understood by tooling, tools can trace the dependency tree and pull in only the referenced code to produce the final bundle - which is far more efficient (eg: if you use angular2, but not our http module, you dont need that code)

The two leaders in this bit of tooling are currently Webpack and JSPM, but TypeScript has bundling on their roadmap to accomplish the same goal.

Now - we will continue to distribute bundled JS code - but is not certainly not the preferred method for consuming angular2. As of now, there isn't a great solution for us re-bundling the d.ts files generated by TypeScript - previous to alpha 42, we had a pretty hacky manual process that caused us a lot of trouble to keep stable and up to date. There are some third party tools for that beginning to show up.

The Angular2 bundles that exist today are primarily for ES5 users, and for making plunkers and demos easier to get online, but they are not the recommended solution for (eventual!) production usage. I would strongly suggest moving towards the modern way of working with Javascript modules. I realize that's easy for me to say and less so for you to flip the switch on, but as Angular2 is trying to be forward-looking, it is where we will concentrate our efforts.

Hope that explains more that it confuses - we definitely want to enable a variety of use cases here, so happy to continue discussing if you have more questions.

(ps - use NPM. you'll love it.)

[robwormald]

p.p.s - if you're in the sort of constrained environment where you have to submit a request to use a third party dependency, NPM has the option of maintaining an internal registry (there are a number of free / open source and hosted / non-free solutions for this) - see https://www.npmjs.com/onsite for example.

This is a great option for large orgs, especially as they begin towards using ES6 and modern Javascript in general. Just a thought.

[kylecordes]

Rob - I have been following the various machinations in trying out the various alternative tools around everything you wrote about above, and by the way that was an excellent summary that should be widely distributed. But the following would also be very helpful, if it is possible.

For those cases when it is helpful to distribute a modest pile of files and have things "just work" even with typescript, we are already there, even for something like a plunkr, using JSPM. A couple of files of overhead, and Angular bundle or two, the typescript compiler itself in one file, etc. "Legacy" typings were also conveniently supplied as a single d.ts file for most libraries. That used to be available for Angular 2, until the recent division into numerous small d.ts files as you described. It would be very helpful if the Angular 2 distribution could somehow also include, or make available otherwise, a single-file d.ts to get a good typescript development experience in these cases where we would like to get up and running with just a few files. Pointless for production, but very useful for introducing people to Angular 2.