Angular2-Meteor

Angular2 + Meteor integration.

Angular2 version: beta-12.

Change Log

Check out change log of the package here.

If you suddenly started facing issues or want to upgrade, please check out common issues and troubleshoot section first.

Tutorial

If you are new to Angular 2, we recommend to check out our 15-steps Angular2+Meteor tutorial.

Please note, the tutorial above is about Angular2-Meteor version for Meteor 1.2, while current README focuses more on the version for Meteor 1.3. New version is in active development now.

Quick Start

Install package:

With Meteor 1.3:

Before installing any Angular2-Meteor's NPMs, we recommend to have Angular 2 NPM and its peer dependencies added in your package.json. The list you can find here. It makes the chance to get "unmet peer dependency" warning is minimum for the future package updates.

After, you are ready to install Angular2-Meteor's NPMs:

    npm install angular2-meteor --save
    npm install angular2-meteor-auto-bootstrap --save

You'd likely prefer to install another one Meteor package as well — angular2-compilers. This package adds own HTML processor and TypeScript compiler to a Meteor app. TypeScript is a language that makes development with Angular 2 really easy, and the only one fully supported by the Angular2-Meteor currently. So one of the prerequisites will be to run:

   meteor add angular2-compilers

Please note that you'll have to remove the standard Meteor HTML processor if you have it installed. The reason is that Meteor doesn't allow more then two processor for one extension:

   meteor remove blaze-html-templates

Angular 2 heavily relies on some polyfills and dependencies. For example, in order to make it work, you'll need to load (import) reclect-metatada and zone.js before you can use any component from angular2 itself.

There is a way to overcome that inconvenience (i.e., importing dependencies manually): you can install barbatus:angular2-runtime, a package that adds all required dependencies. Since it's a package, it's loaded by Meteor before any user code.

Note that current version of barbatus:angular2-runtime supports beta-12 only. There is no guarantee that it'll work for newer versions of Angular 2.

Other notes:

Meteor 1.3 uses CommonJS implementation for modules loading so you do not need to use SystemJS or any other loader!
You'll have to add an index.html (can have any other name) even if your app template consists of one tag, e.g., <body><app></app></body>

With Meteor 1.2

   meteor add angular2-meteor

Notes:

The compilers are part of this package
Meteor 1.2 does not have modules loader, so you need to use SystemJS as modules loader (comes with this package!)

Usage

Import Angular2 into your app:

Package assumes TypeScript as the main language for development with Angular 2.

ES6 modules are supported via CommonsJS (starting in Meteor 1.3) module loader library.

To start, create client/app.ts file, import Component and then bootstrap the app:

1    import {Component} from 'angular2/core';
2    import {bootstrap} from 'angular2/bootstrap';
3
4    @Component({
5      selector: 'socially',
6      template: "<p>Hello World!</p>"
7    })
8    class Socially {}
9
10    bootstrap(Socially);

Add index.html file to the app top folder:

1    <body>
2       <socially></socially>
3    </body>

At this point you should see app working and showing "Hello word".

If you have an HTML file in the app root folder with body or head tag (index.html in our case), the package will recognize it as your master HTML file and will skip inserting a default layout. Otherwise, it'll insert bootstrap HTML as follows:

1<body>
2    <app></app>
3</body>

Also, if you name your main client component is app.ts, the package will import client/app it automatically.

(Note that if you use Meteor 1.2, you need to use SystemJS imports to load your main file!)

Start using Meteor in your Angular2 app:

This package comes with some modules that makes it easy to use Meteor in Angular 2.

You can use Meteor collections in the same way as you would do in a regular Meteor app with Blaze, you just need to use another bootstrap method, instead of the one the comes with Angular2:

1import {bootstrap} from 'angular2-meteor-auto-bootstrap';

And now you can iterate Mongo.Cursor objects with Angular 2.0 ngFor!

For example, change client/app.ts to:

1    // ....
2
3    @Component({
4      templateUrl: 'client/parties.html'
5    })
6    class Socially {
7        constructor() {
8          this.parties = Parties.find();
9        }
10    }
11
12    // ....

Add Angular2 template file client/parties.html with a content as follows:

1    <div *ngFor="#party of parties">
2      <p>Name: {{party.name}}</p>
3    </div>

At this moment, you are ready to create awesome apps backed by the power of Angular 2 and Meteor!

To use Meteor features, make sure that your components extends MeteorComponent, and you can feature that comes from Meteor:

1    import {Component} from 'angular2/core';
2    import {bootstrap} from 'angular2-meteor-auto-bootstrap';
3    import {MeteorComponent} from 'angular2-meteor';
4    import {MyCollection} form '../model/my-collection.ts';
5
6    @Component({
7      selector: 'socially'
8      template: "<p>Hello World!</p>"
9    })
10    class Socially extends MeteorComponent {
11      myData : Mongo.Cursor<any>;
12    
13      constructor() {
14         this.myData = MyCollection.find({});
15         this.subscribe('my-subscription'); // Wraps Meteor.subscribe
16      }
17      
18      doSomething() {
19         this.call('server-method'); // Wraps Meteor.call
20      }
21    }
22
23    bootstrap(Socially);

