Migrating to Meteor 1.3

Edit on GitHub | Discuss on the Meteor Forums

Breaking changes

These are all the breaking changes – that is changes that you absolutely have to worry about if you are updating your app from 1.2.x to 1.3. However, we recommend that you also consider the recommended changes listed in the other sections below.

Mobile

Recommended change: use modules

The biggest new feature in Meteor 1.3 is support for ES2015 modules on the client and the server. Using modules you can declare dependencies between files, control load order, and use npm packages on the client and server easily.

1
2
import { Meteor } from 'meteor/meteor';
import { EJSON } from 'meteor/ejson';
1
meteor npm install --save meteor-node-stubs
1
2
3
4
5
6
7
8
9
10
11
12
13
api.addFiles('file.js');
// For files that are not imported elsewhere, this turns into
import './file.js';

// Remove from package.js
api.export('Foo');

// localPackage/foo.js
// Foo must be explicitly exported
export default Foo;

// client/main.js
import '/imports/localPackage';

Also, you should no longer need to use the meteorhacks:npm package.

Recommended changes: package authors

Package authors are recommended to:

Recommended changes: Testing

Meteor 1.3 includes a new command meteor test, which can be used to run tests against your app, in two modalities. You can read about these features in much more detail in the Testing Guide Article.

Full app testing

If you were previously using Velocity to run tests against your running Meteor app, the full app test mode should allow you to run your tests against 1.3, with some small changes.

Module testing

If you were previously using in-app packages in order to unit test your app, you should switch to a modules-based approach and test them using the normal test mode.

Recommended changes: Mobile

Along side some of the breaking mobile changes listed above, there are some changes in the way the mobile integration works that you should consider:

Install React from npm

In Meteor 1.3, we recommend installing react and react-dom into your app using npm, and importing them from your app code:

1
2
import React from 'react';
import ReactDOM from 'react-dom';

As mentioned in the breaking changes, the react Atmosphere package still works, but it now expects you to install the React npm packages it uses in your application (read the Using Packages article for more details about how to manage your npm dependencies):

1
2
3
4
npm install --save react react-dom react-addons-transition-group \
 react-addons-css-transition-group react-addons-linked-state-mixin \
 react-addons-create-fragment react-addons-update react-addons-pure-render-mixin \
 react-addons-test-utils react-addons-perf

However, we recommend that you should stop using the react or react-runtime Atmosphere packages and instead install React directly from npm (for more detail, see the React article of the guide). To make this change in an existing app, you can run:

1
2
3
4
5
6
meteor remove react

# if you are using our data integration
meteor add react-meteor-data

npm install --save react react-dom react-addons-pure-render-mixin

Then, in your application, you should import React directly rather than relying on a global React symbol:

1
import React from 'react';

If you are using a package that depends on the react or react-runtime Atmosphere packages, you will still need to install the full list of npm React packages above, so we encourage package authors to update their packages to import React directly from npm.

Loading data with React

The react-meteor-data has a new createContainer syntax for combining Meteor’s data system with React in an idiomatic way. We encourage you to use containers to separate your data loading concerns from your presentational components!

Install Angular from npm

With an Angular Meteor app you can safely update to Meteor 1.3 without any changes to your code.
You just need to make sure you are using the latest angular Atmosphere package 1.3.9_2.

But, in Meteor 1.3, we recommend installing angular and angular-meteor into your app using npm:

1
npm install --save angular angular-meteor

and importing them from your app code:

1
2
import angular from 'angular';
import angular-meteor from 'angular-meteor';

Read the Using Packages article for more details about how to manage your npm dependencies.

If you already using the Atmosphere packages and want to move to the npm packages, you will need to remove the Atmosphere packages first but keep the angular-templates Atmosphere package:

1
2
3
4
meteor remove angular
meteor add angular-templates

npm install --save angular angular-meteor

Then, in your application, you should import angular directly rather than relying on global angular:

1
2
import angular from 'angular';
import angular-meteor from 'angular-meteor';

Existing Angular Atmosphere packages

If you are a package author that depends on the angular:angular Atmosphere package, you can support both Meteor 1.2 and 1.3 so your users will have an easy and unbreaking update process:

Change your angular:angular dependency into a weak dependency:

1
api.use('angular:angular@1.5.3', 'client', { weak: true });

and then add a dependency check for both Meteor 1.2 and 1.3 before initializing your angular module:

1
2
3
4
5
6
7
8
9
10
11
12
if (!window.angular) {
  try {
    if (Package['modules-runtime']) {
      var require = Package['modules-runtime'].meteorInstall();
      require('angular');
    }
  } catch(e) {
    throw new Error('angular package is missing');
  }
}

angular.module('your.module', []);

New guide articles

As part of the 1.3 release, we have some new guide articles and updated sections of existing articles:

← Application structure Collections and Schemas →

Edit this page on GitHub