/angular2-meteor

Angular 2.0 and Meteor - the perfect stack

Primary LanguageTypeScriptMIT LicenseMIT

Angular2-Meteor NPM version NPM downloads Build Status Join the chat at https://gitter.im/Reactive-Extensions/RxJS

Angular2 + Meteor integration.

Table of Contents

Tutorial

If you are new to Angular2 and/or Meteor but want to learn them quickly, please check out our 23-steps Angular2-Meteor tutorial.

Questions and Issues

If you have rather a question than an issue, please consider the following resources at first:

The chances to get a quick response there is higher than posting a new issue here.

If you've decided that it's likely a real issue, please consider going through the following list at first:

  • Check out common issues and troubleshoot section;
  • Check quickly recently created/closed issues: chances are high that someone's already created a similar one or similar issue's been resolved;
  • If your issue looks nontrivial, we would approciate a small demo to reproduce it. You will also get a response much faster.

Quick Start

Install package:

Before installing any Angular2-Meteor's NPMs, we recommend to have Angular 2 NPM and its peer dependencies added in your package.json. You can find such a list here. It minimizes the chance to get "unmet peer dependency" warnings in the future package updates.

After that, 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 Meteor package as well — angular2-compilers. This package adds our own HTML processor and TypeScript compiler to a Meteor app. TypeScript is a language that makes development with Angular 2 really easy, and currently the only one fully supported by the Angular2-Meteor. 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 than 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) reflect-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 the required dependencies. Since it's a package, it's loaded by Meteor before any user code.

Please don't forget to add a main HTML file (can be index.html or with any other name) even if your app template consists of one single tag, e.g., <body><app></app></body>.

Import Angular2 into your app:

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

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

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

    import {Component} from 'angular2/core';
    import {bootstrap} from 'angular2/bootstrap';

    @Component({
      selector: 'socially',
      template: "<p>Hello World!</p>"
    })
    class Socially {}

    bootstrap(Socially);

Add index.html file to the app root folder:

    <body>
       <socially></socially>
    </body>

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

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:

import {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:

    // ....

    @Component({
      templateUrl: 'client/parties.html'
    })
    class Socially {
        constructor() {
          this.parties = Parties.find();
        }
    }

    // ....

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

    <div *ngFor="#party of parties">
      <p>Name: {{party.name}}</p>
    </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:

    import {Component} from 'angular2/core';
    import {bootstrap} from 'angular2-meteor-auto-bootstrap';
    import {MeteorComponent} from 'angular2-meteor';
    import {MyCollection} form '../model/my-collection.ts';

    @Component({
      selector: 'socially'
      template: "<p>Hello World!</p>"
    })
    class Socially extends MeteorComponent {
      myData : Mongo.Cursor<any>;
    
      constructor() {
         this.myData = MyCollection.find({});
         this.subscribe('my-subscription'); // Wraps Meteor.subscribe
      }
      
      doSomething() {
         this.call('server-method'); // Wraps Meteor.call
      }
    }

    bootstrap(Socially);

You can read more about MeteorComponent in the [tutorial section] (http://www.angular-meteor.com/tutorials/socially/angular2/privacy-and-publish-subscribe-functions)!

Demos

Check out two demos for the quick how-to:

Server Side

One of the big advantages of Meteor is that you can use TypeScript and CommonJS on the server side as well.

It means that you can easily share your code between client and server!

TypeScript

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

TypeScript configuration file a.k.a. tsconfig.json is supported as well.

Please note that tsconfig.json is not required, but if you want to configure TypeScript in your IDE or add more options, place tsconfig.json in the root folder of your app. You can read about all available compiler options here.

Default TypeScript options for Meteor 1.3 are as follows:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "module": "commonjs",
    "target": "es5",
    "moduleResolution": "node",
    "emitDecoratorMetadata": true,
    "sourceMap": true
  }
}

Typings

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

For example, to install Meteor declaration file run:

npm install typings -g

typings install registry:env/meteor --ambient

Please note that you don't need to worry about Angular 2's typings and typings of the related packages! TypeScript finds and checkes them in NPMs automatically.

Common Issues and Troubleshoot

Upgrading to Meteor 1.3

Please don't use Atmosphere packages related to Angular 2 with Meteor 1.3, use NPM equivalents instead; most of these atmosphere packages were anyways converted from NPMs. The reason is that they are based on SystemJS, which won’t work with Meteor 1.3 and modules package any more.

For example, check out Angular2 Maps here.

Or, you may be interested in Angular 2 version of the Meteor Accounts UI. You can find out a preliminary version here.

It works fine locally but fails to run in the production

This UglifyJS minification issue is likely to blame, which is fixed in Angular2 beta-16.

Change Log

Change log of the package is located here.

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!

Check out CONTRIBUTION.md for more info.