You can find more examples in the full tutorial!

Demos

Check out two demos for the quick how-to:

For Meter 1.2: the Tutorial's Socially app
For Meteor 1.3: Todos demo

Server Side

You can use TypeScript also in the server side, so you can share you interfaces with both client and server!

Similar to the client's main module app file, Meteor checks for the existence of the main file in the server folder and, in case of success, will import it for you.

TypeScript

The package uses TypeScript for Meteor to compile (transpile) .ts-files.

TypeScript configuration file a.k.a. tsconfig.json is supported as well. Place a file with this name at the root folder and start adding any available TypeScript options you want. You can read about all available compiler options [here] (https://github.com/Microsoft/TypeScript/wiki/tsconfig.json).

Default TypeScript options for Meteor 1.3 are as follows:

1{
2  "compilerOptions": {
3    "experimentalDecorators": true,
4    "module": "commonjs",
5    "target": "es5",
6    "moduleResolution": "node",
7    "emitDecoratorMetadata": true,
8    "sourceMap": true
9  }
10}

For Meteor 1.2, options are the same as above except:

1{
2  "compilerOptions": {
3    "module": "system",
4    "moduleResolution": "classic"
5  }
6}

Typings

To add declaration files of any global 3-party JavaScript library including Meteor itself (so called ambient typings), we recommend to use typings utility, which is specially designed to be used for typigns management with access to global registries of common 3-party libraries.

As for Angular 2's typings and typings of the related packages, if you plan to use Meteor 1.3 and NPM packages you don't need to worry about them at all, as most of declaration files are provided in NPMs (at least for Angular 2 itself). If you plan to use Meteor 1.2 and Atmosphere packages, all required typigns will be installed (copied) automatically into the "typings" folder during the first run.

Commong Issues and Troubleshoot

Upgrading to Meteor 1.3

If you want to upgrade to Meteor 1.3 and use CommonJS modules, but at the same time have some of the Atmosphere packages related to Angular 2 (like barbatus:g2-google-maps, barbatus:ng2-meteor-accounts-ui etc) installed, you’ll need to remove them. The reason is they are based on SystemJS, which won’t work with Meteor 1.3 and modules package any more. Use NPM equivalents instead since most of that atmosphere packages were anyways converted from NPMs.

For example, check out Angular2 Maps here. a NPM version of the Meteor Accounts UI for Angular 2 is currently under development. You can find out some preliminary version here.

It works fine locally but fails to run in the production

This UglifyJS minification issue is likely to blame. Read this comment to find out more info.

As a temporary solution, you could install barbarous:ng2-minifier-js, which configures UglifyJS to skip renaming (mangling). So you’ll need:

meteor remove standard-minifier-js
meteor add  barbatus:ng2-minifier-js

Roadmap

You can check out the package's roadmap and its status under this repository's issues.

Contribution

If you know how to make integration of Angular 2 and Meteor better, you are very welcome!

For the coding style guide, we use AirBnB rules with TypeScript specifics and max line width set to 100 symbols. Rules are partly enforced by the tslint.json file in the root (if you are not familiar with TSLint, read more here). Please, check that your code conforms with the rules before PR.

Clone the source to your computer

In order to work with this package locally when using Meteor 1.3 project, follow these instructions:

Clone this repository to any folder. Note that if you clone into Meteor project directory - you need to put the cloned folder inside a hidden file, so Meteor won't try to build it! Just create a folder that starts with . under your project root, it should look like that:

MyProject
   .local-work
      angular2-meteor
   .meteor
   client
   server
   public

Make sure that you already have node_modules directory under your root, if not — create it:
```
$ mkdir node_modules
```
Also, make sure that you have a NPM project initialized in your directory (you should have package.json), if not — use:
```
$ npm init
```
Make sure that you do not have angular2-meteor already - check under node_modules — if you do, delete it.

Now you have two options, you can specify the local copy in the package.json of your project, as follow:

1{
2   "dependencies": {
3      "angular2-meteor": "./local-work/angular2-meteor"
4   }
5}

And then make sure to run the NPM install command:

$ npm install

**Or, ** you can link the directory using NPM command like tool, as follow:

$ npm link ./local-work/angular2-meteor

Building the project from sources

In order to use your local copy of Angular2-Meteor, you have two options:

Import the TypeScript source code from the package, for example:

import {MeteorComponent} from 'angular2-meteor/modules/meteor_component.ts';

Or, you can keep the same code you have now, but you will need to build Angular2-Meteor source code each change you perform, by running gulp build.

Troubleshoot

When working with local package, note that you should never have two local packages of angular2 package, you should have it only under node_modules/angular2 of the root directory. In case of weird errors regarding missing direcrtives - make sure that you do not have a copy of angular2 package under node_modules/angular2-meteor/node_modules/angular2!

urigo:angular2-meteor