Angular2-Meteor
Angular2 + Meteor integration.
Angular2 version: beta-12.
Table of Contents
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
supportsbeta-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
!