The Gitbook Meteor Guide | Java Script | Application Software

Table of Contents Introduction

1.1

Introduction

1.2

Code style

1.3

Application Structure

1.4

Migrating to Meteor 1.4

1.5

Migrating to Meteor 1.3

1.6

Collections and Schemas

1.7

Publications and Data Loading

1.8

Methods

1.9

Users and Accounts

1.10

Testing

1.11

URLs and Routing

1.12

User Interfaces

1.13

Blaze

1.14

React

1.15

Angular

1.16

Atmosphere vs. npm

1.17

Using Atmosphere Packages

1.18

Writing Atmosphere Packages

1.19

Using npm Packages

1.20

Writing npm Packages

1.21

Mobile

1.22

Build system

1.23

Security

1.24

Deployment and Monitoring

1.25

1

Introduction

Meteor Guide The Gitbook version of the Meteor Guide http://guide.meteor.com/

2

Introduction

What is Meteor? Meteor is a full-stack JavaScript platform for developing modern web and mobile applications. Meteor includes a key set of technologies for building connected-client reactive applications, a build tool, and a curated set of packages from the Node.js and general JavaScript community. Meteor allows you to develop in one language, JavaScript, in all environments: application server, web browser, and mobile device. Meteor uses data on the wire, meaning the server sends data, not HTML, and the client renders it. Meteor embraces the ecosystem, bringing the best parts of the extremely active JavaScript community to you in a careful and considered way. Meteor provides full stack reactivity, allowing your UI to seamlessly reflect the true state of the world with minimal development effort.

Quick start Meteor supports OS X, Windows, and Linux. On Windows? Download the official Meteor installer here. On OS X or Linux? Install the latest official Meteor release from your terminal: curl https://install.meteor.com/ | sh

The Windows installer supports Windows 7, Windows 8.1, Windows Server 2008, and Windows Server 2012. The command line installer supports Mac OS X 10.7 (Lion) and above, and Linux on x86 and x86_64 architectures. Once you've installed Meteor, create a project: meteor create myapp

Run it locally:

3

Introduction

cd myapp meteor npm install meteor # Meteor server running on: http://localhost:3000/

Meteor comes with npm bundled so that you can type meteor npm without worrying about installing it yourself. If you like, you can also use a globally installed npm to manage your packages.

Meteor resources 1. The place to get started with Meteor is the official tutorial. 2. Stack Overflow is the best place to ask (and answer!) technical questions. Be sure to add the meteor tag to your question. 3. Visit the Meteor discussion forums to announce projects, get help, talk about the community, or discuss changes to core. 4. The Meteor docs is the best place to find the core API documentation of the platform. 5. Atmosphere is the repository of community packages designed especially for Meteor. 6. Awesome Meteor is a community-curated list of packages and resources.

What is the Meteor Guide? This is a set of articles outlining opinions on best-practice application development using the Meteor platform. Our aim is to cover patterns that are common to the development of all modern web and mobile applications, so many concepts documented here are not necessarily Meteor specific and could be applied to any application built with a focus on modern, interactive user interfaces. Nothing in the Meteor guide is required to build a Meteor application---you can certainly use the platform in ways that contradict the principles and patterns of the guide. However, the guide is an attempt to document best practices and community conventions, so we hope that the majority of the Meteor community will benefit from adopting the practices documented here. The APIs of the Meteor platform are available at the docs site, and you can browse community packages on atmosphere.

4

Introduction

Target audience The guide is targeted towards intermediate developers that have some familiarity with JavaScript, the Meteor platform, and web development in general. If you are just getting started with Meteor, we recommend starting with the official tutorial.

Example app Many articles reference the Todos example application. This code is being actively developed alongside the guide. You can see the latest source code for the app, and file issues or make suggestions via pull request at its GitHub repository.

Guide development Contributing Ongoing Meteor Guide development takes place in the open on GitHub. We encourage pull requests and issues to discuss problems with and changes that could be made to the content. We hope that keeping our process open and honest will make it clear what we plan to include in the guide and what changes will be coming in future Meteor versions.

Goals of the project The decisions made and practices outlined in the guide must necessarily be opinionated. Certain best practices will be highlighted and other valid approaches ignored. We aim to reach community consensus around major decisions but there will always be other ways to solve problems when developing your application. We believe it's important to know what the "standard" way to solve a problem is before branching out to other options. If an alternate approach proves itself superior, then it should make its way into a future version of the guide. An important function of the guide is to shape future development in the Meteor platform. By documenting best practices, the guide shines a spotlight on areas of the platform that could be better, easier, or more performant, and thus will be used to focus a lot of future platform choices. Similarly, gaps in the platform highlighted by the guide can often be plugged by community packages; we hope that if you see an opportunity to improve the Meteor workflow by writing a package, that you take it! If you're not sure how best to design or architect your package, reach out on the forums and start a discussion.

5

Introduction

6

Code style

After reading this article, you'll know: 1. Why it's a good idea to have consistent code style 2. Which style guide we recommend for JavaScript code 3. How to set up ESLint to check code style automatically 4. Style suggestions for Meteor-specific patterns, such as Methods, publications, and more

Benefits of consistent style Countless hours have been spent by developers throughout the years arguing over single vs. double quotes, where to put brackets, how many spaces to type, and all kinds of other cosmetic code style questions. These are all questions that have at best a tangential relationship to code quality, but are very easy to have opinions about because they are so visual. While it's not necessarily important whether your code base uses single or double quotes for string literals, there are huge benefits to making that decision once and having it be consistent across your organization. These benefits also apply to the Meteor and JavaScript development communities as a whole.

Easy to read code The same way that you don't read English sentences one word at a time, you don't read code one token at a time. Mostly you just look at the shape of a certain expression, or the way it highlights in your editor, and assume what it does. If the style of every bit of code is consistent, that ensures that bits of code that look the same actually are the same - there isn't any hidden punctuation or gotchas that you don't expect, so you can focus on understanding the logic instead of the symbols. One example of this is indentation - while in JavaScript, indentation is not meaningful, it's helpful to have all of your code consistently indented so that you don't need to read all of the brackets in detail to see what is going on. // This code is misleading because it looks like both statements // are inside the conditional. if (condition) firstStatement(); secondStatement();

7

Code style

// Much clearer! if (condition) { firstStatement(); } secondStatement();

Automatic error checking Having a consistent style means that it's easier to adopt standard tools for error checking. For example, if you adopt a convention that you must always use let or const instead of var , you can now use a tool to ensure all of your variables are scoped the way you expect.

That means you can avoid bugs where variables act in unexpected ways. Also, by enforcing that all variables are declared before use, you can easily catch typos before even running any code!

Deeper understanding It's hard to learn everything about a programming language at once. For example, programmers new to JavaScript often struggle with the var keyword and function scope. Using a community-recommended coding style with automatic linting can warn you about these pitfalls proactively. This means you can jump right into coding without learning about all of the edge cases of JavaScript ahead of time. As you write more code and come up against the recommended style rules, you can take that as an opportunity to learn more about your programming language and how different people prefer to use it.

JavaScript style guide Here at Meteor, we strongly believe that JavaScript is the best language to build web applications, for a variety of reasons. JavaScript is constantly improving, and the standards around ES2015 have really brought together the JavaScript community. Here are our recommendations about how to use ES2015 JavaScript in your app today.

8

Code style

An example of refactoring from JavaScript to ES2015

Use the `ecmascript` package ECMAScript, the language standard on which every browser's JavaScript implementation is based, has moved to yearly standards releases. The newest complete standard is ES2015, which includes some long-awaited and very significant improvements to the JavaScript language. Meteor's ecmascript package compiles this standard down to regular JavaScript that all browsers can understand using the popular Babel compiler. It's fully backwards compatible to "regular" JavaScript, so you don't have to use any new features if you don't want to. We've put a lot of effort into making advanced browser features like source maps work great with this package, so that you can debug your code using your favorite developer tools without having to see any of the compiled output. The ecmascript package is included in all new apps and packages by default, and compiles all files with the .js file extension automatically. See the list of all ES2015 features supported by the ecmascript package. To get the full experience, you should also use the es5-shim package which is included in all new apps by default. This means you can rely on runtime features like Array#forEach without worrying about which browsers support them. All of the code samples in this guide and future Meteor tutorials will use all of the new ES2015 features. You can also read more about ES2015 and how to get started with it on the Meteor Blog: Getting started with ES2015 and Meteor Set up Sublime Text for ES2015 How much does ES2015 cost?

9

Code style

Follow a JavaScript style guide We recommend choosing and sticking to a JavaScript style guide and enforcing it with tools. A popular option that we recommend is the Airbnb style guide with the ES6 extensions (and optionally React extensions).

Check your code with ESLint "Code linting" is the process of automatically checking your code for common errors or style problems. For example, ESLint can determine if you have made a typo in a variable name, or some part of your code is unreachable because of a poorly written if condition. We recommend using the Airbnb eslint configuration which verifies the Airbnb styleguide. Below, you can find directions for setting up automatic linting at many different stages of development. In general, you want to run the linter as often as possible, because it's the fastest and easiest way to identify typos and small errors.

Installing and running ESLint To setup ESLint in your application, you can install the following npm packages: meteor npm install --save-dev babel-eslint eslint-config-airbnb eslint-plugin-import e slint-plugin-meteor eslint-plugin-react eslint-plugin-jsx-a11y eslint-import-resolvermeteor eslint

Meteor comes with npm bundled so that you can type meteor npm without worrying about installing it yourself. If you like, you can also use a globally installed npm command. You can also add a eslintConfig section to your package.json to specify that you'd like to use the Airbnb config, and to enable ESLint-plugin-Meteor. You can also setup any extra rules you want to change, as well as adding a lint npm command:

10

Code style

{ ... "scripts": { "lint": "eslint .", "pretest": "npm run lint --silent" }, "eslintConfig": { "parser": "babel-eslint", "parserOptions": { "allowImportExportEverywhere": true }, "plugins": [ "meteor" ], "extends": [ "airbnb", "plugin:meteor/recommended" ], "settings": { "import/resolver": "meteor" }, "rules": {} } }

To run the linter, you can now simply type: meteor npm run lint

For more details, read the Getting Started directions from the ESLint website.

Integrating with your editor Linting is the fastest way to find potential bugs in your code. Running a linter is usually faster than running your app or your unit tests, so it's a good idea to run it all the time. Setting up linting in your editor can seem annoying at first since it will complain often when you save poorly-formatted code, but over time you'll develop the muscle memory to just write wellformatted code in the first place. Here are some directions for setting up ESLint in different editors:

Sublime Text You can install the Sublime Text packages that integrate them into the text editor. It's generally recommended to use Package Control to add these packages. If you already have that setup, you can just add the these packages by name; if not, click the instructions links:

11

Code style

Babel (for syntax highlighting – full instructions) SublimeLinter (full instructions) SublimeLinter-contrib-eslint (full instructions) To get proper syntax highlighting, go to a .js file, then select the following through the View dropdown menu: Syntax -> Open all with current extension as... -> Babel -> JavaScript (Babel). If you are using React .jsx files, do the same from a .jsx file. If it's working, you will see "JavaScript (Babel)" in the lower right hand corner of the window when you are on one of these files. Refer to the package readme for information on compatible color schemes. A side note for Emmet users: You can use \ to expand HTML tags in .jsx files, and it will correctly expand classes to React's "className" property. You can bind to the tab key for this, but you may not want to.

Atom Using ESLint with Atom is simple. Just install these three packages: apm install language-babel apm install linter apm install linter-eslint

Then restart (or reload by pressing Ctrl+Alt+R / Cmd+Opt+R) Atom to activate linting.

WebStorm WebStorm provides these instructions for using ESLint. After you install the ESLint Node packages and set up your package.json , just enable ESLint and click "Apply". You can configure how WebStorm should find your .eslintrc file, but on my machine it worked without any changes. It also automatically suggested switching to "JSX Harmony" syntax highlighting.

12

Code style

Linting can be activated on WebStorm on a project-by-project basis, or you can set ESLint as a default under Editor > Inspections, choosing the Default profile, checking "ESLint", and applying.

Visual Studio Code Using ESLint in VS Code requires installation of the 3rd party ESLint extension. In order to install the extension, follow these steps: 1. Launch VS Code and open the quick open menu by typing Ctrl+P 2. Paste ext install vscode-eslint in the command window and press Enter 3. Restart VS Code

Meteor code style The section above talked about JavaScript code in general - you can easily apply it in any JavaScript application, not just with Meteor apps. However, there are some style questions that are Meteor-specific, in particular how to name and structure all of the different components of your app.

Collections Collections should be named as a plural noun, in PascalCase. The name of the collection in the database (the first argument to the collection constructor) should be the same as the name of the JavaScript symbol.

13

Code style

// Defining a collection Lists = new Mongo.Collection('Lists');

Fields in the database should be camelCased just like your JavaScript variable names. // Inserting a document with camelCased field names Widgets.insert({ myFieldName: 'Hello, world!', otherFieldName: 'Goodbye.' });

Methods and publications Method and publication names should be camelCased, and namespaced to the module they are in: // in imports/api/todos/methods.js updateText = new ValidatedMethod({ name: 'todos.updateText', // ... });

Note that this code sample uses the ValidatedMethod package recommended in the Methods article. If you aren't using that package, you can use the name as the property passed to Meteor.methods . Here's how this naming convention looks when applied to a publication: // Naming a publication Meteor.publish('lists.public', function listsPublic() { // ... });

Files, exports, and packages You should use the ES2015 import and export features to manage your code. This will let you better understand the dependencies between different parts of your code, and it will be easy to know where to look if you need to read the source code of a dependency. Each file in your app should represent one logical module. Avoid having catch-all utility modules that export a variety of unrelated functions and symbols. Often, this can mean that it's good to have one class, UI component, or collection per file, but there are cases where it

14

Code style

is OK to make an exception, for example if you have a UI component with a small subcomponent that isn't used outside of that file. When a file represents a single class or UI component, the file should be named the same as the thing it defines, with the same capitalization. So if you have a file that exports a class: export default class ClickCounter { ... }

This class should be defined inside a file called ClickCounter.js . When you import it, it'll look like this: import ClickCounter from './ClickCounter.js';

Note that imports use relative paths, and include the file extension at the end of the file name. For Atmosphere packages, as the older pre-1.3 api.export syntax allowed more than one export per package, you'll tend to see non-default exports used for symbols. For instance: // You'll need to destructure here, as Meteor could export more symbols import { Meteor } from 'meteor/meteor'; // This will not work import Meteor from 'meteor/meteor';

Templates and components Since Spacebars templates are always global, can't be imported and exported as modules, and need to have names that are completely unique across the whole app, we recommend naming your Blaze templates with the full path to the namespace, separated by underscores. Underscores are a great choice in this case because then you can easily type the name of the template as one symbol in JavaScript. ...

If this template is a "smart" component that loads server data and accesses the router, append _page to the name:

15

Code style

...

Often when you are dealing with templates or UI components, you'll have several closely coupled files to manage. They could be two or more of HTML, CSS, and JavaScript files. In this case, we recommend putting these together in the same directory with the same name: # The Lists_show template from the Todos example app has 3 files: show.html show.js show.less

The whole directory or path should indicate that these templates are related to the Lists module, so it's not necessary to reproduce that information in the file name. Read more about directory structure below. If you are writing your UI in React, you don't need to use the underscore-split names because you can import and export your components using the JavaScript module system.

16

Application Structure

After reading this article, you'll know: 1. How a Meteor application compares to other types of applications in terms of file structure. 2. How to organize your application both for small and larger applications. 3. How to format your code and name the parts of your application in consistent and maintainable ways.

Universal JavaScript Meteor is a full-stack framework for building JavaScript applications. This means Meteor applications differ from most applications in that they include code that runs on the client, inside a web browser or Cordova mobile app, code that runs on the server, inside a Node.js container, and common code that runs in both environments. The Meteor build tool allows you to easily specify what JavaScript code, including any supporting UI templates, CSS rules, and static assets, to run in each environment using a combination of ES2015 import and export and the Meteor build system default file load order rules.

ES2015 modules As of version 1.3, Meteor ships with full support for ES2015 modules. The ES2015 module standard is the replacement for CommonJS and AMD, which are commonly used JavaScript module format and loading systems. In ES2015, you can make variables available outside a file using the export keyword. To use the variables somewhere else, you must import them using the path to the source. Files that export some variables are called "modules", because they represent a unit of reusable code. Explicitly importing the modules and packages you use helps you write your code in a modular way, avoiding the introduction of global symbols and "action at a distance". Since this is a new feature introduced in Meteor 1.3, you will find a lot of code online that uses the older, more centralized conventions built around packages and apps declaring global symbols. This old system still works, so to opt-in to the new module system code must be placed inside the imports/ directory in your application. We expect a future release of Meteor will turn on modules by default for all code, because this is more aligned with how developers in the wider JavaScript community write their code. You can read about the module system in detail in the modules package README. This package is automatically included in every new Meteor app as part of the ecmascript metapackage, so most apps won't need to do anything to start using modules right away.

17

Application Structure

Introduction to using `import` and `export` Meteor allows you to import not only JavaScript in your application, but also CSS and HTML to control load order: import '../../api/lists/methods.js'; // import from relative path import '/imports/startup/client'; // import module with index.js from absolute path import './loading.html'; // import Blaze compiled HTML from relative path import '/imports/ui/style.css'; // import CSS from absolute path

For more ways to import styles, see the Build System article. Meteor also supports the standard ES2015 modules export syntax: export const listRenderHold = LaunchScreen.hold(); // named export export { Todos }; // named export export default Lists; // default export export default new Collection('lists'); // default export

Importing from packages In Meteor, it is also simple and straightforward to use the import syntax to load npm packages on the client or server and access the package's exported symbols as you would with any other module. You can also import from Meteor Atmosphere packages, but the import path must be prefixed with meteor/ to avoid conflict with the npm package namespace. For example, to import moment from npm and HTTP from Atmosphere: import moment from 'moment'; // default import from npm import { HTTP } from 'meteor/http'; // named import from Atmosphere

For more details using imports with packages see Using Packages in the Meteor Guide.

Using `require` In Meteor, import statements compile to CommonJS require syntax. However, as a convention we encourage you to use import . With that said, in some situations you may need to call out to require directly. One notable example is when requiring client or server-only code from a common file. As import s must be at the top-level scope, you may not place them within an if statement, so you'll need to write code like:

18

Application Structure

if (Meteor.isClient) { require('./client-only-file.js'); }

Note that dynamic calls to require() (where the name being required can change at runtime) cannot be analyzed correctly and may result in broken client bundles. If you need to require from an ES2015 module with a default export, you can grab the export with require("package").default . Another situation where you'll need to use require is in CoffeeScript files. As CS doesn't support the import syntax yet, you should use require : { FlowRouter } = require 'meteor/kadira:flow-router' React = require 'react'

Exporting with CoffeeScript When using CoffeeScript, not only the syntax to import variables is different, but also the export has to be done in a different way. Variables to be exported are put in the exports object: exports.Lists = ListsCollection 'Lists'

File structure To fully use the module system and ensure that our code only runs when we ask it to, we recommend that all of your application code should be placed inside the imports/ directory. This means that the Meteor build system will only bundle and include that file if it is referenced from another file using an import (also called "lazy evaluation or loading"). Meteor will load all files outside of any directory named imports/ in the application using the default file load order rules (also called "eager evaluation or loading"). It is recommended that you create exactly two eagerly loaded files, client/main.js and server/main.js , in order to define explicit entry points for both the client and the server. Meteor ensures that any file in any directory named server/ will only be available on the server, and likewise for files in any directory named client/ . This also precludes trying to import a file to be used on the server from any directory named client/ even if it is nested in an imports/ directory and vice versa for importing client files from server/ .

19

Application Structure

These main.js files won't do anything themselves, but they should import some startup modules which will run immediately, on client and server respectively, when the app loads. These modules should do any configuration necessary for the packages you are using in your app, and import the rest of your app's code.

Example directory layout To start, let's look at our Todos example application, which is a great example to follow when structuring your app. Here's an overview of its directory structure: imports/ startup/ client/ index.js # import client startup through a single index entry po int routes.js # set up all routes in the app useraccounts-configuration.js # configure login templates server/ fixtures.js # fill the DB with example data on startup index.js # import server startup through a single index entry po int api/ lists/ # a unit of domain logic server/ publications.js # all list-related publications publications.tests.js # tests for the list publications lists.js # definition of the Lists collection lists.tests.js # tests for the behavior of that collection methods.js # methods related to lists methods.tests.js # tests for those methods ui/ components/ # all reusable components in the application # can be split by domain if there are many layouts/ # wrapper components for behaviour and visuals pages/ # entry points for rendering used by the router client/ main.js # client entry point, imports all client code server/ main.js # server entry point, imports all server code

Structuring imports

20

Application Structure

Now that we have placed all files inside the imports/ directory, let's think about how best to organize our code using modules. It makes sense to put all code that runs when your app starts in an imports/startup directory. Another good idea is splitting data and business logic from UI rendering code. We suggest using directories called imports/api and imports/ui for this logical split.

Within the imports/api directory, it's sensible to split the code into directories based on the domain that the code is providing an API for --- typically this corresponds to the collections you've defined in your app. For instance in the Todos example app, we have the imports/api/lists and imports/api/todos domains. Inside each directory we define the

collections, publications and methods used to manipulate the relevant domain data. Note: in a larger application, given that the todos themselves are a part of a list, it might make sense to group both of these domains into a single larger "list" module. The Todos example is small enough that we need to separate these only to demonstrate modularity. Within the imports/ui directory it typically makes sense to group files into directories based on the type of UI side code they define, i.e. top level pages , wrapping layouts , or reusable components .

For each module defined above, it makes sense to co-locate the various auxiliary files with the base JavaScript file. For instance, a Blaze UI component should have its template HTML, JavaScript logic, and CSS rules in the same directory. A JavaScript module with some business logic should be co-located with the unit tests for that module.

Startup files Some of your code isn't going to be a unit of business logic or UI, it's just some setup or configuration code that needs to run in the context of the app when it starts up. In the Todos example app, the imports/startup/client/useraccounts-configuration.js file configures the useraccounts login templates (see the Accounts article for more information about useraccounts ). The imports/startup/client/routes.js configures all of the routes and then

imports all other code that is required on the client:

21

Application Structure

import { FlowRouter } from 'meteor/kadira:flow-router'; import { BlazeLayout } from 'meteor/kadira:blaze-layout'; import { AccountsTemplates } from 'meteor/useraccounts:core'; // Import to load these templates import '../../ui/layouts/app-body.js'; import '../../ui/pages/root-redirector.js'; import '../../ui/pages/lists-show-page.js'; import '../../ui/pages/app-not-found.js'; // Import to override accounts templates import '../../ui/accounts/accounts-templates.js'; // Below here are the route definitions

We then import both of these files in imports/startup/client/index.js : import './useraccounts-configuration.js'; import './routes.js';

This makes it easy to then import all the client startup code with a single import as a module from our main eagerly loaded client entry point client/main.js : import '/imports/startup/client';

On the server, we use the same technique of importing all the startup code in imports/startup/server/index.js :

// This defines a starting set of data to be loaded if the app is loaded with an empty db. import '../imports/startup/server/fixtures.js'; // This file configures the Accounts package to define the UI of the reset password em ail. import '../imports/startup/server/reset-password-email.js'; // Set up some rate limiting and other important security settings. import '../imports/startup/server/security.js'; // This defines all the collections, publications and methods that the application pro vides // as an API to the client. import '../imports/api/api.js';

22

Application Structure

Our main server entry point server/main.js then imports this startup module. You can see that here we don't actually import any variables from these files - we just import them so that they execute in this order.

Importing Meteor "pseudo-globals" For backwards compatibility Meteor 1.3 still provides Meteor's global namespacing for the Meteor core package as well as for other Meteor packages you include in your application. You can also still directly call functions such as Meteor.publish , as in previous versions of Meteor, without first importing them. However, it is recommended best practice that you first load all the Meteor "pseudo-globals" using the import { Name } from 'meteor/package' syntax before using them. For instance: import { Meteor } from 'meteor/meteor'; import { EJSON } from 'meteor/ejson';

Default file load order Even though it is recommended that you write your application to use ES2015 modules and the imports/ directory, Meteor 1.3 continues to support eager loading of files, using these default load order rules, to provide backwards compatibility with applications written for Meteor 1.2 and earlier. You may combine both eager loading and lazy loading using import in a single app. Any import statements are evaluated in the order they are listed in a file when that file is loaded and evaluated using these rules. There are several load order rules. They are applied sequentially to all applicable files in the application, in the priority given below: 1. HTML template files are always loaded before everything else 2. Files beginning with main. are loaded last 3. Files inside any lib/ directory are loaded next 4. Files with deeper paths are loaded next 5. Files are then loaded in alphabetical order of the entire path

23

Application Structure

nav.html main.html client/lib/methods.js client/lib/styles.js lib/feature/styles.js lib/collections.js client/feature-y.js feature-x.js client/main.js

For example, the files above are arranged in the correct load order. main.html is loaded second because HTML templates are always loaded first, even if it begins with main. , since rule 1 has priority over rule 2. However, it will be loaded after nav.html because rule 2 has priority over rule 5. client/lib/styles.js and lib/feature/styles.js have identical load order up to rule 4;

however, since client comes before lib alphabetically, it will be loaded first. You can also use Meteor.startup to control when run code is run on both the server and the client.

Special directories By default, any JavaScript files in your Meteor application folder are bundled and loaded on both the client and the server. However, the names of the files and directories inside your project can affect their load order, where they are loaded, and some other characteristics. Here is a list of file and directory names that are treated specially by Meteor: imports Any directory named imports/ is not loaded anywhere and files must be imported using import . node_modules Any directory named node_modules/ is not loaded anywhere. node.js packages installed into node_modules directories must be imported using import or by using Npm.depends in package.js .

client Any directory named client/ is not loaded on the server. Similar to wrapping your code in if (Meteor.isClient) { ... } . All files loaded on the client are automatically concatenated and minified when in production mode. In development mode, JavaScript

24

Application Structure

and CSS files are not minified, to make debugging easier. CSS files are still combined into a single file for consistency between production and development, because changing the CSS file's URL affects how URLs in it are processed. HTML files in a Meteor application are treated quite a bit differently from a serverside framework. Meteor scans all the HTML files in your directory for three top-level elements: , , and . The head and body sections are separately concatenated into a single head and body, which are transmitted to the client on initial page load. server Any directory named server/ is not loaded on the client. Similar to wrapping your code in if (Meteor.isServer) { ... } , except the client never even receives the code. Any sensitive code that you don't want served to the client, such as code containing passwords or authentication mechanisms, should be kept in the server/ directory. Meteor gathers all your JavaScript files, excluding anything under the client , public , and private subdirectories, and loads them into a Node.js server instance. In Meteor, your server code runs in a single thread per request, not in the asynchronous callback style typical of Node. public All files inside a top-level directory called public/ are served as-is to the client. When referencing these assets, do not include public/ in the URL, write the URL as if they were all in the top level. For example, reference public/bg.png as . This is the best place for favicon.ico , robots.txt , and similar files.

private All files inside a top-level directory called private/ are only accessible from server code and can be loaded via the Assets API. This can be used for private data files and any files that are in your project directory that you don't want to be accessible from the outside. client/compatibility This folder is for compatibility with JavaScript libraries that rely on variables declared with var at the top level being exported as globals. Files in this directory are executed without being wrapped in a new variable scope. These files are executed before other client-side JavaScript files. It is recommended to use npm for 3rd party JavaScript libraries and use import to control when files are loaded.

25

Application Structure

tests Any directory named tests/ is not loaded anywhere. Use this for any test code you want to run using a test runner outside of Meteor's built-in test tools. The following directories are also not loaded as part of your app code: Files/directories whose names start with a dot, like .meteor and .git packages/ : Used for local packages cordova-build-override/ : Used for advanced mobile build customizations programs : For legacy reasons

Files outside special directories All JavaScript files outside special directories are loaded on both the client and the server. Meteor provides the variables Meteor.isClient and Meteor.isServer so that your code can alter its behavior depending on whether it's running on the client or the server. CSS and HTML files outside special directories are loaded on the client only and cannot be used from server code.

Splitting into multiple apps If you are writing a sufficiently complex system, there can come a time where it makes sense to split your code up into multiple applications. For example you may want to create a separate application for the administration UI (rather than checking permissions all through the admin part of your site, you can check once), or separate the code for the mobile and desktop versions of your app. Another very common use case is splitting a worker process away from your main application so that expensive jobs do not impact the user experience of your visitors by locking up a single web server. There are some advantages of splitting your application in this way: Your client JavaScript bundle can be significantly smaller if you separate out code that a specific type of user will never use. You can deploy the different applications with different scaling setups and secure them differently (for instance you might restrict access to your admin application to users behind a firewall). You can allow different teams at your organization to work on the different applications independently.

26

Application Structure

However there are some challenges to splitting your code in this way that should be considered before jumping in.

Sharing code The primary challenge is properly sharing code between the different applications you are building. The simplest approach to deal with this issue is to simply deploy the same application on different web servers, controlling the behavior via different settings. This approach allows you to easily deploy different versions with different scaling behavior but doesn't enjoy most of the other advantages stated above. If you want to create Meteor applications with separate code, you'll have some modules that you'd like to share between them. If those modules are something the wider world could use, you should consider publishing them to a package system, either npm or Atmosphere, depending on whether the code is Meteor-specific or otherwise. If the code is private, or of no interest to others, it typically makes sense to simply include the same module in both applications (you can do this with private npm modules). There are several ways to do this: a straightforward approach is simply to include the common code as a git submodule of both applications. alternatively, if you include both applications in a single repository, you can use symbolic links to include the common module inside both apps.

Sharing data Another important consideration is how you'll share the data between your different applications. The simplest approach is to point both applications at the same MONGO_URL and allow both applications to read and write from the database directly. This works well thanks to Meteor's support for reactivity through the database. When one app changes some data in MongoDB, users of any other app connected to the database will see the changes immediately thanks to Meteor's livequery. However, in some cases it's better to allow one application to be the master and control access to the data for other applications via an API. This can help if you want to deploy the different applications on different schedules and need to be conservative about how the data changes.

27

Application Structure

The simplest way to provide a server-server API is to use Meteor's built-in DDP protocol directly. This is the same way your Meteor client gets data from your server, but you can also use it to communicate between different applications. You can use DDP.connect() to connect from a "client" server to the master server, and then use the connection object returned to make method calls and read from publications.

Sharing accounts If you have two servers that access the same database and you want authenticated users to make DDP calls across the both of them, you can use the resume token set on one connection to login on the other. If your user has connected to server A, then you can use DDP.connect() to open a connection to server B, and pass in server A's resume token to authenticate on server B. As both servers are using the same DB, the same server token will work in both cases. The code to authenticate looks like this: // This is server A's token as the default `Accounts` points at our server const token = Accounts._storedLoginToken(); // We create a *second* accounts client pointing at server B const app2 = DDP.connect('url://of.server.b'); const accounts2 = new AccountsClient({ connection: app2 }); // Now we can login with the token. Further calls to `accounts2` will be authenticated accounts2.loginWithToken(token);

You can see a proof of concept of this architecture in an example repository.

28

Migrating to Meteor 1.4

Breaking changes These are all the breaking changes — that is, changes you absolutely have to worry about if you are updating your app from 1.3.x to 1.4. However, we recommend that you also consider the recommended changes listed below.

Binary Packages require a Build Toolchain The headline feature of Meteor 1.4 is the upgrade to Node version 4.4.7. Node 4 includes a changed ABI (application binary interface), which means that binary npm packages that your application uses will need to be recompiled. Some very common binary packages (such as npm-bcrypt ) will already have been republished for the Node 4 platform, so if you are using a limited set of packages, this may not affect you; however if you are using less common dependencies, this may be an issue. If you have binary npm packages in your application node_modules directory, you should run meteor npm rebuild (after meteor update ) in your application directory to recompile those

packages. Meteor will automatically recompile any binary npm dependencies of Meteor packages, if they were not already compiled with the correct ABI. This will typically happen the first time you start your application after updating to 1.4, but it may also happen when you meteor add some:package that was published using a different version of Meteor and/or Node.

In order for this rebuilding to work, you will need to install a basic compiler toolchain on your development machine. Specifically, OS X users should install the commandline tools (in short, run xcode-select -install ).

Windows users should install the MS Build Tools. Linux users should ensure they have Python 2.7, make and a C compiler (g++) installed. To test that your compiler toolchain is installed and working properly, try installing any binary npm package in your application using meteor npm . For example, run meteor npm install bcrypt then meteor node , then try calling require("bcrypt") from the Node shell.

Update from MongoDB 2.4

29

Migrating to Meteor 1.4

Meteor has been updated to use version 2.2.4 of the node MongoDB driver. This means Meteor now ships with full support for MongoDB 3.2 (the latest stable version) and the WiredTiger storage engine. We recommend you update your application to MongoDB 3.2. If you are currently using MongoDB 2.4, please note that the version has reached end-of-life and you should at the least update to version 2.6. Version 2.6 is the minimum version supported by Meteor 1.4. Updating your database to 2.6 is generally pretty painless. Please consult the MongoDB documentation for details about how to do so. As of 1.4, you must ensure your MONGO_OPLOG_URL contains a replicaSet argument (see the changelog and the oplog documentation). NOTE: Some MongoDB hosting providers may have a deployment setup that doesn't require you to use a replicaSet argument. For example, Compose.io has two types of deployments, MongoDB Classic and MongoDB+. The new MongoDB+ offering is a sharded setup and not a true replica set (despite the shard being implemented as a replica set) so it does not require the replicaSet parameter and Meteor will throw an error if you add it to your connection strings. If you see a failed authentication you may need to upgrade to SCRAM-SHA-1, essentially: use admin, db.adminCommand({authSchemaUpgrade: 1}); . You may need to delete and re-add your oplog reader user.

Remove debugger statements Due to changes in Node 4, if you have `debugger` statements in your code they will now hit the breakpoint even without a debugger attached. This also means you can now debug without using the `--debug-brk` option.

Password reset and enrollment tokens now expire Password Reset tokens now expire (after 3 days by default -- can be modified via Accounts.config({ passwordResetTokenExpirationInDays: ...}). [PR #7534] (https://github.com/meteor/meteor/pull/7534) See [PR #7794] (https://github.com/meteor/meteor/issues/7794) for infomation about splitting reset vs enrollment tokens and allowing different expiration times.

Recommendations Update to Meteor 1.3.5.1 first 30

Migrating to Meteor 1.4

Though not mandatory, it may be helpful to update your apps to Meteor 1.3.5.1 before updating to 1.4, since 1.3.5.1 is the most recent release before 1.4, and contains much of the same code as 1.4. To update an app to 1.3.5.1, run meteor update --release 1.3.5.1 in the app directory. When you are confident the app is working correctly, meteor update will take you all the way to Meteor 1.4.

Update to MongoDB 3.2 Although Meteor 1.4 supports MongoDB 2.6 and up, as well as the older MMAPv1 storage engine, we recommend you update your database to use the new WiredTiger storage engine and use MongoDB 3.2. To update your production database to version 3.2 you should follow the steps listed in the MongoDB documentation. To update your storage engine, you should ensure you follow the "Change Storage Engine to WiredTiger" instructions in the 3.0 upgrade documentation. If you are using OS X or 64bit Linux, you can update your development database in a similar way (if you are running meteor as usual, you can connect to the development database at localhost:3001/meteor ). However, if you are not concerned about the data in your

development database, the easiest thing to do is to remove all local data (including your development database) with meteor reset . When you next start meteor , the database will be recreated with a 3.2 WiredTiger engine. If you are using Windows or 32bit Linux, you can update your development database to 3.2, however it will continue to use the MMAPv1 storage engine, as the 32bit MongoDB binary does not support WiredTiger.

Use Nested Imports Thanks to the use of the reify library, Meteor now fully supports nested import declarations in both application and package modules, whereas previously they were only allowed in application code: if (Meteor.isClient) { import { symbol } from './client-only/file'; }

One place this is particularly useful is in test files that are only intended to run on the client or the server — you can now use import wherever you like, without having to organize your tests in client or server directories.

31

Migrating to Meteor 1.4

32

Migrating to Meteor 1.3

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. Files in a directory named imports/ will no longer load eagerly. (You should probably rename such a directory as it the basis of our new module system). Files within your app named *.test[s].* , *.app-test[s].* , *.spec[s].* and *.appspec[s].* will no longer load eagerly (you should probably rename such a file if it

doesn't contain tests, as it will be eagerly loaded by our new app testing modes). If you are using React you will now need to install a set of React npm packages in your app. See the recommendations for React below for more details.

Mobile iOS apps now require iOS 8 or higher, and building for iOS requires Xcode 7.2 or higher to be installed. Building for Android now requires Android SDK 23 to be installed. You may also need to create a new AVD for the emulator. Cordova has been upgraded to the most recent versions (Cordova 6.0.0, Cordova iOS 4.0.1 and Cordova Android 5.1.0). This may require you to upgrade your plugin versions. We pin core Cordova plugins to versions known to be compatible and warn about this during build, but you may encounter compile time or runtime errors with third party plugins. Upgrading to newer versions of these plugins may help if they have been updated to work with recent versions of Cordova. The plugin used to serve your app's files and support hot code push has been completely rewritten. As a result, files are now served from localhost instead of meteor.local , with a fixed port number derived from your appId . You may have to

update OAuth redirect URLs to point to the new local domain and port.

Recommendations: 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.

33

Migrating to Meteor 1.3

You should load all Meteor "pseudo-globals" using the `import { Name } from 'meteor/package' syntax. For instance: import { Meteor } from 'meteor/meteor'; import { EJSON } from 'meteor/ejson';

You should consider installing the meteor-node-stubs npm package to allow using npm packages written for node on the browser: meteor npm install --save meteor-node-stubs

If you are using app-local packages to control load order and write unit tests for your application, we recommend you switch to using modules: Remove code related to the Package API from the package.js files and rename them to index.js , Move your local packages to the imports/ directory. Add the necessary import statements to each of the modules in your packages. Add export statements to each of your packages exports. 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';

You can read about our recommended structure for applications and modules in the Application Structure article of the Meteor Guide, and how to test them in the Testing article. If you are using Atmosphere packages which simply wrap npm packages, both on the client and server, it is now recommended that you simply install them using npm. Run npm init to initialize your package.json and install packages with npm install --save

(or npm install --save-dev if it's development dependency for testing etc.). We have some tips about how to use npm packages written in an asynchronous style.

34

Migrating to Meteor 1.3

Also, you should no longer need to use the meteorhacks:npm package. To migrate, follow the following steps: 1. Remove packages from your app: meteor remove meteorhacks:npm npm-container . 2. Remove the generated npm-container package: rm -r packages/npm-container . 3. Move the contents of packages.json to the dependencies section of your package.json (you may need to create one with meteor npm init ).

4. Simply use import instead of Npm.require() .

Recommendations: package authors Package authors are recommended to: No longer publish wrapper packages that do no more than include an npm package / client side lib. If your package adds significant wrappers around the npm package, it might make sense however. Publish to npm when appropriate, especially if your package can be used by the wider JS community! Use api.mainModule() and export from your main module rather than api.exports() in Atmosphere packages. If you depend (directly or transitively) on a client side npm package that is large or problematic if installed twice (e.g. React), use tmeasday:check-npm-versions to declare "peer" dependencies. If the client side npm package you depend on is angular , you can support both Meteor 1.2 and 1.3 using this solution. Read more about this in the Writing Packages article.

Recommendations: 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.

35

Migrating to Meteor 1.3

To convert tests, you'll need to change or upgrade your test driver package to a 1.3 compatible package (as of this writing there is only one choice practicalmeteor:mocha but we expect more to exist in the future). You should name your test files in the pattern *.app-test[s].* and place them outside of tests/ directories. To run the tests you

can run meteor test --full-app --driver-package Note that full app test mode does not run the test reporter in a separate application to the app under test, and does not amalgamate results from multiple testing systems, as Velocity does. This effectively means if you are using more than one testing system, you will need to run meteor test --full-app multiple times. Also, it means certain types of tests are better off written as acceptance tests outside of the Meteor tool.

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. To convert your unit tests to run against the app, first upgrade your test driver (see above) and then place your test files alongside the modules they are testing with a name matching *.tests.* . Such files will automatically be added to your "test app" when you run meteor test --driver-package . You can import the modules that you need to test against within each test file. Some example tests can be seen the Todos example app

Recommendations: Mobile Alongside some of the breaking mobile changes listed above, there are some changes in the way the mobile integration works that you should consider: Some low resolution app icon and launch images sizes for now unsupported devices have been deprecated. To avoid a deprecation warning during build, please remove the entries from your mobile-config.js . (You probably also want to remove the image files from your project.) The plugin now allows for local file access on both iOS and Android. You can construct file system URLs manually ( http://localhost:/local-filesystem/ ) or use WebAppLocalServer.localFileSystemUrl() to convert a file:// URL.

Install React from npm 36

Migrating to Meteor 1.3

In Meteor 1.3, we recommend installing react and react-dom into your app using npm, and importing them from your app code: 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): 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: 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: 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!

37

Migrating to Meteor 1.3

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: npm install --save angular angular-meteor

and importing them from your app code: 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: 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: 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:

38

Migrating to Meteor 1.3

api.use('angular:[email protected]', 'client', { weak: true });

and then add a dependency check for both Meteor 1.2 and 1.3 before initializing your angular module: 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: There's a Application Structure article which explains how to structure your files and use the module system. There's a Code Style article that makes recommendations about how to ensure consistent formatting for your code. There's a Testing article which covers how to do various kinds of testing in Meteor. There's a React article which explains how to best use React with Meteor There's a Mobile article which covers how to best use our Cordova integration. There's a Using Packages article which explains how best to use both npm and Atmosphere packages in your app. There's a Writing Packages article which explains practice for writing Atmosphere packages and using all kinds of dependencies within them. The UI/UX article has been updated to explain how to do i18n in Meteor applications.

39

Migrating to Meteor 1.3

40

Collections and Schemas

After reading this guide, you'll know: 1. The different types of MongoDB collections in Meteor, and how to use them. 2. How to define a schema for a collection to control its content. 3. What to consider when defining your collection's schema. 4. How to enforce the schema when writing to a collection. 5. How to carefully change the schema of your collection. 6. How to deal with associations between records.

MongoDB collections in Meteor At its core, a web application offers its users a view into, and a way to modify, a persistent set of data. Whether managing a list of todos, or ordering a car to pick you up, you are interacting with a permanent but constantly changing data layer. In Meteor, that data layer is typically stored in MongoDB. A set of related data in MongoDB is referred to as a "collection". In Meteor you access MongoDB through collections, making them the primary persistence mechanism for your app data. However, collections are a lot more than a way to save and retrieve data. They also provide the core of the interactive, connected user experience that users expect from the best applications. Meteor makes this user experience easy to implement. In this article, we'll look closely at how collections work in various places in the framework, and how to get the most out of them.

Server-side collections When you create a collection on the server: Todos = new Mongo.Collection('Todos');

You are creating a collection within MongoDB, and an interface to that collection to be used on the server. It's a fairly straightforward layer on top of the underlying Node MongoDB driver, but with a synchronous API: // This line won't complete until the insert is done Todos.insert({_id: 'my-todo'}); // So this line will return something const todo = Todos.findOne({_id: 'my-todo'}); // Look ma, no callbacks! console.log(todo);

41

Collections and Schemas

Client-side collections On the client, when you write the same line: Todos = new Mongo.Collection('Todos');

It does something totally different! On the client, there is no direct connection to the MongoDB database, and in fact a synchronous API to it is not possible (nor probably what you want). Instead, on the client, a collection is a client side cache of the database. This is achieved thanks to the Minimongo library---an in-memory, all JS, implementation of the MongoDB API. What this means is that on the client, when you write: // This line is changing an in-memory Minimongo data structure Todos.insert({_id: 'my-todo'}); // And this line is querying it const todo = Todos.findOne({_id: 'my-todo'}); // So this happens right away! console.log(todo);

The way that you move data from the server (and MongoDB-backed) collection into the client (in-memory) collection is the subject of the data loading article. Generally speaking, you subscribe to a publication, which pushes data from the server to the client. Usually, you can assume that the client contains an up-to-date copy of some subset of the full MongoDB collection. To write data back to the server, you use a Method, the subject of the methods article.

Local collections There is a third way to use a collection in Meteor. On the client or server, if you create a collection but pass null instead of a name: SelectedTodos = new Mongo.Collection(null);

This creates a local collection. This is a Minimongo collection that has no database connection (ordinarily a named collection would either be directly connected to the database on the server, or via a subscription on the client). A local collection is a convenient way to use the full power of the Minimongo library for inmemory storage. For instance, you might use it instead of a simple array if you need to execute complex queries over your data. Or you may want to take advantage of its reactivity

42

Collections and Schemas

on the client to drive some UI in a way that feels natural in Meteor.

Defining a schema Although MongoDB is a schema-less database, which allows maximum flexibility in data structuring, it is generally good practice to use a schema to constrain the contents of your collection to conform to a known format. If you don't, then you tend to end up needing to write defensive code to check and confirm the structure of your data as it comes out of the database, instead of when it goes into the database. As in most things, you tend to read data more often than you write it, and so it's usually easier, and less buggy to use a schema when writing. In Meteor, the pre-eminent schema package is aldeed:simple-schema. It's an expressive, MongoDB based schema that's used to insert and update documents. Another alternative is jagi:astronomy which is a full Object Model (OM) layer offering schema definition, server/client side validators, object methods and event handlers. Let's assume that we have a Lists collection. To define a schema for this collection using simple-schema , you can simply create a new instance of the SimpleSchema class and attach

it to the Lists object: Lists.schema = new SimpleSchema({ name: {type: String}, incompleteCount: {type: Number, defaultValue: 0}, userId: {type: String, regEx: SimpleSchema.RegEx.Id, optional: true} });

This example from the Todos app defines a schema with a few simple rules: 1. We specify that the name field of a list is required and must be a string. 2. We specify the incompleteCount is a number, which on insertion is set to 0 if not otherwise specified. 3. We specify that the userId , which is optional, must be a string that looks like the ID of a user document. We attach the schema to the namespace of Lists directly, which allows us to check objects against this schema directly whenever we want, such as in a form or Method. In the next section we'll see how to use this schema automatically when writing to the collection. You can see that with relatively little code we've managed to restrict the format of a list significantly. You can read more about more complex things that can be done with schemas in the Simple Schema docs.

43

Collections and Schemas

Validating against a schema Now we have a schema, how do we use it? It's pretty straightforward to validate a document with a schema. We can write: const list = { name: 'My list', incompleteCount: 3 }; Lists.schema.validate(list);

In this case, as the list is valid according to the schema, the validate() line will run without problems. If however, we wrote: const list = { name: 'My list', incompleteCount: 3, madeUpField: 'this should not be here' }; Lists.schema.validate(list);

Then the validate() call will throw a ValidationError which contains details about what is wrong with the list document.

The `ValidationError` What is a ValidationError ? It's a special error that is used in Meteor to indicate a userinput based error in modifying a collection. Typically, the details on a ValidationError are used to mark up a form with information about what inputs don't match the schema. In the methods article, we'll see more about how this works.

Designing your data schema Now that you are familiar with the basic API of Simple Schema, it's worth considering a few of the constraints of the Meteor data system that can influence the design of your data schema. Although generally speaking you can build a Meteor data schema much like any MongoDB data schema, there are some important details to keep in mind.

44

Collections and Schemas

The most important consideration is related to the way DDP, Meteor's data loading protocol, communicates documents over the wire. The key thing to realize is that DDP sends changes to documents at the level of top-level document fields. What this means is that if you have large and complex subfields on document that change often, DDP can send unnecessary changes over the wire. For instance, in "pure" MongoDB you might design the schema so that each list document had a field called todos which was an array of todo items: Lists.schema = new SimpleSchema({ name: {type: String}, todos: {type: [Object]} });

The issue with this schema is that due to the DDP behavior just mentioned, each change to any todo item in a list will require sending the entire set of todos for that list over the network. This is because DDP has no concept of "change the text field of the 3rd item in the field called todos ", simply "change the field called todos to a totally new array".

Denormalization and multiple collections The implication of the above is that we need to create more collections to contain subdocuments. In the case of the Todos application, we need both a Lists collection and a Todos collection to contain each list's todo items. Consequently we need to do some things

that you'd typically associate with a SQL database, like using foreign keys ( todo.listId ) to associate one document with another. In Meteor, it's often less of a problem doing this than it would be in a typical MongoDB application, as it's easy to publish overlapping sets of documents (we might need one set of users to render one screen of our app, and an intersecting set for another), which may stay on the client as we move around the application. So in that scenario there is an advantage to separating the subdocuments from the parent. However, given that MongoDB prior to version 3.2 doesn't support queries over multiple collections ("joins"), we typically end up having to denormalize some data back onto the parent collection. Denormalization is the practice of storing the same piece of information in the database multiple times (as opposed to a non-redundant "normal" form). MongoDB is a database where denormalizing is encouraged, and thus optimized for this practice. In the case of the Todos application, as we want to display the number of unfinished todos next to each list, we need to denormalize list.incompleteTodoCount . This is an inconvenience but typically reasonably easy to do as we'll see in the section on abstracting denormalizers below.

45

Collections and Schemas

Another denormalization that this architecture sometimes requires can be from the parent document onto sub-documents. For instance, in Todos, as we enforce privacy of the todo lists via the list.userId attribute, but we publish the todos separately, it might make sense to denormalize todo.userId also. To do this, we'd need to be careful to take the userId from the list when creating the todo, and updating all relevant todos whenever a list's userId changed.

Designing for the future An application, especially a web application, is rarely finished, and it's useful to consider potential future changes when designing your data schema. As in most things, it's rarely a good idea to add fields before you actually need them (often what you anticipate doesn't actually end up happening, after all). However, it's a good idea to think ahead to how the schema may change over time. For instance, you may have a list of strings on a document (perhaps a set of tags). Although it's tempting to leave them as a subfield on the document (assuming they don't change much), if there's a good chance that they'll end up becoming more complicated in the future (perhaps tags will have a creator, or subtags later on?), then it might be easier in the long run to make a separate collection from the beginning. The amount of foresight you bake into your schema design will depend on your app's individual constraints, and will need to be a judgement call on your part.

Using schemas on write Although there are a variety of ways that you can run data through a Simple Schema before sending it to your collection (for instance you could check a schema in every method call), the simplest and most reliable is to use the aldeed:collection2 package to run every mutator ( insert/update/upsert call) through the schema. To do so, we use attachSchema() : Lists.attachSchema(Lists.schema);

What this means is that now every time we call Lists.insert() , Lists.update() , Lists.upsert() , first our document or modifier will be automatically checked against the

schema (in subtly different ways depending on the exact mutator).

`defaultValue` and data cleaning

46

Collections and Schemas

One thing that Collection2 does is "clean" the data before sending it to the database. This includes but is not limited to: 1. Coercing types - converting strings to numbers 2. Removing attributes not in the schema 3. Assigning default values based on the defaultValue in the schema definition However, sometimes it's useful to do more complex initialization to documents before inserting them into collections. For instance, in the Todos app, we want to set the name of new lists to be List X where X is the next available unique letter. To do so, we can subclass Mongo.Collection and write our own insert() method: class ListsCollection extends Mongo.Collection { insert(list, callback) { if (!list.name) { let nextLetter = 'A'; list.name = `List ${nextLetter}`; while (!!this.findOne({name: list.name})) { // not going to be too smart here, can go past Z nextLetter = String.fromCharCode(nextLetter.charCodeAt(0) + 1); list.name = `List ${nextLetter}`; } } // Call the original `insert` method, which will validate // against the schema return super.insert(list, callback); } } Lists = new ListsCollection('Lists');

Hooks on insert/update/remove The technique above can also be used to provide a location to "hook" extra functionality into the collection. For instance, when removing a list, we always want to remove all of its todos at the same time. We can use a subclass for this case as well, overriding the remove() method:

47

Collections and Schemas

class ListsCollection extends Mongo.Collection { // ... remove(selector, callback) { Package.todos.Todos.remove({listId: selector}); return super.remove(selector, callback); } }

This technique has a few disadvantages: 1. Mutators can get very long when you want to hook in multiple times. 2. Sometimes a single piece of functionality can be spread over multiple mutators. 3. It can be a challenge to write a hook in a completely general way (that covers every possible selector and modifier), and it may not be necessary for your application (because perhaps you only ever call that mutator in one way). A way to deal with points 1. and 2. is to separate out the set of hooks into their own module, and simply use the mutator as a point to call out to that module in a sensible way. We'll see an example of that below. Point 3. can usually be resolved by placing the hook in the Method that calls the mutator, rather than the hook itself. Although this is an imperfect compromise (as we need to be careful if we ever add another Method that calls that mutator in the future), it is better than writing a bunch of code that is never actually called (which is guaranteed to not work!), or giving the impression that your hook is more general that it actually is.

Abstracting denormalizers Denormalization may need to happen on various mutators of several collections. Therefore, it's sensible to define the denormalization logic in one place, and hook it into each mutator with one line of code. The advantage of this approach is that the denormalization logic is one place rather than spread over many files, but you can still examine the code for each collection and fully understand what happens on each update. In the Todos example app, we build a incompleteCountDenormalizer to abstract the counting of incomplete todos on the lists. This code needs to run whenever a todo item is inserted, updated (checked or unchecked), or removed. The code looks like:

48

Collections and Schemas

const incompleteCountDenormalizer = { _updateList(listId) { // Recalculate the correct incomplete count direct from MongoDB const incompleteCount = Todos.find({ listId, checked: false }).count(); Lists.update(listId, {$set: {incompleteCount}}); }, afterInsertTodo(todo) { this._updateList(todo.listId); }, afterUpdateTodo(selector, modifier) { // We only support very limited operations on todos check(modifier, {$set: Object}); // We can only deal with $set modifiers, but that's all we do in this app if (_.has(modifier.$set, 'checked')) { Todos.find(selector, {fields: {listId: 1}}).forEach(todo => { this._updateList(todo.listId); }); } }, // Here we need to take the list of todos being removed, selected *before* the update // because otherwise we can't figure out the relevant list id(s) (if the todo has be en deleted) afterRemoveTodos(todos) { todos.forEach(todo => this._updateList(todo.listId)); } };

We are then able to wire in the denormalizer into the mutations of the Todos collection like so: class TodosCollection extends Mongo.Collection { insert(doc, callback) { doc.createdAt = doc.createdAt || new Date(); const result = super.insert(doc, callback); incompleteCountDenormalizer.afterInsertTodo(doc); return result; } }

Note that we only handled the mutators we actually use in the application---we don't deal with all possible ways the todo count on a list could change. For example, if you changed the listId on a todo item, it would need to change the incompleteCount of two lists. However,

49

Collections and Schemas

since our application doesn't do this, we don't handle it in the denormalizer. Dealing with every possible MongoDB operator is difficult to get right, as MongoDB has a rich modifier language. Instead we focus on just dealing with the modifiers we know we'll see in our app. If this gets too tricky, then moving the hooks for the logic into the Methods that actually make the relevant modifications could be sensible (although you need to be diligent to ensure you do it in all the relevant places, both now and as the app changes in the future). It could make sense for packages to exist to completely abstract some common denormalization techniques and actually attempt to deal with all possible modifications. If you write such a package, please let us know!

Migrating to a new schema As we discussed above, trying to predict all future requirements of your data schema ahead of time is impossible. Inevitably, as a project matures, there will come a time when you need to change the schema of the database. You need to be careful about how you make the migration to the new schema to make sure your app works smoothly during and after the migration.

Writing migrations A useful package for writing migrations is percolate:migrations , which provides a nice framework for switching between different versions of your schema. Suppose, as an example, that we wanted to add a list.todoCount field, and ensure that it was set for all existing lists. Then we might write the following in server-only code (e.g. /server/migrations.js ):

Migrations.add({ version: 1, up() { Lists.find({todoCount: {$exists: false}}).forEach(list => { const todoCount = Todos.find({listId: list._id}).count(); Lists.update(list._id, {$set: {todoCount}}); }); }, down() { Lists.update({}, {$unset: {todoCount: true}}, {multi: true}); } });

50

Collections and Schemas

This migration, which is sequenced to be the first migration to run over the database, will, when called, bring each list up to date with the current todo count. To find out more about the API of the Migrations package, refer to its documentation.

Bulk changes If your migration needs to change a lot of data, and especially if you need to stop your app server while it's running, it may be a good idea to use a MongoDB Bulk Operation. The advantage of a bulk operation is that it only requires a single round trip to MongoDB for the write, which usually means it is a lot faster. The downside is that if your migration is complex (which it usually is if you can't just do an .update(.., .., {multi: true}) ), it can take a significant amount of time to prepare the bulk update. What this means is if users are accessing the site whilst the update is being prepared, it will likely go out of date! Also, a bulk update will lock the entire collection while it is being applied, which can cause a significant blip in your user experience if it takes a while. For these reason, you often need to stop your server and let your users know you are performing maintenance while the update is happening. We could write our above migration like so (note that you must be on MongoDB 2.6 or later for the bulk update operations to exist). We can access the native MongoDB API via Collection#rawCollection() :

51

Collections and Schemas

Migrations.add({ version: 1, up() { // This is how to get access to the raw MongoDB node collection that the Meteor se rver collection wraps const batch = Lists.rawCollection().initializeUnorderedBulkOp(); //Mongo throws an error if we execute a batch operation without actual operations, e.g. when Lists was empty. let hasUpdates = false; Lists.find({todoCount: {$exists: false}}).forEach(list => { const todoCount = Todos.find({listId: list._id}).count(); // We have to use pure MongoDB syntax here, thus the `{_id: X}` batch.find({_id: list._id}).updateOne({$set: {todoCount}}); hasUpdates = true; }); if(hasUpdates){ // We need to wrap the async function to get a synchronous API that migrations e xpects const execute = Meteor.wrapAsync(batch.execute, batch); return execute(); } return true; }, down() { Lists.update({}, {$unset: {todoCount: true}}, {multi: true}); } });

Note that we could make this migration faster by using an Aggregation to gather the initial set of todo counts.

Running migrations To run a migration against your development database, it's easiest to use the Meteor shell: // After running `meteor shell` on the command line: Migrations.migrateTo('latest');

If the migration logs anything to the console, you'll see it in the terminal window that is running the Meteor server. To run a migration against your production database, run your app locally in production mode (with production settings and environment variables, including database settings), and use the Meteor shell in the same way. What this does is run the up() function of all

52

Collections and Schemas

outstanding migrations, against your production database. In our case, it should ensure all lists have a todoCount field set. A good way to do the above is to spin up a virtual machine close to your database that has Meteor installed and SSH access (a special EC2 instance that you start and stop for the purpose is a reasonable option), and running the command after shelling into it. That way any latencies between your machine and the database will be eliminated, but you still can be very careful about how the migration is run. Note that you should always take a database backup before running any migration!

Breaking schema changes Sometimes when we change the schema of an application, we do so in a breaking way -- so that the old schema doesn't work properly with the new code base. For instance, if we had some UI code that heavily relied on all lists having a todoCount set, there would be a period, before the migration runs, in which the UI of our app would be broken after we deployed. The simple way to work around the problem is to take the application down for the period in between deployment and completing the migration. This is far from ideal, especially considering some migrations can take hours to run (although using Bulk Updates probably helps a lot here). A better approach is a multi-stage deployment. The basic idea is that: 1. Deploy a version of your application that can handle both the old and the new schema. In our case, it'd be code that doesn't expect the todoCount to be there, but which correctly updates it when new todos are created. 2. Run the migration. At this point you should be confident that all lists have a todoCount . 3. Deploy the new code that relies on the new schema and no longer knows how to deal with the old schema. Now we are safe to rely on list.todoCount in our UI. Another thing to be aware of, especially with such multi-stage deploys, is that being prepared to rollback is important! For this reason, the migrations package allows you to specify a down() function and call Migrations.migrateTo(x) to migrate back to version x . So if we wanted to reverse our migration above, we'd run // The "0" migration is the unmigrated (before the first migration) state Migrations.migrateTo(0);

If you find you need to roll your code version back, you'll need to be careful about the data, and step carefully through your deployment steps in reverse.

53

Collections and Schemas

Caveats Some aspects of the migration strategy outlined above are possibly not the most ideal way to do things (although perhaps appropriate in many situations). Here are some other things to be aware of: 1. Usually it is better to not rely on your application code in migrations (because the application will change over time, and the migrations should not). For instance, having your migrations pass through your Collection2 collections (and thus check schemas, set autovalues etc) is likely to break them over time as your schemas change over time. One way to avoid this problem is simply to not run old migrations on your database. This is a little bit limiting but can be made to work. 2. Running the migration on your local machine will probably make it take a lot longer as your machine isn't as close to the production database as it could be. Deploying a special "migration application" to the same hardware as your real application is probably the best way to solve the above issues. It'd be amazing if such an application kept track of which migrations ran when, with logs and provided a UI to examine and run them. Perhaps a boilerplate application to do so could be built (if you do so, please let us know and we'll link to it here!).

Associations between collections As we discussed earlier, it's very common in Meteor applications to have associations between documents in different collections. Consequently, it's also very common to need to write queries fetching related documents once you have a document you are interested in (for instance all the todos that are in a single list). To make this easier, we can attach functions to the prototype of the documents that belong to a given collection, to give us "methods" on the documents (in the object oriented sense). We can then use these methods to create new queries to find related documents.

Collection helpers We can use the dburles:collection-helpers package to easily attach such methods (or "helpers") to documents. For instance:

54

Collections and Schemas

Lists.helpers({ // A list is considered to be private if it has a userId set isPrivate() { return !!this.userId; } });

Once we've attached this helper to the Lists collection, every time we fetch a list from the database (on the client or server), it will have a .isPrivate() function available: const list = Lists.findOne(); if (list.isPrivate()) { console.log('The first list is private!'); }

Association helpers Now we can attach helpers to documents, it's simple to define a helper that fetches related documents Lists.helpers({ todos() { return Todos.find({listId: this._id}, {sort: {createdAt: -1}}); } });

Now we can easily find all the todos for a list: const list = Lists.findOne(); console.log(`The first list has ${list.todos().count()} todos`);

55

Publications and Data Loading

After reading this guide, you'll know: 1. What publications and subscriptions are in the Meteor platform. 2. How to define a publication on the server. 3. Where to subscribe on the client and in which templates. 4. Useful patterns for managing subscriptions. 5. How to reactively publish related data. 6. How to ensure your publication is secure in the face of reactive changes. 7. How to use the low-level publish API to publish anything. 8. What happens when you subscribe to a publication. 9. How to turn a 3rd-party REST endpoint into a publication. 10. How to turn a publication in your app into a REST endpoint.

Publications and subscriptions In a traditional, HTTP-based web application, the client and server communicate in a "request-response" fashion. Typically the client makes RESTful HTTP requests to the server and receives HTML or JSON data in response, and there's no way for the server to "push" data to the client when changes happen at the backend. Meteor is built from the ground up on the Distributed Data Protocol (DDP) to allow data transfer in both directions. Building a Meteor app doesn't require you to set up REST endpoints to serialize and send data. Instead you create publication endpoints that can push data from server to client. In Meteor a publication is a named API on the server that constructs a set of data to send to a client. A client initiates a subscription which connects to a publication, and receives that data. That data consists of a first batch sent when the subscription is initialized and then incremental updates as the published data changes. So a subscription can be thought of as a set of data that changes over time. Typically, the result of this is that a subscription "bridges" a server-side MongoDB collection, and the client side Minimongo cache of that collection. You can think of a subscription as a pipe that connects a subset of the "real" collection with the client's version, and constantly keeps it up to date with the latest information on the server.

Defining a publication A publication should be defined in a server-only file. For instance, in the Todos example app, we want to publish the set of public lists to all users:

56

Publications and Data Loading

Meteor.publish('lists.public', function() { return Lists.find({ userId: {$exists: false} }, { fields: Lists.publicFields }); });

There are a few things to understand about this code block. First, we've named the publication with the unique string lists.public , and that will be how we access it from the client. Second, we are simply returning a Mongo cursor from the publication function. Note that the cursor is filtered to only return certain fields from the collection, as detailed in the Security article. What that means is that the publication will simply ensure the set of data matching that query is available to any client that subscribes to it. In this case, all lists that do not have a userId setting. So the collection named Lists on the client will have all of the public lists

that are available in the server collection named Lists while that subscription is open. In this particular example in the Todos application, the subscription is initialized when the app starts and never stopped, but a later section will talk about subscription life cycle. Every publication takes two types of parameters: 1. The this context, which has information about the current DDP connection. For example, you can access the current user's _id with this.userId . 2. The arguments to the publication, which can be passed in when calling Meteor.subscribe .

Note: Since we need to access context on this we need to use the function() {} form for publications rather than the ES2015 () => {} . You can disable the arrow function linting rule for publication files with eslint-disable prefer-arrow-callback . A future version of the publication API will work more nicely with ES2015. In this publication, which loads private lists, we need to use this.userId to get only the todo lists that belong to a specific user.

57

Publications and Data Loading

Meteor.publish('lists.private', function() { if (!this.userId) { return this.ready(); } return Lists.find({ userId: this.userId }, { fields: Lists.publicFields }); });

Thanks to the guarantees provided by DDP and Meteor's accounts system, the above publication can be confident that it will only ever publish private lists to the user that they belong to. Note that the publication will re-run if the user logs out (or back in again), which means that the published set of private lists will change as the active user changes. In the case of a logged-out user, we explicitly call this.ready() , which indicates to the subscription that we've sent all the data we are initially going to send (in this case none). It's important to know that if you don't return a cursor from the publication or call this.ready() , the user's subscription will never become ready, and they will likely see a loading state forever. Here's an example of a publication which takes a named argument. Note that it's important to check the types of arguments that come in over the network. Meteor.publish('todos.inList', function(listId) { // We need to check the `listId` is the type we expect new SimpleSchema({ listId: {type: String} }).validate({ listId }); // ... });

When we subscribe to this publication on the client, we can provide this argument via the Meteor.subscribe() call:

Meteor.subscribe('todos.inList', list._id);

Organizing publications

58

Publications and Data Loading

It makes sense to place a publication alongside the feature that it's targeted for. For instance, sometimes publications provide very specific data that's only really useful for the view for which they were developed. In that case, placing the publication in the same module or directory as the view code makes perfect sense. Often, however, a publication is more general. For example in the Todos example application, we create a todos.inList publication, which publishes all the todos in a list. Although in the application we only use this in one place (in the Lists_show template), in a larger app, there's a good chance we might need to access all the todos for a list in other places. So putting the publication in the todos package is a sensible approach.

Subscribing to data To use publications, you need to create a subscription to it on the client. To do so, you call Meteor.subscribe() with the name of the publication. When you do this, it opens up a

subscription to that publication, and the server starts sending data down the wire to ensure that your client collections contain up to date copies of the data specified by the publication. Meteor.subscribe() also returns a "subscription handle" with a property called .ready() .

This is a reactive function that returns true when the publication is marked ready (either you call this.ready() explicitly, or the initial contents of a returned cursor are sent over). const handle = Meteor.subscribe('lists.public');

Stopping Subscriptions The subscription handle also has another important property, the .stop() method. When you are subscribing, it is very important to ensure that you always call .stop() on the subscription when you are done with it. This ensures that the documents sent by the subscription are cleared from your local Minimongo cache and the server stops doing the work required to service your subscription. If you forget to call stop, you'll consume unnecessary resources both on the client and the server. However, if you call Meteor.subscribe() conditionally inside a reactive context (such as an autorun , or getMeteorData in React) or via this.subscribe() in a Blaze component, then

Meteor's reactive system will automatically call this.stop() for you at the appropriate time.

Subscribe in UI components

59

Publications and Data Loading

It is best to place the subscription as close as possible to the place where the data from the subscription is needed. This reduces "action at a distance" and makes it easier to understand the flow of data through your application. If the subscription and fetch are separated, then it's not always clear how and why changes to the subscriptions (such as changing arguments), will affect the contents of the cursor. What this means in practice is that you should place your subscription calls in components. In Blaze, it's best to do this in the onCreated() callback: Template.Lists_show_page.onCreated(function() { this.getListId = () => FlowRouter.getParam('_id'); this.autorun(() => { this.subscribe('todos.inList', this.getListId()); }); });

In this code snippet we can see two important techniques for subscribing in Blaze templates: 1. Calling this.subscribe() (rather than Meteor.subscribe ), which attaches a special subscriptionsReady() function to the template instance, which is true when all

subscriptions made inside this template are ready. 2. Calling this.autorun sets up a reactive context which will re-initialize the subscription whenever the reactive function this.getListId() changes. Read more about Blaze subscriptions in the Blaze article, and about tracking loading state inside UI components in the UI article.

Fetching data Subscribing to data puts it in your client-side collection. To use the data in your user interface, you need to query your client-side collection. There are a couple of important rules to follow when doing this.

Always use specific queries to fetch data If you're publishing a subset of your data, it might be tempting to simply query for all data available in a collection (i.e. Lists.find() ) in order to get that subset on the client, without re-specifying the Mongo selector you used to publish that data in the first place. But if you do this, then you open yourself up to problems if another subscription pushes data into the same collection, since the data returned by Lists.find() might not be what you expected anymore. In an actively developed application, it's often hard to anticipate what

60

Publications and Data Loading

may change in the future and this can be a source of hard to understand bugs. Also, when changing between subscriptions, there is a brief period where both subscriptions are loaded (see Publication behavior when changing arguments below), so when doing things like pagination, it's exceedingly likely that this will be the case.

Fetch the data nearby where you subscribed to it We do this for the same reason we subscribe in the component in the first place---to avoid action at a distance and to make it easier to understand where data comes from. A common pattern is to fetch the data in a parent template, and then pass it into a "pure" child component, as we'll see it in the UI Article. Note that there are some exceptions to this second rule. A common one is Meteor.user() --although this is strictly speaking subscribed to (automatically usually), it's typically overcomplicated to pass it through the component hierarchy as an argument to each component. However keep in mind it's best not to use it in too many places as it makes components harder to test.

Global subscriptions One place where you might be tempted to not subscribe inside a component is when it accesses data that you know you always need. For instance, a subscription to extra fields on the user object (see the Accounts Article) that you need on every screen of your app. However, it's generally a good idea to use a layout component (which you wrap all your components in) to subscribe to this subscription anyway. It's better to be consistent about such things, and it makes for a more flexible system if you ever decide you have a screen that doesn't need that data.

Patterns for data loading Across Meteor applications, there are some common patterns of data loading and management on the client side that are worth knowing. We'll go into more detail about some of these in the UI/UX Article.

Subscription readiness It is key to understand that a subscription will not instantly provide its data. There will be a latency between subscribing to the data on the client and it arriving from the publication on the server. You should also be aware that this delay may be a lot longer for your users in

61

Publications and Data Loading

production than for you locally in development! Although the Tracker system means you often don't need to think too much about this in building your apps, usually if you want to get the user experience right, you'll need to know when the data is ready. To find that out, Meteor.subscribe() and ( this.subscribe() in Blaze components) returns a "subscription handle", which contains a reactive data source called .ready() : const handle = Meteor.subscribe('lists.public'); Tracker.autorun(() => { const isReady = handle.ready(); console.log(`Handle is ${isReady ? 'ready' : 'not ready'}`); });

We can use this information to be more subtle about when we try and show data to users, and when we show a loading screen.

Reactively changing subscription arguments We've already seen an example of using an autorun to re-subscribe when the (reactive) arguments to a subscription change. It's worth digging in a little more detail to understand what happens in this scenario. Template.Lists_show_page.onCreated(function() { this.getListId = () => FlowRouter.getParam('_id'); this.autorun(() => { this.subscribe('todos.inList', this.getListId()); }); });

In our example, the autorun will re-run whenever this.getListId() changes, (ultimately because FlowRouter.getParam('_id') changes), although other common reactive data sources are: 1. Template data contexts (which you can access reactively with Template.currentData() ). 2. The current user status ( Meteor.user() and Meteor.loggingIn() ). 3. The contents of other application specific client data stores. Technically, what happens when one of these reactive sources changes is the following: 1. The reactive data source invalidates the autorun computation (marks it so that it re-runs in the next Tracker flush cycle). 2. The subscription detects this, and given that anything is possible in next computation

62

Publications and Data Loading

run, marks itself for destruction. 3. The computation re-runs, with .subscribe() being re-called either with the same or different arguments. 4. If the subscription is run with the same arguments then the "new" subscription discovers the old "marked for destruction" subscription that's sitting around, with the same data already ready, and simply reuses that. 5. If the subscription is run with different arguments, then a new subscription is created, which connects to the publication on the server. 6. At the end of the flush cycle (i.e. after the computation is done re-running), the old subscription checks to see if it was re-used, and if not, sends a message to the server to tell the server to shut it down. Step 4 above is an important detail---that the system cleverly knows not to re-subscribe if the autorun re-runs and subscribes with the exact same arguments. This holds true even if the new subscription is set up somewhere else in the template hierarchy. For example, if a user navigates between two pages that both subscribe to the exact same subscription, the same mechanism will kick in and no unnecessary subscribing will happen.

Publication behavior when arguments change It's also worth knowing a little about what happens on the server when the new subscription is started and the old one is stopped. The server explicitly waits until all the data is sent down (the new subscription is ready) for the new subscription before removing the data from the old subscription. The idea here is to avoid flicker---you can, if desired, continue to show the old subscription's data until the new data is ready, then instantly switch over to the new subscription's complete data set. What this means is in general, when changing subscriptions, there'll be a period where you are over-subscribed and there is more data on the client than you strictly asked for. This is one very important reason why you should always fetch the same data that you have subscribed to (don't "over-fetch").

Paginating subscriptions A very common pattern of data access is pagination. This refers to the practice of fetching an ordered list of data one "page" at a time---typically some number of items, say twenty. There are two styles of pagination that are commonly used, a "page-by-page" style---where you show only one page of results at a time, starting at some offset (which the user can control), and "infinite-scroll" style, where you show an increasing number of pages of items, as the user moves through the list (this is the typical "feed" style user interface).

63

Publications and Data Loading

In this section, we'll consider a publication/subscription technique for the second, infinitescroll style pagination. The page-by-page technique is a little tricker to handle in Meteor, due to it being difficult to calculate the offset on the client. If you need to do so, you can follow many of the same techniques that we use here and use the percolate:find-frompublication package to keep track of which records have come from your publication.

In an infinite scroll publication, we simply need to add a new argument to our publication controlling how many items to load. Suppose we wanted to paginate the todo items in our Todos example app: const MAX_TODOS = 1000; Meteor.publish('todos.inList', function(listId, limit) { new SimpleSchema({ listId: { type: String }, limit: { type: Number } }).validate({ listId, limit }); const options = { sort: {createdAt: -1}, limit: Math.min(limit, MAX_TODOS) }; // ... });

It's important that we set a sort parameter on our query (to ensure a repeatable order of list items as more pages are requested), and that we set an absolute maximum on the number of items a user can request (at least in the case where lists can grow without bound). Then on the client side, we'd set some kind of reactive state variable to control how many items to request: Template.Lists_show_page.onCreated(function() { this.getListId = () => FlowRouter.getParam('_id'); this.autorun(() => { this.subscribe('todos.inList', this.getListId(), this.state.get('requestedTodos')); }); });

We'd increment that requestedTodos variable when the user clicks "load more" (or perhaps just when they scroll to the bottom of the page).

64

Publications and Data Loading

One piece of information that's very useful to know when paginating data is the total number of items that you could see. The tmeasday:publish-counts package can be useful to publish this. We could add a Lists.todoCount publication like so Meteor.publish('Lists.todoCount', function({ listId }) { new SimpleSchema({ listId: {type: String} }).validate({ listId }); Counts.publish(this, `Lists.todoCount.${listId}`, Todos.find({listId})); });

Then on the client, after subscribing to that publication, we can access the count with Counts.get(`Lists.todoCount.${listId}`)

Client-side data with reactive stores In Meteor, persistent or shared data comes over the wire on publications. However, there are some types of data which doesn't need to be persistent or shared between users. For instance, the "logged-in-ness" of the current user, or the route they are currently viewing. Although client-side state is often best contained as state of an individual template (and passed down the template hierarchy as arguments where necessary), sometimes you have a need for "global" state that is shared between unrelated sections of the template hierarchy. Usually such state is stored in a global singleton object which we can call a store. A singleton is a data structure of which only a single copy logically exists. The current user and the router from above are typical examples of such global singletons.

Types of stores In Meteor, it's best to make stores reactive data sources, as that way they tie most naturally into the rest of the ecosystem. There are a few different packages you can use for stores. If the store is single-dimensional, you can probably use a ReactiveVar to store it (provided by the reactive-var package). A ReactiveVar has two properties, get() and set() : DocumentHidden = new ReactiveVar(document.hidden); $(window).on('visibilitychange', (event) => { DocumentHidden.set(document.hidden); });

65

Publications and Data Loading

If the store is multi-dimensional, you may want to use a ReactiveDict (from the reactivedict package):

const $window = $(window); function getDimensions() { return { width: $window.width(), height: $window.height() }; }; WindowSize = new ReactiveDict(); WindowSize.set(getDimensions()); $window.on('resize', () => { WindowSize.set(getDimensions()); });

The advantage of a ReactiveDict is you can access each property individually ( WindowSize.get('width') ), and the dict will diff the field and track changes on it individually (so your template will re-render less often for instance). If you need to query the store, or store many related items, it's probably a good idea to use a Local Collection (see the Collections Article).

Accessing stores You should access stores in the same way you'd access other reactive data in your templates---that means centralizing your store access, much like you centralize your subscribing and data fetch. For a Blaze template, that's either in a helper, or from within a this.autorun() inside an onCreated() callback.

This way you get the full reactive power of the store.

Updating stores If you need to update a store as a result of user action, you'd update the store from an event handler, just like you call Methods. If you need to perform complex logic in the update (e.g. not just call .set() etc), it's a good idea to define a mutator on the store. As the store is a singleton, you can just attach a function to the object directly:

66

Publications and Data Loading

WindowSize.simulateMobile = (device) => { if (device === 'iphone6s') { this.set({width: 750, height: 1334}); } }

Advanced publications Sometimes, the simple mechanism of returning a query from a publication function won't cover your needs. In those situations, there are some more powerful publication patterns that you can use.

Publishing relational data It's common to need related sets of data from multiple collections on a given page. For instance, in the Todos app, when we render a todo list, we want the list itself, as well as the set of todos that belong to that list. One way you might do this is to return more than one cursor from your publication function: Meteor.publish('todos.inList', function(listId) { new SimpleSchema({ listId: {type: String} }).validate({ listId }); const list = Lists.findOne(listId); if (list && (!list.userId || list.userId === this.userId)) { return [ Lists.find(listId), Todos.find({listId}) ]; } else { // The list doesn't exist, or the user isn't allowed to see it. // In either case, make it appear like there is no list. return this.ready(); } });

However, this example will not work as you might expect. The reason is that reactivity doesn't work in the same way on the server as it does on the client. On the client, if anything in a reactive function changes, the whole function will re-run, and the results are fairly intuitive.

67

Publications and Data Loading

On the server however, the reactivity is limited to the behavior of the cursors you return from your publish functions. You'll see any changes to the data that matches their queries, but their queries will never change. So in the case above, if a user subscribes to a list that is later made private by another user, although the list.userId will change to a value that no longer passes the condition, the body of the publication will not re-run, and so the query to the Todos collection ( {listId} ) will not change. So the first user will continue to see items they shouldn't. However, we can write publications that are properly reactive to changes across collections. To do this, we use the reywood:publish-composite package. The way this package works is to first establish a cursor on one collection, and then explicitly set up a second level of cursors on a second collection with the results of the first cursor. The package uses a query observer behind the scenes to trigger the subscription to change and queries to re-run whenever the source data changes. Meteor.publishComposite('todos.inList', function(listId) { new SimpleSchema({ listId: {type: String} }).validate({ listId }); const userId = this.userId; return { find() { const query = { _id: listId, $or: [{userId: {$exists: false}}, {userId}] }; // We only need the _id field in this query, since it's only // used to drive the child queries to get the todos const options = { fields: { _id: 1 } }; return Lists.find(query, options); }, children: [{ find(list) { return Todos.find({ listId: list._id }, { fields: Todos.publicFields }); } }] }; });

68

Publications and Data Loading

In this example, we write a complicated query to make sure that we only ever find a list if we are allowed to see it, then, once per list we find (which can be one or zero times depending on access), we publish the todos for that list. Publish Composite takes care of stopping and starting the dependent cursors if the list stops matching the original query or otherwise.

Complex authorization We can also use publish-composite to perform complex authorization in publications. For instance, consider if we had a Todos.admin.inList publication that allowed an admin to bypass default publication's security for users with an admin flag set. We might want to write: Meteor.publish('Todos.admin.inList', function({ listId }) { new SimpleSchema({ listId: {type: String} }).validate({ listId }); const user = Meteor.users.findOne(this.userId); if (user && user.admin) { // We don't need to worry about the list.userId changing this time return [ Lists.find(listId), Todos.find({listId}) ]; } else { return this.ready(); } });

However, due to the same reasons discussed above, the publication will not re-run if the user's admin status changes. If this is something that is likely to happen and reactive changes are needed, then we'll need to make the publication reactive. We can do this via the same technique as above however:

69

Publications and Data Loading

Meteor.publishComposite('Todos.admin.inList', function(listId) { new SimpleSchema({ listId: {type: String} }).validate({ listId }); const userId = this.userId; return { find() { return Meteor.users.find({userId, admin: true}); }, children: [{ find() { // We don't need to worry about the list.userId changing this time return [ Lists.find(listId), Todos.find({listId}) ]; } }] }; });

Custom publications with the low level API In all of our examples so far (outside of using Meteor.publishComposite() ) we've returned a cursor from our Meteor.publish() handlers. Doing this ensures Meteor takes care of the job of keeping the contents of that cursor in sync between the server and the client. However, there's another API you can use for publish functions which is closer to the way the underlying Distributed Data Protocol (DDP) works. DDP uses three main messages to communicate changes in the data for a publication: the added , changed and removed messages. So, we can similarly do the same for a

publication:

70

Publications and Data Loading

Meteor.publish('custom-publication', function() { // We can add documents one at a time this.added('collection-name', 'id', {field: 'values'}); // We can call ready to indicate to the client that the initial document sent has be en sent this.ready(); // We may respond to some 3rd party event and want to send notifications Meteor.setTimeout(() => { // If we want to modify a document that we've already added this.changed('collection-name', 'id', {field: 'new-value'}); // Or if we don't want the client to see it any more this.removed('collection-name', 'id'); }); // It's very important to clean up things in the subscription's onStop handler this.onStop(() => { // Perhaps kill the connection with the 3rd party server }); });

From the client's perspective, data published like this doesn't look any different---there's actually no way for the client to know the difference as the DDP messages are the same. So even if you are connecting to, and mirroring, some esoteric data source, on the client it'll appear like any other Mongo collection. One point to be aware of is that if you allow the user to modify data in the "pseudocollection" you are publishing in this fashion, you'll want to be sure to re-publish the modifications to them via the publication, to achieve an optimistic user experience.

Subscription lifecycle Although you can use publications and subscriptions in Meteor via an intuitive understanding, sometimes it's useful to know exactly what happens under the hood when you subscribe to data. Suppose you have a simple publication of the following form: Meteor.publish('Posts.all', function() { return Posts.find({}, {limit: 10}); });

Then when a client calls Meteor.subscribe('Posts.all') the following things happen inside Meteor:

71

Publications and Data Loading

1. The client sends a sub message with the name of the subscription over DDP. 2. The server starts up the subscription by running the publication handler function. 3. The publication handler identifies that the return value is a cursor. This enables a convenient mode for publishing cursors. 4. The server sets up a query observer on that cursor, unless such an observer already exists on the server (for any user), in which case that observer is re-used. 5. The observer fetches the current set of documents matching the cursor, and passes them back to the subscription (via the this.added() callback). 6. The subscription passes the added documents to the subscribing client's connection mergebox, which is an on-server cache of the documents that have been published to this particular client. Each document is merged with any existing version of the document that the client knows about, and an added (if the document is new to the client) or changed (if it is known but this subscription is adding or changing fields) DDP message is sent. Note that the mergebox operates at the level of top-level fields, so if two subscriptions publish nested fields (e.g. sub1 publishes doc.a.b = 7 and sub2 publishes doc.a.c = 8 ), then the "merged" document might not look as you expect (in this case doc.a = {c: 8} , if sub2 happens second).

7. The publication calls the .ready() callback, which sends the DDP ready message to the client. The subscription handle on the client is marked as ready. 8. The observer observes the query. Typically, it uses MongoDB's Oplog to notice changes that affect the query. If it sees a relevant change, like a new matching document or a change in a field on a matching document, it calls into the subscription (via .added() , .changed() or .removed() ), which again sends the changes to the mergebox, and

then to the client via DDP. This continues until the client stops the subscription, triggering the following behavior: 1. The client sends the unsub DDP message. 2. The server stops its internal subscription object, triggering the following effects: 3. Any this.onStop() callbacks setup by the publish handler run. In this case, it is a single automatic callback setup when returning a cursor from the handler, which stops the query observer and cleans it up if necessary. 4. All documents tracked by this subscription are removed from the mergebox, which may or may not mean they are also removed from the client.

72

Publications and Data Loading

5. The nosub message is sent to the client to indicate that the subscription has stopped.

Working with REST APIs Publications and subscriptions are the primary way of dealing with data in Meteor's DDP protocol, but lots of data sources use the popular REST protocol for their API. It's useful to be able to convert between the two.

Loading data from a REST endpoint with a publication As a concrete example of using the low-level API, consider the situation where you have some 3rd party REST endpoint which provides a changing set of data that's valuable to your users. How do you make that data available? One option would be to provide a Method that simply proxies through to the endpoint, for which it's the client's responsibility to poll and deal with the changing data as it comes in. So then it's the clients problem to deal with keeping a local data cache of the data, updating the UI when changes happen, etc. Although this is possible (you could use a Local Collection to store the polled data, for instance), it's simpler, and more natural to create a publication that does this polling for the client. A pattern for turning a polled REST endpoint looks something like this:

73

Publications and Data Loading

const POLL_INTERVAL = 5000; Meteor.publish('polled-publication', function() { const publishedKeys = {}; const poll = () => { // Let's assume the data comes back as an array of JSON documents, with an _id fie ld, for simplicity const data = HTTP.get(REST_URL, REST_OPTIONS); data.forEach((doc) => { if (publishedKeys[doc._id]) { this.changed(COLLECTION_NAME, doc._id, doc); } else { publishedKeys[doc._id] = true; this.added(COLLECTION_NAME, doc._id, doc); } }); }; poll(); this.ready(); const interval = Meteor.setInterval(poll, POLL_INTERVAL); this.onStop(() => { Meteor.clearInterval(interval); }); });

Things can get more complicated; for instance you may want to deal with documents being removed, or share the work of polling between multiple users (in a case where the data being polled isn't private to that user), rather than doing the exact same poll for each interested user.

Accessing a publication as a REST endpoint The opposite scenario occurs when you want to publish data to be consumed by a 3rd party, typically over REST. If the data we want to publish is the same as what we already publish via a publication, then we can use the simple:rest package to do this really easily. In the Todos example app, we have done this, and you can now access our publications over HTTP:

74

Publications and Data Loading

$ curl localhost:3000/publications/lists.public { "Lists": [ { "_id": "rBt5iZQnDpRxypu68", "name": "Meteor Principles", "incompleteCount": 7 }, { "_id": "Qzc2FjjcfzDy3GdsG", "name": "Languages", "incompleteCount": 9 }, { "_id": "TXfWkSkoMy6NByGNL", "name": "Favorite Scientists", "incompleteCount": 6 } ] }

You can also access authenticated publications (such as lists.private ). Suppose we've signed up (via the web UI) as [email protected] , with the password password , and created a private list. Then we can access it as follows: # First, we need to "login" on the commandline to get an access token $ curl localhost:3000/users/login -H "Content-Type: application/json" --data '{"email ": "[email protected]", "password": "password"}' { "id": "wq5oLMLi2KMHy5rR6", "token": "6PN4EIlwxuVua9PFoaImEP9qzysY64zM6AfpBJCE6bs", "tokenExpires": "2016-02-21T02:27:19.425Z" } # Then, we can make an authenticated API call $ curl localhost:3000/publications/lists.private -H "Authorization: Bearer 6PN4EIlwxuV ua9PFoaImEP9qzysY64zM6AfpBJCE6bs" { "Lists": [ { "_id": "92XAn3rWhjmPEga4P", "name": "My Private List", "incompleteCount": 5, "userId": "wq5oLMLi2KMHy5rR6" } ] }

75

Publications and Data Loading

76

Methods

After reading this article, you'll know: 1. What Methods are in Meteor and how they work in detail. 2. Best practices for defining and calling Methods. 3. How to throw and handle errors with Methods. 4. How to call a Method from a form.

What is a Method? Methods are Meteor's remote procedure call (RPC) system, used to save user input events and data that come from the client. If you're familiar with REST APIs or HTTP, you can think of them like POST requests to your server, but with many nice features optimized for building a modern web application. Later on in this article, we'll go into detail about some of the benefits you get from Methods that you wouldn't get from an HTTP endpoint. At its core, a Method is an API endpoint for your server; you can define a Method on the server and its counterpart on the client, then call it with some data, write to the database, and get the return value in a callback. Meteor Methods are also tightly integrated with the pub/sub and data loading systems of Meteor to allow for Optimistic UI - the ability to simulate server-side actions on the client to make your app feel faster than it actually is. We'll be referring to Meteor Methods with a capital M to differentiate them from class methods in JavaScript.

Defining and calling Methods Basic Method In a basic app, defining a Meteor Method is as simple as defining a function. In a complex app, you want a few extra features to make Methods more powerful and easily testable. First, we're going to go over how to define a Method using the Meteor core API, and in a later section we'll go over how to use a helpful wrapper package we've created to enable a more powerful Method workflow.

Defining Here's how you can use the built-in Meteor.methods API to define a Method. Note that Methods should always be defined in common code loaded on the client and the server to enable Optimistic UI. If you have some secret code in your Method, consult the Security article for how to hide it from the client.

77

Methods

This example uses the aldeed:simple-schema package, which is recommended in several other articles, to validate the Method arguments. Meteor.methods({ 'todos.updateText'({ todoId, newText }) { new SimpleSchema({ todoId: { type: String }, newText: { type: String } }).validate({ todoId, newText }); const todo = Todos.findOne(todoId); if (!todo.editableBy(this.userId)) { throw new Meteor.Error('todos.updateText.unauthorized', 'Cannot edit todos in a private list that is not yours'); } Todos.update(todoId, { $set: { text: newText } }); } });

Calling This Method is callable from the client and server using Meteor.call . Note that you should only use a Method in the case where some code needs to be callable from the client; if you just want to modularize code that is only going to be called from the server, use a regular JavaScript function, not a Method. Here's how you can call this Method from the client: Meteor.call('todos.updateText', { todoId: '12345', newText: 'This is a todo item.' }, (err, res) => { if (err) { alert(err); } else { // success! } });

If the Method throws an error, you get that in the first argument of the callback. If the Method succeeds, you get the result in the second argument and the first argument err will be undefined . For more information about errors, see the section below about error handling.

78

Methods

Advanced Method boilerplate Meteor Methods have several features which aren't immediately obvious, but every complex app will need them at some point. These features were added incrementally over several years in a backwards-compatible fashion, so unlocking the full capabilities of Methods requires a good amount of boilerplate. In this article we will first show you all of the code you need to write for each feature, then the next section will talk about a Method wrapper package we have developed to make it easier. Here's some of the functionality an ideal Method would have: 1. Run validation code by itself without running the Method body. 2. Easily override the Method for testing. 3. Easily call the Method with a custom user ID, especially in tests (as recommended by the Discover Meteor two-tiered methods pattern). 4. Refer to the Method via JS module rather than a magic string. 5. Get the Method simulation return value to get IDs of inserted documents. 6. Avoid calling the server-side Method if the client-side validation failed, so we don't waste server resources.

Defining

79

Methods

export const updateText = { name: 'todos.updateText', // Factor out validation so that it can be run independently (1) validate(args) { new SimpleSchema({ todoId: { type: String }, newText: { type: String } }).validate(args) }, // Factor out Method body so that it can be called independently (3) run({ todoId, newText }) { const todo = Todos.findOne(todoId); if (!todo.editableBy(this.userId)) { throw new Meteor.Error('todos.updateText.unauthorized', 'Cannot edit todos in a private list that is not yours'); } Todos.update(todoId, { $set: { text: newText } }); }, // Call Method by referencing the JS object (4) // Also, this lets us specify Meteor.apply options once in // the Method implementation, rather than requiring the caller // to specify it at the call site. call(args, callback) { const options = { returnStubValue: true, // (5) throwStubExceptions: true // (6) } Meteor.apply(this.name, [args], options, callback); } }; // Actually register the method with Meteor's DDP system Meteor.methods({ [updateText.name]: function (args) { updateText.validate.call(this, args); updateText.run.call(this, args); } })

Calling Now calling the Method is as simple as calling a JavaScript function:

80

Methods

import { updateText } from './path/to/methods.js'; // Call the Method updateText.call({ todoId: '12345', newText: 'This is a todo item.' }, (err, res) => { if (err) { alert(err); } else { // success! } }); // Call the validation only updateText.validate({ wrong: 'args'}); // Call the Method with custom userId in a test updateText.run.call({ userId: 'abcd' }, { todoId: '12345', newText: 'This is a todo item.' });

As you can see, this approach to calling Methods results in a better development workflow you can more easily deal with the different parts of the Method separately and test your code more easily without having to deal with Meteor internals. But this approach requires you to write a lot of boilerplate on the Method definition side.

Advanced Methods with mdg:validated-method To alleviate some of the boilerplate that's involved in correct Method definitions, we've published a wrapper package called mdg:validated-method that does most of this for you. Here's the same Method as above, but defined with the package:

81

Methods

import { ValidatedMethod } from 'meteor/mdg:validated-method'; export const updateText = new ValidatedMethod({ name: 'todos.updateText', validate: new SimpleSchema({ todoId: { type: String }, newText: { type: String } }).validator(), run({ todoId, newText }) { const todo = Todos.findOne(todoId); if (!todo.editableBy(this.userId)) { throw new Meteor.Error('todos.updateText.unauthorized', 'Cannot edit todos in a private list that is not yours'); } Todos.update(todoId, { $set: { text: newText } }); } });

You call it the same way you call the advanced Method above, but the Method definition is significantly simpler. We believe this style of Method lets you clearly see the important parts - the name of the Method sent over the wire, the format of the expected arguments, and the JavaScript namespace by which the Method can be referenced. Validated methods only accept a single argument and a callback function.

Error handling In regular JavaScript functions, you indicate errors by throwing an Error object. Throwing errors from Meteor Methods works almost the same way, but a bit of complexity is introduced by the fact that in some cases the error object will be sent over a websocket back to the client.

Throwing errors from a Method Meteor introduces two new types of JavaScript errors: Meteor.Error and ValidationError . These and the regular JavaScript Error type should be used in different situations:

Regular `Error` for internal server errors

82

Methods

When you have an error that doesn't need to be reported to the client, but is internal to the server, throw a regular JavaScript error object. This will be reported to the client as a totally opaque internal server error with no details.

Meteor.Error for general runtime errors When the server was not able to complete the user's desired action because of a known condition, you should throw a descriptive Meteor.Error object to the client. In the Todos example app, we use these to report situations where the current user is not authorized to complete a certain action, or where the action is not allowed within the app - for example, deleting the last public list. Meteor.Error takes three arguments: error , reason , and details .

1.

error should be a short, unique, machine-readable error code string that the client can

interpret to understand what happened. It's good to prefix this with the name of the Method for easy internationalization, for example: 'todos.updateText.unauthorized' . 2.

reason should be a short description of the error for the developer. It should give your

coworker enough information to be able to debug the error. The reason parameter should not be printed to the end user directly, since this means you now have to do internationalization on the server before sending the error message, and the UI developer has to worry about the Method implementation when thinking about what will be displayed in the UI. 3.

details is optional, and can be used where extra data will help the client understand

what is wrong. In particular, it can be combined with the error field to print a more helpful error message to the end user.

ValidationError for argument validation errors When a Method call fails because the arguments are of the wrong type, it's good to throw a ValidationError . This works just like Meteor.Error , but is a custom constructor that

enforces a standard error format that can be read by different form and validation libraries. In particular, if you are calling this Method from a form, throwing a ValidationError will make it easy to display nice error messages next to particular fields in the form. When you use mdg:validated-method with aldeed:simple-schema as demonstrated above, this type of error is thrown for you. Read more about the error format in the mdg:validation-error docs.

Handling errors

83

Methods

When you call a Method, any errors thrown by it will be returned in the callback. At this point, you should identify which error type it is and display the appropriate message to the user. In this case, it is unlikely that the Method will throw a ValidationError or an internal server error, so we will only handle the unauthorized error: // Call the Method updateText.call({ todoId: '12345', newText: 'This is a todo item.' }, (err, res) => { if (err) { if (err.error === 'todos.updateText.unauthorized') { // Displaying an alert is probably not what you would do in // a real app; you should have some nice UI to display this // error, and probably use an i18n library to generate the // message from the error code. alert('You aren\'t allowed to edit this todo item'); } else { // Unexpected error, handle it in the UI somehow } } else { // success! } });

We'll talk about how to handle the ValidationError in the section on forms below.

Errors in Method simulation When a Method is called, it usually runs twice---once on the client to simulate the result for Optimistic UI, and again on the server to make the actual change to the database. This means that if your Method throws an error, it will likely fail on the client and the server. For this reason, ValidatedMethod turns on undocumented option in Meteor to avoid calling the server-side implementation if the simulation throws an error. While this behavior is good for saving server resources in cases where a Method will certainly fail, it's important to make sure that the simulation doesn't throw an error in cases where the server Method would have succeeded (for example, if you didn't load some data on the client that the Method needs to do the simulation properly). In this case, you can wrap server-side-only logic in a block that checks for a method simulation: if (!this.isSimulation) { // Logic that depends on server environment here }

84

Methods

Calling a Method from a form The main thing enabled by the ValidationError convention is simple integration between Methods and the forms that call them. In general, your app is likely to have a one-to-one mapping of forms in the UI to Methods. First, let's define a Method for our business logic: // This Method encodes the form validation requirements. // By defining them in the Method, we do client and server-side // validation in one place. export const insert = new ValidatedMethod({ name: 'Invoices.methods.insert', validate: new SimpleSchema({ email: { type: String, regEx: SimpleSchema.RegEx.Email }, description: { type: String, min: 5 }, amount: { type: String, regEx: /^\d*\.(\d\d)?$/ } }).validator(), run(newInvoice) { // In here, we can be sure that the newInvoice argument is // validated. if (!this.userId) { throw new Meteor.Error('Invoices.methods.insert.not-logged-in', 'Must be logged in to create an invoice.'); } Invoices.insert(newInvoice) } });

Let's define a simple HTML form:

85

Methods

Recipient email {{#each error in errors "email"}} {{error}} {{/each}} Item description {{#each error in errors "description"}} {{error}} {{/each}} Amount owed {{#each error in errors "amount"}} {{error}} {{/each}}

Now, let's write some JavaScript to handle this form nicely:

86

Methods

import { insert } from '../api/invoices/methods.js'; Template.Invoices_newInvoice.onCreated(function() { this.errors = new ReactiveDict(); }); Template.Invoices_newInvoice.helpers({ errors(fieldName) { return this.errors.get(fieldName); } }); Template.Invoices_newInvoice.events({ 'submit .Invoices_newInvoice'(event, instance) { const data = { email: event.target.email.value, description: event.target.description.value, amount: event.target.amount.value }; insert.call(data, (err, res) => { if (err) { if (err.error === 'validation-error') { // Initialize error object const errors = { email: [], description: [], amount: [] }; // Go through validation errors returned from Method err.details.forEach((fieldError) => { // XXX i18n errors[fieldError.name].push(fieldError.type); }); // Update ReactiveDict, errors will show up in the UI instance.errors.set(errors); } } }); } });

As you can see, there is a fair amount of boilerplate to handle errors nicely in a form, but most of it can be easily abstracted by an off-the-shelf form framework or a simple application-specific wrapper of your own design.

Loading data with Methods 87

Methods

Since Methods can work as general purpose RPCs, they can also be used to fetch data instead of publications. There are some advantages and some disadvantages to this approach compared with loading data through publications, and at the end of the day we recommend always using publications to load data. Methods can be useful to fetch the result of a complex computation from the server that doesn't need to update when the server data changes. The biggest disadvantage of fetching data through Methods is that the data won't be automatically loaded into Minimongo, Meteor's client-side data cache, so you'll need to manage the lifecycle of that data manually.

Using a local collection to store and display data fetched from a Method Collections are a very convenient way of storing data on the client side. If you're fetching data using something other than subscriptions, you can put it in a collection manually. Let's look at an example where we have a complex algorithm for calculating average scores from a series of games for a number of players. We don't want to use a publication to load this data because we want to control exactly when it runs, and don't want the data to be cached automatically. First, you need to create a local collection - this is a collection that exists only on the client side and is not tied to a database collection on the server. Read more in the Collections article. // In client-side code, declare a local collection // by passing `null` as the argument ScoreAverages = new Mongo.Collection(null);

Now, if you fetch data using a Method, you can put into this collection: import { calculateAverages } from '../api/games/methods.js'; function updateAverages() { // Clean out result cache ScoreAverages.remove({}); // Call a Method that does an expensive computation calculateAverages.call((err, res) => { res.forEach((item) => { ScoreAverages.insert(item); }); }); }

88

Methods

We can now use the data from the local collection ScoreAverages inside a UI component exactly the same way we would use a regular MongoDB collection. Instead of it updating automatically, we'll need to call updateAverages every time we need new results.

Advanced concepts While you can easily use Methods in a simple app by following the Meteor introductory tutorial, it's important to understand exactly how they work to use them effectively in a production app. One of the downsides of using a framework like Meteor that does a lot for you under the hood is that you don't always understand what is going on, so it's good to learn some of the core concepts.

Method call lifecycle Here's exactly what happens, in order, when a Method is called:

1. Method simulation runs on the client If we defined this Method in client and server code, as all Methods should be, a Method simulation is executed in the client that called it. The client enters a special mode where it tracks all changes made to client-side collections, so that they can be rolled back later. When this step is complete, the user of your app sees their UI update instantly with the new content of the client-side database, but the server hasn't received any data yet. If an exception is thrown from the Method simulation, then by default Meteor ignores it and continues to step (2). If you are using ValidatedMethod or pass a special throwStubExceptions option to Meteor.apply , then an exception thrown from the simulation

will stop the server-side Method from running at all. The return value of the Method simulation is discarded, unless the returnStubValue option is passed when calling the Method, in which case it is returned to the Method caller. ValidatedMethod passes this option by default.

2. A `method` DDP message is sent to the server The Meteor client constructs a DDP message to send to the server. This includes the Method name, arguments, and an automatically generated Method ID that represents this particular Method invocation.

89

Methods

3. Method runs on the server When the server receives the message, it executes the Method code again on the server. The client side version was a simulation that will be rolled back later, but this time it's the real version that is writing to the actual database. Running the actual Method logic on the server is crucial because the server is a trusted environment where we know that security-critical code will run the way we expect.

4. Return value is sent to the client Once the Method has finished running on the server, it sends a result message to the client with the Method ID generated in step 2, and the return value itself. The client stores this for later use, but doesn't call the Method callback yet. If you pass the onResultReceived option to Meteor.apply , that callback is fired.

5. Any DDP publications affected by the Method are updated If we have any publications on the page that have been affected by the database writes from this Method, the server sends the appropriate updates to the client. Note that the client data system doesn't reveal these updates to the app UI until the next step.

6. `updated` message sent to the client, data replaced with server result, Method callback fires After the relevant data updates have been sent to the correct client, the server sends back the last message in the Method life cycle - the DDP updated message with the relevant Method ID. The client rolls back any changes to client side data made in the Method simulation in step 1, and replaces them with the actual changes sent from the server in step 5. Lastly, the callback passed to Meteor.call actually fires with the return value from step 4. It's important that the callback waits until the client is up to date, so that your Method callback can assume that the client state reflects any changes done inside the Method.

Error case In the list above, we didn't cover the case when the Method execution on the server throws an error. In that case, there is no return value, and the client gets an error instead. The Method callback is fired instantly with the returned error as the first argument. Read more about error handling in the section about errors below.

90

Methods

Benefits of Methods over REST We believe Methods provide a much better primitive for building modern applications than REST endpoints built on HTTP. Let's go over some of the things you get for free with Methods that you would have to worry about if using HTTP. The purpose of this section is not to convince you that REST is bad - it's just to remind you that you don't need to handle these things yourself in a Meteor app.

Methods use synchronous-style APIs, but are non-blocking You may notice in the example Method above, we didn't need to write any callbacks when interacting with MongoDB, but the Method still has the non-blocking properties that people associate with Node.js and callback-style code. Meteor uses a coroutine library called Fibers to enable you to write code that uses return values and throws errors, and avoid dealing with lots of nested callbacks.

Methods always run and return in order When accessing a REST API, you will sometimes run into a situation where you make two requests one after the other, but the results arrive out of order. Meteor's underlying machinery makes sure this never happens with Methods. When multiple Method calls are received from the same client, Meteor runs each Method to completion before starting the next one. If you need to disable this functionality for one particularly long-running Method, you can use this.unblock() to allow the next Method to run while the current one is still in progress. Also, since Meteor is based on Websockets instead of HTTP, all Method calls and results are guaranteed to arrive in the order they are sent. You can also pass a special option wait: true to Meteor.apply to wait to send a particular Method until all others have returned, and not send any other Methods until this one returns.

Change tracking for Optimistic UI When Method simulations and server-side executions run, Meteor tracks any resulting changes to the database. This is what lets the Meteor data system roll back the changes from the Method simulation and replace them with the actual writes from the server. Without this automatic database tracking, it would be very difficult to implement a correct Optimistic UI system.

Calling a Method from another Method

91

Methods

Sometimes, you'll want to call a Method from another Method. Perhaps you already have some functionality implemented and you want to add a wrapper that fills in some of the arguments automatically. This is a totally fine pattern, and Meteor does some nice things for you: 1. Inside a client-side Method simulation, calling another Method doesn't fire off an extra request to the server - the assumption is that the server-side implementation of the Method will do it. However, it does run the simulation of the called Method, so that the simulation on the client closely matches what will happen on the server. 2. Inside a Method execution on the server, calling another Method runs that Method as if it were called by the same client. That means the Method runs as usual, and the context - userId , connection , etc - are taken from the original Method call.

Consistent ID generation and optimistic UI When you insert documents into Minimongo from the client-side simulation of a Method, the _id field of each document is a random string. When the Method call is executed on the

server, the IDs are generated again before being inserted into the database. If it were implemented naively, it could mean that the IDs generated on the server are different, which would cause undesirable flickering and re-renders in the UI when the Method simulation was rolled back and replaced with the server data. But this is not the case in Meteor! Each Meteor Method invocation shares a random generator seed with the client that called the Method, so any IDs generated by the client and server Methods are guaranteed to be the same. This means you can safely use the IDs generated on the client to do things while the Method is being sent to the server, and be confident that the IDs will be the same when the Method finishes. One case where this is particularly useful is if you want to create a new document in the database, then immediately redirect to a URL that contains that new document's ID.

Method retries If you call a Method from the client, and the user's Internet connection disconnects before the result is received, Meteor assumes that the Method didn't actually run. When the connection is re-established, the Method call will be sent again. This means that, in certain situations, Methods can be sent more than once. This should only happen very rarely, but in the case where an extra Method call could have negative consequences it is worth putting in extra effort to ensure that Methods are idempotent - that is, calling them multiple times doesn't result in additional changes to the database.

92

Methods

Many Method operations are idempotent by default. Inserts will throw an error if they happen twice because the generated ID will conflict. Removes on collections won't do anything the second time, and most update operators like $set will have the same result if run again. The only places you need to worry about code running twice are MongoDB update operators that stack, like $inc and $push , and calls to external APIs.

Historical comparison with allow/deny The Meteor core API includes an alternative to Methods for manipulating data from the client. Instead of explicitly defining Methods with specific arguments, you can instead call insert , update , and remove directly from the client and specify security rules with allow

and deny . In the Meteor Guide, we are taking a strong position that this feature should be avoided and Methods used instead. Read more about the problems with allow/deny in the Security article. Historically, there have been some misconceptions about the features of Meteor Methods as compared with the allow/deny feature, including that it was more difficult to achieve Optimistic UI when using Methods. However, the client-side insert , update , and remove feature is actually implemented on top of Methods, so Methods are strictly more powerful. You get great default Optimistic UI just by defining your Method code on the client and the server, as described in the Method lifecycle section above.

93

Users and Accounts

After reading this article, you'll know: 1. What features in core Meteor enable user accounts 2. How to use accounts-ui for a quick prototype 3. How to use the useraccounts family of packages to build your login UI 4. How to build a fully-featured password login experience 5. How to enable login through OAuth providers like Facebook 6. How to add custom data to Meteor's users collection 7. How to manage user roles and permissions

Features in core Meteor Before we get into all of the different user-facing accounts functionality you can add with Meteor, let's go over some of the features built into the Meteor DDP protocol and accountsbase package. These are the parts of Meteor that you'll definitely need to be aware of if you

have any user accounts in your app; most of everything else is optional and added/removed via packages.

userId in DDP DDP is Meteor's built-in pub/sub and RPC protocol. You can read about how to use it in the Data Loading and Methods articles. In addition to the concepts of data loading and method calls, DDP has one more feature built in - the idea of a userId field on a connection. This is the place where login state is tracked, regardless of which accounts UI package or login service you are using. This built-in feature means that you always get this.userId inside Methods and Publications, and can access the user ID on the client. This is a great starting point for building your own custom accounts system, but most developers won't need to worry about the mechanics, since you'll mostly be interacting with the accounts-base package instead.

`accounts-base` This package is the core of Meteor's developer-facing user accounts functionality. This includes: 1. A users collection with a standard schema, accessed through Meteor.users , and the client-side singletons Meteor.userId() and Meteor.user() , which represent the login state on the client. 2. A variety of helpful other generic methods to keep track of login state, log out, validate users, etc. Visit the Accounts section of the docs to find a complete list.

94

Users and Accounts

3. An API for registering new login handlers, which is used by all of the other accounts packages to integrate with the accounts system. There isn't any official documentation for this API, but you can read more about it on the MeteorHacks blog. Usually, you don't need to include accounts-base yourself since it's added for you if you use accounts-password or similar, but it's good to be aware of what is what.

Fast prototyping with `accounts-ui` Often, a complicated accounts system is not the first thing you want to build when you're starting out with a new app, so it's useful to have something you can just drop in quickly. This is where accounts-ui comes in - it's just one line that you drop into your app to get an accounts system. To add it: meteor add accounts-ui

Then just include it anywhere in a Blaze template: {{> loginButtons}}

Then, make sure to pick a login provider; they will automatically integrate with accounts-ui : # pick one or more of the below meteor add accounts-password meteor add accounts-facebook meteor add accounts-google meteor add accounts-github meteor add accounts-twitter meteor add accounts-meetup meteor add accounts-meteor-developer

Now just open your app, follow the configuration steps, and you're good to go - if you've done the Meteor tutorial, you've already seen this in action. Of course, in a production application, you probably want a more custom user interface and some logic to have a more tailored UX, but that's why we have the rest of this guide. Here are a couple of screenshots of accounts-ui so you know what to expect:

95

Users and Accounts

Customizable UI: useraccounts Once you've gotten your initial prototype up and running with accounts-ui , you'll want to move to something more powerful and configurable so that you can better integrate your login flow with the rest of your app. The useraccounts family of packages is the most powerful set of accounts management UI controls available for Meteor today. If you need even more customization, you can also roll your own system, but it's worth trying useraccounts first.

Use any router or UI framework The first thing to understand about useraccounts is that the core accounts management logic is independent of the HTML templates and routing packages. This means you can use useraccounts:core to build your own set of login templates. Generally, you'll want to pick

one login template package and one login routing package. The options for templates include: useraccounts:unstyled which lets you bring your own CSS; this one is used in the

Todos example app to make the login UI blend seamlessly with the rest of the app.

96

Users and Accounts

Pre-built templates for Bootstrap, Semantic UI, Materialize, and more. These templates don't come with the actual CSS framework, so you can pick your favorite Bootstrap package, for example. While it's optional and the basic functionality will work without it, it's also a good idea to pick a router integration: Flow Router, the router recommended in this guide. Iron Router, another popular router in the Meteor community. In the example app we are using the Flow Router integration with great success. Some of the later sections will cover how to customize the routes and templates to fit your app better.

Drop-in UI without routing If you don't want to configure routing for your login flow, you can just drop in a self-managing accounts screen. Wherever you want the accounts UI template to render, just include the atForm template, like so:

{{> atForm}}

Once you configure routing according to the section below, you'll want to remove this inclusion.

Customizing templates For some apps, the off-the-shelf login templates provided by the various useraccounts UI packages will work as-is, but most apps will want to customize some of the presentation. There's a simple way to do that using the template replacement functionality of the aldeed:template-extension package.

First, figure out which template you want to replace by looking at the source code of the package. For example, in the useraccounts:unstyled package, the templates are listed in this directory on GitHub. By squinting at the file names and looking for some of the HTML strings, we can figure out that we might be interested in replacing the atPwdFormBtn template. Let's take a look at the original template: {{buttonText}}

97

Users and Accounts

Once you've identified which template you need to replace, define a new template. In this case, we want to modify the class on the button to work with the CSS for the rest of the app. There are a few things to keep in mind when overriding a template: 1. Render the helpers in the same way the previous template did. In this case we are using buttonText . 2. Keep any id attributes, like at-btn , since those are used for event handling. Here's what our new override template looks like: {{buttonText}}

Then, use the replaces function on the template to override the existing template from useraccounts :

Template['override-atPwdFormBtn'].replaces('atPwdFormBtn');

Customizing routes In addition to having control over the templates, you'll want to be able to control the routing and URLs for the different views offered by useraccounts . Since Flow Router is the officially recommended routing option for Meteor, we'll go over that in particular. First, we need to configure the layout we want to use when rendering the accounts templates: AccountsTemplates.configure({ defaultTemplate: 'Auth_page', defaultLayout: 'App_body', defaultContentRegion: 'main', defaultLayoutRegions: {} });

In this case, we want to use the App_body layout template for all of the accounts-related pages. This template has a content region called main . Now, let's configure some routes:

98

Users and Accounts

// Define these routes in a file loaded on both client and server AccountsTemplates.configureRoute('signIn', { name: 'signin', path: '/signin' }); AccountsTemplates.configureRoute('signUp', { name: 'join', path: '/join' }); AccountsTemplates.configureRoute('forgotPwd'); AccountsTemplates.configureRoute('resetPwd', { name: 'resetPwd', path: '/reset-password' });

Note that we have specified a password reset route. Normally, we would have to configure Meteor's accounts system to send this route in password reset emails, but the useraccounts:flow-routing package does it for us. Read more about configuring email flows

below. Now that the routes are setup on the server, they can be accessed from the browser (e.g. example.com/reset-password ). To create links to these routes in a template, it's best to use a

helper method provided by the router. For Flow Router, the arillo:flow-router-helpers package provides a pathFor helper for just this purpose. Once installed, the following is possible in a template: Sign In Join

You can find a complete list of different available routes in the documentation the useraccounts:flow-routing .

Further customization useraccounts offers many other customization options beyond templates and routing. Read

the useraccounts guide to learn about all of the other options.

Password login 99

Users and Accounts

Meteor comes with a secure and fully-featured password login system out of the box. To use it, add the package: meteor add accounts-password

To see what options are available to you, read the complete description of the accountspassword API in the Meteor docs.

Requiring username or email Note: You don't have to do this if you're using useraccounts . It disables the regular Meteor client-side account creation functions for you and does custom validation. By default, the Accounts.createUser function provided by accounts-password allows you to create an account with a username, email, or both. Most apps expect a specific combination of the two, so you will certainly want to validate the new user creation: // Ensuring every user has an email address, should be in server-side code Accounts.validateNewUser((user) => { new SimpleSchema({ _id: { type: String }, emails: { type: Array }, 'emails.$': { type: Object }, 'emails.$.address': { type: String }, 'emails.$.verified': { type: Boolean }, createdAt: { type: Date }, services: { type: Object, blackbox: true } }).validate(user); // Return true to allow user creation to proceed return true; });

Multiple emails Often, users might want to associate multiple email addresses with the same account. accounts-password addresses this case by storing the email addresses as an array in the

user collection. There are some handy API methods to deal with adding, removing, and verifying emails. One useful thing to add for your app can be the concept of a "primary" email address. This way, if the user has added multiple emails, you know where to send confirmation emails and similar.

100

Users and Accounts

Case sensitivity Before Meteor 1.2, all email addresses and usernames in the database were considered to be case-sensitive. This meant that if you registered an account as [email protected] , and then tried to log in with [email protected] , you'd see an error indicating that no user with that email exists. Of course, this can be quite confusing, so we decided to improve things in Meteor 1.2. But the situation was not as simple as it seemed; since MongoDB doesn't have a concept of case-insensitive indexes, it was impossible to guarantee unique emails at the database level. For this reason, we have some special APIs for querying and updating users which manage the case-sensitivity problem at the application level.

What does this mean for my app? Just follow one simple rule: don't query the database by username or email directly. Instead, use the Accounts.findUserByUsername and Accounts.findUserByEmail methods provided by Meteor. This will run a query for you that is case-insensitive, so you will always find the user you are looking for.

Email flows When you have a login system for your app based on user emails, that opens up the possibility for email-based account flows. The common thing between all of these workflows is that they involve sending a unique link to the user's email address, which does something special when it is clicked. Let's look at some common examples that Meteor's accountspassword package supports out of the box:

1. Password reset. When the user clicks the link in their email, they are taken to a page where they can enter a new password for their account. 2. User enrollment. A new user is created by an administrator, but no password is set. When the user clicks the link in their email, they are taken to a page where they can set a new password for their account. Very similar to password reset. 3. Email verification. When the user clicks the link in their email, the application records that this email does indeed belong to the correct user. Here, we'll talk about how to manage the whole process manually from start to finish.

Email works out of the box with accounts UI packages If you want something that just works out of the box, you can use accounts-ui or useraccounts which basically do everything for you. Only follow the directions below if you

definitely want to build all parts of the email flow yourself.

101

Users and Accounts

Sending the email accounts-password comes with handy functions that you can call from the server to send an

email. They are named for exactly what they do: 1.

Accounts.sendResetPasswordEmail

2.

Accounts.sendEnrollmentEmail

3.

Accounts.sendVerificationEmail

The email is generated using the email templates from Accounts.emailTemplates, and include links generated with Accounts.urls . We'll go into more detail about customizing the email content and URL later.

Identifying when the link is clicked When the user receives the email and clicks the link inside, their web browser will take them to your app. Now, you need to be able to identify these special links and act appropriately. If you haven't customized the link URL, then you can use some built-in callbacks to identify when the app is in the middle of an email flow. Normally, when the Meteor client connects to the server, the first thing it does is pass the login resume token to re-establish a previous login. However, when these callbacks from the email flow are triggered, the resume token is not sent until your code signals that it has finished handling the request by calling the done function that is passed into the registered callback. This means that if you were previously logged in as user A, and then you clicked the reset password link for user B, but then you cancelled the password reset flow by calling done() , the client would log in as A again.

1.

Accounts.onResetPasswordLink

2.

Accounts.onEnrollmentLink

3.

Accounts.onEmailVerificationLink

Here's how you would use one of these functions:

102

Users and Accounts

Accounts.onResetPasswordLink((token, done) => { // Display the password reset UI, get the new password... Accounts.resetPassword(token, newPassword, (err) => { if (err) { // Display error } else { // Resume normal operation done(); } }); })

If you want a different URL for your reset password page, you need to customize it using the Accounts.urls option:

Accounts.urls.resetPassword = (token) => { return Meteor.absoluteUrl(`reset-password/${token}`); };

If you have customized the URL, you will need to add a new route to your router that handles the URL you have specified, and the default Accounts.onResetPasswordLink and friends won't work for you.

Displaying an appropriate UI and completing the process Now that you know that the user is attempting to reset their password, set an initial password, or verify their email, you should display an appropriate UI to allow them to do so. For example, you might want to show a page with a form for the user to enter their new password. When the user submits the form, you need to call the appropriate function to commit their change to the database. Each of these functions takes the new value and the token you got from the event in the previous step. 1.

Accounts.resetPassword - this one should be used both for resetting the password, and

enrolling a new user; it accepts both kinds of tokens. 2.

Accounts.verifyEmail

After you have called one of the two functions above or the user has cancelled the process, call the done function you got in the link callback. This will tell Meteor to get out of the special state it enters when you're doing one of the email account flows.

Customizing accounts emails 103

Users and Accounts

You will probably want to customize the emails accounts-password will send on your behalf. This can be easily done through the Accounts.emailTemplates API. Below is some example code from the Todos app: Accounts.emailTemplates.siteName = "Meteor Guide Todos Example"; Accounts.emailTemplates.from = "Meteor Todos Accounts "; Accounts.emailTemplates.resetPassword = { subject(user) { return "Reset your password on Meteor Todos"; }, text(user, url) { return `Hello! Click the link below to reset your password on Meteor Todos. ${url} If you didn't request this email, please ignore it. Thanks, The Meteor Todos team ` }, html(user, url) { // This is where HTML email content would go. // See the section about html emails below. } };

As you can see, we can use the ES2015 template string functionality to generate a multi-line string that includes the password reset URL. We can also set a custom from address and email subject.

HTML emails If you've ever needed to deal with sending pretty HTML emails from an app, you know that it can quickly become a nightmare. Compatibility of popular email clients with basic HTML features like CSS is notoriously spotty, so it is hard to author something that works at all. Start with a responsive email template or framework, and then use a tool to convert your email content into something that is compatible with all email clients. This blog post by Mailgun covers some of the main issues with HTML email. In theory, a community package could extend Meteor's build system to do the email compilation for you, but at the time of writing we were not aware of any such packages.

OAuth login

104

Users and Accounts

In the distant past, it could have been a huge headache to get Facebook or Google login to work with your app. Thankfully, most popular login providers have standardized around some version of OAuth, and Meteor supports some of the most popular login services out of the box.

Facebook, Google, and more Here's a complete list of login providers for which Meteor actively maintains core packages: 1. Facebook with accounts-facebook 2. Google with accounts-google 3. GitHub with accounts-github 4. Twitter with accounts-twitter 5. Meetup with accounts-meetup 6. Meteor Developer Accounts with accounts-meteor-developer There is a package for logging in with Weibo, but it is no longer being actively maintained.

Logging in If you are using an off-the-shelf login UI like accounts-ui or useraccounts , you don't need to write any code after adding the relevant package from the list above. If you are building a login experience from scratch, you can log in programmatically using the Meteor.loginWith function. It looks like this:

Meteor.loginWithFacebook({ requestPermissions: ['user_friends', 'public_profile', 'email'] }, (err) => { if (err) { // handle error } else { // successful login! } });

Configuring OAuth There are a few points to know about configuring OAuth login: 1. Client ID and secret. It's best to keep your OAuth secret keys outside of your source code, and pass them in through Meteor.settings. Read how in the Security article. 2. Redirect URL. On the OAuth provider's side, you'll need to specify a redirect URL. The URL will look like: https://www.example.com/_oauth/facebook . Replace facebook with

105

Users and Accounts

the name of the service you are using. Note that you will need to configure two URLs one for your production app, and one for your development environment, where the URL might be something like http://localhost:3000/_oauth/facebook . 3. Permissions. Each login service provider should have documentation about which permissions are available. For example, here is the page for Facebook. If you want additional permissions to the user's data when they log in, pass some of these strings in the requestPermissions option to Meteor.loginWithFacebook or Accounts.ui.config . In the next section we'll talk about how to retrieve that data.

Calling service API for more data If your app supports or even requires login with an external service such as Facebook, it's natural to also want to use that service's API to request additional data about that user. For example, you might want to get a list of a Facebook user's photos. First, you'll need to request the relevant permissions when logging in the user. See the section above for how to pass those options. Then, you need to get the user's access token. You can find this token in the Meteor.users collection under the services field. For example, if you wanted to get a particular user's Facebook access token: // Given a userId, get the user's Facebook access token const user = Meteor.users.findOne(userId); const fbAccessToken = user.services.facebook.accessToken;

For more details about the data stored in the user database, read the section below about accessing user data. Now that you have the access token, you need to actually make a request to the appropriate API. Here you have two options: 1. Use the http package to access the service's API directly. You'll probably need to pass the access token from above in a header. For details you'll need to search the API documentation for the service. 2. Use a package from Atmosphere or npm that wraps the API into a nice JavaScript interface. For example, if you're trying to load data from Facebook you could use the fbgraph npm package. Read more about how to use npm with your app in the Build System article.

Loading and displaying user data 106

Users and Accounts

Meteor's accounts system, as implemented in accounts-base , also includes a database collection and generic functions for getting data about users.

Currently logged in user Once a user is logged into your app with one of the methods described above, it is useful to be able to identify which user is logged in, and get the data provided during the registration process.

On the client: Meteor.userId() For code that runs on the client, the global Meteor.userId() reactive function will give you the ID of the currently logged in user. In addition to that core API, there are some helpful shorthand helpers: Meteor.user() , which is exactly equal to calling Meteor.users.findOne(Meteor.userId()) , and the {% raw %} {{currentUser}}{% endraw %} Blaze helper that returns the value of Meteor.user() .

Note that there is a benefit to restricting the places you access the current user to make your UI more testable and modular. Read more about this in the UI article.

On the server: this.userId On the server, each connection has a different logged in user, so there is no global logged-in user state by definition. Since Meteor tracks the environment for each Method call, you can still use the Meteor.userId() global, which returns a different value depending on which Method you call it from, but you can run into edge cases when dealing with asynchronous code. Also, Meteor.userId() won't work inside publications. We suggest using the this.userId property on the context of Methods and publications instead, and passing that around through function arguments to wherever you need it. // Accessing this.userId inside a publication Meteor.publish('lists.private', function() { if (!this.userId) { return this.ready(); } return Lists.find({ userId: this.userId }, { fields: Lists.publicFields }); });

107

Users and Accounts

// Accessing this.userId inside a Method Meteor.methods({ 'todos.updateText'({ todoId, newText }) { new SimpleSchema({ todoId: { type: String }, newText: { type: String } }).validate({ todoId, newText }), const todo = Todos.findOne(todoId); if (!todo.editableBy(this.userId)) { throw new Meteor.Error('todos.updateText.unauthorized', 'Cannot edit todos in a private list that is not yours'); } Todos.update(todoId, { $set: { text: newText } }); } });

The Meteor.users collection Meteor comes with a default MongoDB collection for user data. It's stored in the database under the name users , and is accessible in your code through Meteor.users . The schema of a user document in this collection will depend on which login service was used to create the account. Here's an example of a user that created their account with accounts-password :

108

Users and Accounts

{ "_id": "DQnDpEag2kPevSdJY", "createdAt": "2015-12-10T22:34:17.610Z", "services": { "password": { "bcrypt": "XXX" }, "resume": { "loginTokens": [ { "when": "2015-12-10T22:34:17.615Z", "hashedToken": "XXX" } ] } }, "emails": [ { "address": "[email protected]", "verified": false } ] }

Here's what the same user would look like if they instead logged in with Facebook:

109

Users and Accounts

{ "_id": "Ap85ac4r6Xe3paeAh", "createdAt": "2015-12-10T22:29:46.854Z", "services": { "facebook": { "accessToken": "XXX", "expiresAt": 1454970581716, "id": "XXX", "email": "[email protected]", "name": "Ada Lovelace", "first_name": "Ada", "last_name": "Lovelace", "link": "https://www.facebook.com/app_scoped_user_id/XXX/", "gender": "female", "locale": "en_US", "age_range": { "min": 21 } }, "resume": { "loginTokens": [ { "when": "2015-12-10T22:29:46.858Z", "hashedToken": "XXX" } ] } }, "profile": { "name": "Sashko Stubailo" } }

Note that the schema is different when users register with different login services. There are a few things to be aware of when dealing with this collection: 1. User documents in the database have secret data like access keys and hashed passwords. When publishing user data to the client, be extra careful not to include anything that client shouldn't be able to see. 2. DDP, Meteor's data publication protocol, only knows how to resolve conflicts in top-level fields. This means that you can't have one publication send services.facebook.first_name and another send services.facebook.locale - one of

them will win, and only one of the fields will actually be available on the client. The best way to fix this is to denormalize the data you want onto custom top-level fields, as described in the section about custom user data. 3. The OAuth login service packages populate profile.name . We don't recommend using this but, if you plan to, make sure to deny client-side writes to profile . See the section

110

Users and Accounts

about the profile field on users. 4. When finding users by email or username, make sure to use the case-insensitive functions provided by accounts-password . See the section about case-sensitivity for more details.

Custom data about users As your app gets more complex, you will invariably need to store some data about individual users, and the most natural place to put that data is in additional fields on the Meteor.users collection described above. In a more normalized data situation it would be a good idea to keep Meteor's user data and yours in two separate tables, but since MongoDB doesn't deal well with data associations it makes sense to just use one collection.

Add top-level fields onto the user document The best way to store your custom data onto the Meteor.users collection is to add a new uniquely-named top-level field on the user document. For example, if you wanted to add a mailing address to a user, you could do it like this: // Using address schema from schema.org // https://schema.org/PostalAddress const newMailingAddress = { addressCountry: 'US', addressLocality: 'Seattle', addressRegion: 'WA', postalCode: '98052', streetAddress: "20341 Whitworth Institute 405 N. Whitworth" }; Meteor.users.update(userId, { $set: { mailingAddress: newMailingAddress } });

You can use any field name other than those used by the Accounts sytem.

Adding fields on user registration The code above is just code that you could run on the server inside a Meteor Method to set someone's mailing address. Sometimes, you want to set a field when the user first creates their account, for example to initialize a default value or compute something from their social data. You can do this using Accounts.onCreateUser :

111

Users and Accounts

// Generate user initials after Facebook login Accounts.onCreateUser((options, user) => { if (! user.services.facebook) { throw new Error('Expected login with Facebook only.'); } const { first_name, last_name } = user.services.facebook; user.initials = first_name[0].toUpperCase() + last_name[0].toUpperCase(); // Don't forget to return the new user object at the end! return user; });

Note that the user object provided doesn't have an _id field yet. If you need to do something with the new user's ID inside this function, a useful trick can be to generate the ID yourself: // Generate a todo list for each new user Accounts.onCreateUser((options, user) => { // Generate a user ID ourselves user._id = Random.id(); // Need to add the `random` package // Use the user ID we generated Lists.createListForUser(user._id); // Don't forget to return the new user object at the end! return user; });

Don't use profile There's a tempting existing field called profile that is added by default when a new user registers. This field was historically intended to be used as a scratch pad for user-specific data - maybe their image avatar, name, intro text, etc. Because of this, the profile field on every user is automatically writeable by that user from the client. It's also automatically published to the client for that particular user. It turns out that having a field writeable by default without making that super obvious might not be the best idea. There are many stories of new Meteor developers storing fields such as isAdmin on profile ... and then a malicious user can easily set that to true whenever they want, making themselves an admin. Even if you aren't concerned about this, it isn't a good idea to let malicious users store arbitrary amounts of data in your database. Rather than dealing with the specifics of this field, it can be helpful to just ignore its existence entirely. You can safely do that as long as you deny all writes from the client:

112

Users and Accounts

// Deny all client-side updates to user documents Meteor.users.deny({ update() { return true; } });

Even ignoring the security implications of profile , it isn't a good idea to put all of your app's custom data onto one field. As discussed in the Collections article, Meteor's data transfer protocol doesn't do deeply nested diffing of fields, so it's a good idea to flatten out your objects into many top-level fields on the document.

Publishing custom data If you want to access the custom data you've added to the Meteor.users collection in your UI, you'll need to publish it to the client. Mostly, you can just follow the advice in the Data Loading and Security articles. The most important thing to keep in mind is that user documents are certain to contain private data about your users. In particular, the user document includes hashed password data and access keys for external APIs. This means it's critically important to filter the fields of the user document that you send to any client. Note that in Meteor's publication and subscription system, it's totally fine to publish the same document multiple times with different fields - they will get merged internally and the client will see a consistent document with all of the fields together. So if you just added one custom field, you should just write a publication with that one field. Let's look at an example of how we might publish the initials field from above: Meteor.publish('Meteor.users.initials', function ({ userIds }) { // Validate the arguments to be what we expect new SimpleSchema({ userIds: { type: [String] } }).validate({ userIds }); // Select only the users that match the array of IDs passed in const selector = { _id: { $in: userIds } }; // Only return one field, `initials` const options = { fields: { initials: 1 } }; return Meteor.users.find(selector, options); });

113

Users and Accounts

This publication will let the client pass an array of user IDs it's interested in, and get the initials for all of those users.

Roles and permissions One of the main reasons you might want to add a login system to your app is to have permissions for your data. For example, if you were running a forum, you would want administrators or moderators to be able to delete any post, but normal users can only delete their own. This uncovers two different types of permissions: 1. Role-based permissions 2. Per-document permissions

alanning:roles The most popular package for role-based permissions in Meteor is alanning:roles . For example, here is how you would make a user into an administrator, or a moderator: // Give Alice the 'admin' role Roles.addUsersToRoles(aliceUserId, 'admin', Roles.GLOBAL_GROUP); // Give Bob the 'moderator' role for a particular category Roles.addUsersToRoles(bobsUserId, 'moderator', categoryId);

Now, let's say you wanted to check if someone was allowed to delete a particular forum post: const forumPost = Posts.findOne(postId); const canDelete = Roles.userIsInRole(userId, ['admin', 'moderator'], forumPost.categoryId); if (! canDelete) { throw new Meteor.Error('unauthorized', 'Only admins and moderators can delete posts.'); } Posts.remove(postId);

Note that we can check for multiple roles at once, and if someone has a role in the GLOBAL_GROUP , they are considered as having that role in every group. In this case, the

groups were by category ID, but you could use any unique identifier to make a group. Read more in the alanning:roles package documentation. 114

Users and Accounts

Per-document permissions Sometimes, it doesn't make sense to abstract permissions into "groups" - you just want documents to have owners and that's it. In this case, you can use a simpler strategy using collection helpers. Lists.helpers({ // ... editableBy(userId) { if (!this.userId) { return true; } return this.userId === userId; }, // ... });

Now, we can call this simple function to determine if a particular user is allowed to edit this list: const list = Lists.findOne(listId); if (! list.editableBy(userId)) { throw new Meteor.Error('unauthorized', 'Only list owners can edit private lists.'); }

Learn more about how to use collection helpers in the Collections article.

115

Testing

Introduction Testing allows you to ensure your application works the way you think it does, especially as your codebase changes over time. If you have good tests, you can refactor and rewrite code with confidence. Tests are also the most concrete form of documentation of expected behavior, since other developers can figure out how to use your code by reading the tests. Automated testing is critical because it allows you to run a far greater set of tests much more often than you could manually, allowing you to catch regression errors immediately.

Types of tests Entire books have been written on the subject of testing, so we will simply touch on some basics of testing here. The important thing to consider when writing a test is what part of the application you are trying to test, and how you are verifying the behavior works. Unit test: If you are testing one small module of your application, you are writing a unit test. You'll need to stub and mock other modules that your module usually leverages in order to isolate each test. You'll typically also need to spy on actions that the module takes to verify that they occur. Integration test: If you are testing that multiple modules behave properly in concert, you are writing an integration test. Such tests are much more complex and may require running code both on the client and on the server to verify that communication across that divide is working as expected. Typically an integration test will still isolate a part of the entire application and directly verify results in code. Acceptance test: If you want to write a test that can be run against any running version of your app and verifies at the browser level that the right things happen when you push the right buttons, then you are writing an acceptance test (sometimes called "end to end test"). Such tests typically try to hook into the application as little as possible, beyond perhaps setting up the right data to run a test against. Load test: Finally you may wish to test that your application works under typical load or see how much load it can handle before it falls over. This is called a load test or stress test. Such tests can be challenging to set up and typically aren't run often but are very important for confidence before a big production launch.

Challenges of testing in Meteor

116

Testing

In most ways, testing a Meteor app is no different from testing any other full stack JavaScript application. However, compared to more traditional backend or front-end focused frameworks, two factors can make testing a little more challenging: Client/server data: Meteor's data system makes it simple to bridge the client-server gap and often allows you to build your application without thinking about how data moves around. It becomes critical to test that your code does actually work correctly across that gap. In traditional frameworks where you spend a lot of time thinking about interfaces between client and server you can often get away with testing both sides of the interface in isolation, but Meteor's full app test mode makes it easy to write integration tests that cover the full stack. Another challenge here is creating test data in the client context; we'll discuss ways to do this in the section on generating test data below. Reactivity: Meteor's reactivity system is "eventually consistent" in the sense that when you change a reactive input to the system, you'll see the user interface change to reflect this some time later. This can be a challenge when testing, but there are some ways to wait until those changes happen to verify the results, for example Tracker.afterFlush() .

The 'meteor test' command The primary way to test your application in Meteor is the meteor test command. This loads your application in a special "test mode". What this does is: 1. Doesn't eagerly load any of our application code as Meteor normally would. 2. Does eagerly load any file in our application (including in imports/ folders) that look like *.test[s].* , or *.spec[s].* 3. Sets the Meteor.isTest flag to be true. 4. Starts up the test driver package (see below). The Meteor build tool and the meteor test command ignore any files located in any tests/ directory. This allows you to put tests in this directory that you can run using a

test runner outside of Meteor's built-in test tools and still not have those files loaded in your application. See Meteor's default file load order rules. What this means is that you can write tests in files with a certain filename pattern and know they'll not be included in normal builds of your app. When your app runs in test mode, those files will be loaded (and nothing else will), and they can import the modules you want to test. As we'll see this is ideal for unit tests and simple integration tests.

117

Testing

Additionally, Meteor offers a "full application" test mode. You can run this with meteor test -full-app .

This is similar to test mode, with key differences: 1. It loads test files matching *.app-test[s].* and *.app-spec[s].* . 2. It does eagerly load our application code as Meteor normally would. 3. Sets the Meteor.isAppTest flag to be true (instead of the Meteor.isTest flag). This means that the entirety of your application (including for instance the web server and client side router) is loaded and will run as normal. This enables you to write much more complex integration tests and also load additional files for acceptance tests. Note that there is another test command in the Meteor tool; meteor test-packages is a way of testing Atmosphere packages, which is discussed in the Writing Packages article.

Driver packages When you run a meteor test command, you must provide a --driver-package argument. A test driver is a mini-application that runs in place of your app and runs each of your defined tests, whilst reporting the results in some kind of user interface. There are two main kinds of test driver packages: Web reporters: Meteor applications that display a special test reporting web UI that you can view the test results in.

118

Testing

Console reporters: These run completely on the command-line and are primary used for automated testing like continuous integration (as we'll see, typically PhantomJS is used to drive such tests).

Recommended: Mocha In this article, we'll use the popular Mocha test runner alongside the Chai assertion library to test our application. In order to write and run tests in Mocha, we need to add an appropriate test driver package. There are several options. Choose the ones that makes sense for your app. You may depend on more than one and set up different test commands for different situations. practicalmeteor:mocha Runs client and server package or app tests and displays all results in a browser. Use spacejam for command line / CI support. dispatch:mocha-phantomjs Runs client and server package or app tests using PhantomJS and reports all results in the server console. Can be used for running tests on a CI server. Has a watch mode.

119

Testing

dispatch:mocha-browser Runs client and server package or app tests with Mocha reporting client results in a web browser and server results in the server console. Has a watch mode. dispatch:mocha Runs server-only package or app tests with Mocha and reports all results in the server console. Can be used for running tests on a CI server. Has a watch mode. These packages don't do anything in development or production mode. They declare themselves testOnly so they are not even loaded outside of testing. But when our app is run in test mode, the test driver package takes over, executing test code on both the client and server, and rendering results to the browser. Here's how we can add the practicalmeteor:mocha package to our app: meteor add practicalmeteor:mocha

Test Files Test files themselves (for example a file named todos-item.test.js or routing.appspecs.coffee ) can register themselves to be run by the test driver in the usual way for that

testing library. For Mocha, that's by using describe and it : describe('my module', function () { it('does something that should be tested', function () { // This code will be executed by the test driver when the app is started // in the correct mode }) })

Note that arrow function use with Mocha is discouraged.

Test data When your app is run in test mode, it is initialized with a clean test database. If you are running a test that relies on using the database, and specifically the content of the database, you'll need to perform some setup steps in your test to ensure the database is in the state you expect. There are some tools you can use to do this. To ensure the database is clean, the xolvio:cleaner package is useful. You can use it to reset the database in a beforeEach block:

120

Testing

import { resetDatabase } from 'meteor/xolvio:cleaner'; describe('my module', function () { beforeEach(function () { resetDatabase(); }); });

This technique will only work on the server. If you need to reset the database from a client test, you can use a method to do so: import { resetDatabase } from 'meteor/xolvio:cleaner'; // NOTE: Before writing a method like this you'll want to double check // that this file is only going to be loaded in test mode!! Meteor.methods({ 'test.resetDatabase': () => resetDatabase(), }); describe('my module', function (done) { beforeEach(function (done) { // We need to wait until the method call is done before moving on, so we // use Mocha's async mechanism (calling a done callback) Meteor.call('test.resetDatabase', done); }); });

As we've placed the code above in a test file, it will not load in normal development or production mode (which would be an incredibly bad thing!). If you create a Atmosphere package with a similar feature, you should mark it as testOnly and it will similarly only load in test mode.

Generating test data Often it's sensible to create a set of data to run your test against. You can use standard insert() calls against your collections to do this, but often it's easier to create factories

which help encode random test data. A great package to use to do this is dburles:factory . In the Todos example app, we define a factory to describe how to create a test todo item, using the faker npm package:

121

Testing

import faker from 'faker'; Factory.define('todo', Todos, { listId: () => Factory.get('list'), text: () => faker.lorem.sentence(), createdAt: () => new Date(), });

To use the factory in a test, we simply call Factory.create : // This creates a todo and a list in the database and returns the todo. const todo = Factory.create('todo'); // If we have a list already, we can pass in the id and avoid creating another: const list = Factory.create('list'); const todoInList = Factory.create('todo', { listId: list._id });

Mocking the database As Factory.create directly inserts documents into the collection that's passed into the Factory.define function, it can be a problem to use it on the client. However there's a neat

isolation trick that you can do to replace the server-backed Todos client collection with a mocked out local collection, that's encoded in the hwillson:stub-collections package. import StubCollections from 'meteor/hwillson:stub-collections'; import { Todos } from 'path/to/todos.js'; StubCollections.stub(Todos); // Now Todos is stubbed to a simple local collection mock, // so for instance on the client we can do: Todos.insert({ a: 'document' }); // Restore the `Todos` collection StubCollections.restore();

In a Mocha test, it makes sense to use stub-collections in a beforeEach / afterEach block.

Unit testing

122

Testing

Unit testing is the process of isolating a section of code and then testing that the internals of that section work as you expect. As we've split our code base up into ES2015 modules it's natural to test those modules one at a time. By isolating a module and simply testing its internal functionality, we can write tests that are fast and accurate---they can quickly tell you where a problem in your application lies. Note however that incomplete unit tests can often hide bugs because of the way they stub out dependencies. For that reason it's useful to combine unit tests with slower (and perhaps less commonly run) integration and acceptance tests.

A simple Blaze unit test In the Todos example app, thanks to the fact that we've split our User Interface into smart and reusable components, it's natural to want to unit test some of our reusable components (we'll see below how to integration test our smart components). To do so, we'll use a very simple test helper that renders a Blaze component off-screen with a given data context. As we place it in imports , it won't load in our app by in normal mode (as it's not required anywhere). imports/ui/test-helpers.js :

import { _ } from 'meteor/underscore'; import { Template } from 'meteor/templating'; import { Blaze } from 'meteor/blaze'; import { Tracker } from 'meteor/tracker'; const withDiv = function withDiv(callback) { const el = document.createElement('div'); document.body.appendChild(el); try { callback(el); } finally { document.body.removeChild(el); } }; export const withRenderedTemplate = function withRenderedTemplate(template, data, call back) { withDiv((el) => { const ourTemplate = _.isString(template) ? Template[template] : template; Blaze.renderWithData(ourTemplate, data, el); Tracker.flush(); callback(el); }); };

123

Testing

A simple example of a reusable component to test is the Todos_item template. Here's what a unit test looks like (you can see some others in the app repository). imports/ui/components/client/todos-item.tests.js :

/* eslint-env mocha */ /* eslint-disable func-names, prefer-arrow-callback */ import { Factory } from 'meteor/factory'; import { chai } from 'meteor/practicalmeteor:chai'; import { Template } from 'meteor/templating'; import { $ } from 'meteor/jquery';

import { withRenderedTemplate } from '../../test-helpers.js'; import '../todos-item.js'; describe('Todos_item', function () { beforeEach(function () { Template.registerHelper('_', key => key); }); afterEach(function () { Template.deregisterHelper('_'); }); it('renders correctly with simple data', function () { const todo = Factory.build('todo', { checked: false }); const data = { todo, onEditingChange: () => 0, }; withRenderedTemplate('Todos_item', data, el => { chai.assert.equal($(el).find('input[type=text]').val(), todo.text); chai.assert.equal($(el).find('.list-item.checked').length, 0); chai.assert.equal($(el).find('.list-item.editing').length, 0); }); }); });

Of particular interest in this test is the following:

Importing When we run our app in test mode, only our test files will be eagerly loaded. In particular, this means that in order to use our templates, we need to import them! In this test, we import todos-item.js , which itself imports todos.html (yes, you do need to import the HTML files

of your Blaze templates!)

124

Testing

Stubbing To be a unit test, we must stub out the dependencies of the module. In this case, thanks to the way we've isolated our code into a reusable component, there's not much to do; principally we need to stub out the {% raw %}{{_}}{% endraw %} helper that's created by the tap:i18n system. Note that we stub it out in a beforeEach and restore it the afterEach .

If you're testing code that makes use of globals, you'll need to import those globals. For instance if you have a global Todos collection and are testing this file: // logging.js export function logTodos() { console.log(Todos.findOne()); }

then you'll need to import Todos both in that file and in the test: // logging.js import { Todos } from './todos.js' export function logTodos() { console.log(Todos.findOne()); }

// logging.test.js import { Todos } from './todos.js' Todos.findOne = () => { return {text: "write a guide"} } import { logTodos } from './logging.js' // then test logTodos ...

Creating data We can use the Factory package's .build() API to create a test document without inserting it into any collection. As we've been careful not to call out to any collections directly in the reusable component, we can pass the built todo document directly into the template.

A simple React unit test

125

Testing

We can also apply the same structure to testing React components and recommend the Enzyme package, which simulates a React component's environment and allows you to query it using CSS selectors. A larger suite of tests is available in the react branch of the Todos app, but let's look at a simple example for now: import { Factory } from 'meteor/factory'; import React from 'react'; import { shallow } from 'enzyme'; import { chai } from 'meteor/practicalmeteor:chai'; import TodoItem from './TodoItem.jsx'; describe('TodoItem', () => { it('should render', () => { const todo = Factory.build('todo', { text: 'testing', checked: false }); const item = shallow(); chai.assert(item.hasClass('list-item')); chai.assert(!item.hasClass('checked')); chai.assert.equal(item.find('.editing').length, 0); chai.assert.equal(item.find('input[type="text"]').prop('defaultValue'), 'testing') ; }); });

The test is slightly simpler than the Blaze version above because the React sample app is not internationalized. Otherwise, it's conceptually identical. We use Enzyme's shallow function to render the TodoItem component, and the resulting object to query the document, and also to simulate user interactions. And here's an example of simulating a user checking the todo item:

126

Testing

import { Factory } from 'meteor/factory'; import React from 'react'; import { shallow } from 'enzyme'; import { sinon } from 'meteor/practicalmeteor:sinon'; import TodoItem from './TodoItem.jsx'; import { setCheckedStatus } from '../../api/todos/methods.js'; describe('TodoItem', () => { it('should update status when checked', () => { sinon.stub(setCheckedStatus, 'call'); const todo = Factory.create('todo', { checked: false }); const item = shallow(); item.find('input[type="checkbox"]').simulate('change', { target: { checked: true }, }); sinon.assert.calledWith(setCheckedStatus.call, { todoId: todo._id, newCheckedStatus: true, }); setCheckedStatus.call.restore(); }); });

In this case, the TodoItem component calls a Meteor Method setCheckedStatus when the user clicks, but this is a unit test so there's no server running. So we stub it out using Sinon. After we simulate the click, we verify that the stub was called with the correct arguments. Finally, we clean up the stub and restore the original method behavior.

Running unit tests To run the tests that our app defines, we run our app in test mode: meteor test --driver-package practicalmeteor:mocha

As we've defined a test file ( imports/todos/todos.tests.js ), what this means is that the file above will be eagerly loaded, adding the 'builds correctly from factory' test to the Mocha registry. To run the tests, visit http://localhost:3000 in your browser. This kicks off practicalmeteor:mocha , which runs your tests both in the browser and on the server. It

displays the test results in the browser in a Mocha test reporter:

127

Testing

Usually, while developing an application, it makes sense to run meteor test on a second port (say 3100 ), while also running your main application in a separate process: # in one terminal window meteor # in another meteor test --driver-package practicalmeteor:mocha --port 3100

Then you can open two browser windows to see the app in action while also ensuring that you don't break any tests as you make changes.

Isolation techniques In the unit tests above we saw a very limited example of how to isolate a module from the larger app. This is critical for proper unit testing. Some other utilities and techniques include:

128

Testing

The velocity:meteor-stubs package, which creates simple stubs for most Meteor core objects. Alternatively, you can also use tools like Sinon to stub things directly, as we'll see for example in our simple integration test. The hwillson:stub-collections package we mentioned above. There's a lot of scope for better isolation and testing utilities.

Testing publications Using the johanbrook:publication-collector package, you're able to test individual publication's output without needing to create a traditional subscription: describe('lists.public', function () { it('sends all public lists', function (done) { // Set a user id that will be provided to the publish function as `this.userId`, // in case you want to test authentication. const collector = new PublicationCollector({userId: 'some-id'}); // Collect the data published from the `lists.public` publication. collector.collect('lists.public', (collections) => { // `collections` is a dictionary with collection names as keys, // and their published documents as values in an array. // Here, documents from the collection 'Lists' are published. chai.assert.typeOf(collections.Lists, 'array'); chai.assert.equal(collections.Lists.length, 3); done(); }); }); });

Note that user documents – ones that you would normally query with Meteor.users.find() – will be available as the key users on the dictionary passed from a PublicationCollector.collect() call. See the tests in the package for more details.

Integration testing An integration test is a test that crosses module boundaries. In the simplest case, this simply means something very similar to a unit test, where you perform your isolation around multiple modules, creating a non-singular "system under test".

129

Testing

Although conceptually different to unit tests, such tests typically do not need to be run any differently to unit tests and can use the same meteor test mode and isolation techniques as we use for unit tests. However, an integration test that crosses the client-server boundary of a Meteor application (where the modules under test cross that boundary) requires a different testing infrastructure, namely Meteor's "full app" testing mode. Let's take a look at example of both kinds of tests.

Simple integration test Our reusable components were a natural fit for a unit test; similarly our smart components tend to require an integration test to really be exercised properly, as the job of a smart component is to bring data together and supply it to a reusable component. In the Todos example app, we have an integration test for the Lists_show_page smart component. This test simply ensures that when the correct data is present in the database, the template renders correctly -- that it is gathering the correct data as we expect. It isolates the rendering tree from the more complex data subscription part of the Meteor stack. If we wanted to test that the subscription side of things was working in concert with the smart component, we'd need to write a full app integration test. imports/ui/components/client/todos-item.tests.js :

/* eslint-env mocha */ /* eslint-disable func-names, prefer-arrow-callback */ import { Meteor } from 'meteor/meteor'; import { Factory } from 'meteor/factory'; import { Random } from 'meteor/random'; import { chai } from 'meteor/practicalmeteor:chai'; import StubCollections from 'meteor/hwillson:stub-collections'; import { Template } from 'meteor/templating'; import { _ } from 'meteor/underscore'; import { $ } from 'meteor/jquery'; import { FlowRouter } from 'meteor/kadira:flow-router'; import { sinon } from 'meteor/practicalmeteor:sinon';

import { withRenderedTemplate } from '../../test-helpers.js'; import '../lists-show-page.js'; import { Todos } from '../../../api/todos/todos.js'; import { Lists } from '../../../api/lists/lists.js'; describe('Lists_show_page', function () { const listId = Random.id();

130

Testing

beforeEach(function () { StubCollections.stub([Todos, Lists]); Template.registerHelper('_', key => key); sinon.stub(FlowRouter, 'getParam', () => listId); sinon.stub(Meteor, 'subscribe', () => ({ subscriptionId: 0, ready: () => true, })); }); afterEach(function () { StubCollections.restore(); Template.deregisterHelper('_'); FlowRouter.getParam.restore(); Meteor.subscribe.restore(); }); it('renders correctly with simple data', function () { Factory.create('list', { _id: listId }); const timestamp = new Date(); const todos = _.times(3, i => Factory.create('todo', { listId, createdAt: new Date(timestamp - (3 - i)), })); withRenderedTemplate('Lists_show_page', {}, el => { const todosText = todos.map(t => t.text).reverse(); const renderedText = $(el).find('.list-items input[type=text]') .map((i, e) => $(e).val()) .toArray(); chai.assert.deepEqual(renderedText, todosText); }); }); });

Of particular interest in this test is the following:

Importing As we'll run this test in the same way that we did our unit test, we need to import the relevant modules under test in the same way that we did in the unit test.

Stubbing As the system under test in our integration test has a larger surface area, we need to stub out a few more points of integration with the rest of the stack. Of particular interest here is our use of the hwillson:stub-collections package and of Sinon to stub out Flow Router

131

Testing

and our Subscription.

Creating data In this test, we used Factory package's .create() API, which inserts data into the real collection. However, as we've proxied all of the Todos and Lists collection methods onto a local collection (this is what hwillson:stub-collections is doing), we won't run into any problems with trying to perform inserts from the client. This integration test can be run the exact same way as we ran unit tests above.

Full-app integration test In the Todos example application, we have a integration test which ensures that we see the full contents of a list when we route to it, which demonstrates a few techniques of integration tests. imports/startup/client/routes.app-test.js :

/* eslint-env mocha */ /* eslint-disable func-names, prefer-arrow-callback */ import { Meteor } from 'meteor/meteor'; import { Tracker } from 'meteor/tracker'; import { DDP } from 'meteor/ddp-client'; import { FlowRouter } from 'meteor/kadira:flow-router'; import { assert } from 'meteor/practicalmeteor:chai'; import { Promise } from 'meteor/promise'; import { $ } from 'meteor/jquery'; import { denodeify } from '../../utils/denodeify'; import { generateData } from './../../api/generate-data.app-tests.js'; import { Lists } from '../../api/lists/lists.js'; import { Todos } from '../../api/todos/todos.js';

// Utility -- returns a promise which resolves when all subscriptions are done const waitForSubscriptions = () => new Promise(resolve => { const poll = Meteor.setInterval(() => { if (DDP._allSubscriptionsReady()) { Meteor.clearInterval(poll); resolve(); } }, 200); }); // Tracker.afterFlush runs code when all consequent of a tracker based change // (such as a route change) have occured. This makes it a promise.

132

Testing

const afterFlushPromise = denodeify(Tracker.afterFlush); if (Meteor.isClient) { describe('data available when routed', () => { // First, ensure the data that we expect is loaded on the server // Then, route the app to the homepage beforeEach(() => generateData() .then(() => FlowRouter.go('/')) .then(waitForSubscriptions) ); describe('when logged out', () => { it('has all public lists at homepage', () => { assert.equal(Lists.find().count(), 3); }); it('renders the correct list when routed to', () => { const list = Lists.findOne(); FlowRouter.go('Lists.show', { _id: list._id }); return afterFlushPromise() .then(waitForSubscriptions) .then(() => { assert.equal($('.title-wrapper').html(), list.name); assert.equal(Todos.find({ listId: list._id }).count(), 3); }); }); }); }); }

Of note here: Before running, each test sets up the data it needs using the generateData helper (see the section on creating integration test data for more detail) then goes to the homepage. Although Flow Router doesn't take a done callback, we can use Tracker.afterFlush to wait for all its reactive consequences to occur. Here we wrote a little utility (which could be abstracted into a general package) to wait for all the subscriptions which are created by the route change (the todos.inList subscription in this case) to become ready before checking their data.

Running full-app tests To run the full-app tests in our application, we run: meteor test --full-app --driver-package practicalmeteor:mocha

133

Testing

When we connect to the test instance in a browser, we want to render a testing UI rather than our app UI, so the mocha-web-reporter package will hide any UI of our application and overlay it with its own. However the app continues to behave as normal, so we are able to route around and check the correct data is loaded.

Creating data To create test data in full-app test mode, it usually makes sense to create some special test methods which we can call from the client side. Usually when testing a full app, we want to make sure the publications are sending through the correct data (as we do in this test), and so it's not sufficient to stub out the collections and place synthetic data in them. Instead we'll want to actually create data on the server and let it be published. Similar to the way we cleared the database using a method in the beforeEach in the test data section above, we can call a method to do that before running our tests. In the case of our routing tests, we've used a file called imports/api/generate-data.app-tests.js which defines this method (and will only be loaded in full app test mode, so is not available in general!):

134

Testing

// This file will be auto-imported in the app-test context, // ensuring the method is always available import { Meteor } from 'meteor/meteor'; import { Factory } from 'meteor/factory'; import { resetDatabase } from 'meteor/xolvio:cleaner'; import { Random } from 'meteor/random'; import { _ } from 'meteor/underscore'; import { denodeify } from '../utils/denodeify'; const createList = (userId) => { const list = Factory.create('list', { userId }); _.times(3, () => Factory.create('todo', { listId: list._id })); return list; }; // Remember to double check this is a test-only file before // adding a method like this! Meteor.methods({ generateFixtures() { resetDatabase(); // create 3 public lists _.times(3, () => createList()); // create 3 private lists _.times(3, () => createList(Random.id())); }, }); let generateData; if (Meteor.isClient) { // Create a second connection to the server to use to call // test data methods. We do this so there's no contention // with the currently tested user's connection. const testConnection = Meteor.connect(Meteor.absoluteUrl()); generateData = denodeify((cb) => { testConnection.call('generateFixtures', cb); }); } export { generateData };

Note that we've exported a client-side symbol generateData which is a promisified version of the method call, which makes it simpler to use this sequentially in tests. Also of note is the way we use a second DDP connection to the server in order to send these test "control" method calls.

135

Testing

Acceptance testing Acceptance testing is the process of taking an unmodified version of our application and testing it from the "outside" to make sure it behaves in a way we expect. Typically if an app passes acceptance tests, we have done our job properly from a product perspective. As acceptance tests test the behavior of the application in a full browser context in a generic way, there are a range of tools that you can use to specify and run such tests. In this guide we'll demonstrate using Chimp, an acceptance testing tool with a few neat Meteor-specific features that makes it easy to use. Chimp requires node version 4 or 5. You can check your node version by running: node -v

You can install version 4 from nodejs.org or version 5 with brew install node . Then we can install the Chimp tool globally using: npm install --global chimp

Note that you can also install Chimp as a devDependency in your package.json but you may run into problems deploying your application as it includes binary dependencies. You can avoid such problems by running meteor npm prune to remove non-production dependencies before deploying. Chimp has a variety of options for setting it up, but we can add some npm scripts which will run the currently tests we define in Chimp's two main modes. We can add them to our package.json :

{ "scripts": { "chimp-watch": "chimp --ddp=http://localhost:3000 --watch --mocha --path=tests", "chimp-test": "chimp --mocha --path=tests" } }

Chimp will now look in the tests/ directory (otherwise ignored by the Meteor tool) for files in which you define acceptance tests. In the Todos example app, we define a simple test that ensures we can click the "create list" button. tests/lists.js :

136

Testing

/* eslint-env mocha */ /* eslint-disable func-names, prefer-arrow-callback */ // These are Chimp globals /* globals browser assert server */ function countLists() { browser.waitForExist('.list-todo'); const elements = browser.elements('.list-todo'); return elements.value.length; }; describe('list ui', function () { beforeEach(function () { browser.url('http://localhost:3000'); server.call('generateFixtures'); }); it('can create a list @watch', function () { const initialCount = countLists(); browser.click('.js-new-list'); assert.equal(countLists(), initialCount + 1); }); });

Running acceptance tests To run acceptance tests, we simply need to start our Meteor app as usual, and point Chimp at it. In one terminal, we can do: meteor

In another: meteor npm run chimp-watch

The chimp-watch command will then run the test in a browser, and continue to re-run it as we change the test or the application. (Note that the test assumes we are running the app on port 3000 ).

137

Testing

Thus it's a good way to develop the test---this is why chimp has a feature where we mark tests with a @watch in the name to call out the tests we want to work on (running our entire acceptance test suite can be time consuming in a large application). The chimp-test command will run all of the tests once only and is good for testing that our suite passes, either as a manual step, or as part of a continuous integration process.

Creating data Although we can run the acceptance test against our "pure" Meteor app, as we've done above, it often makes sense to start our meteor server with a special test driver, tmeasday:acceptance-test-driver . (You'll need to meteor add it to your app):

meteor test --full-app --driver-package tmeasday:acceptance-test-driver

The advantage of running our acceptance test suite pointed at an app that runs in full app test mode is that all of the data generating methods that we've created remain available. Otherwise the acceptance-test-driver does nothing. In Chimp tests, you have a DDP connection to the server available on the server variable. You can thus use server.call() (which is wrapped to be synchronous in Chimp tests) to call these methods. This is a convenient way to share data preparation code between acceptance and integration tests.

Continuous Integration Continuous integration testing is the process of running tests on every commit of your project. There are two principal ways to do it: on the developer's machine before allowing them to push code to the central repository, and on a dedicated CI server after each push. Both techniques are useful, and both require running tests in a commandline-only fashion.

Command line We've seen one example of running tests on the command line, using our meteor npm run chimp-test mode.

We can also use a command-line driver for Mocha dispatch:mocha-phantomjs to run our standard tests on the command line. Adding and using the package is straightforward:

138

Testing

meteor add dispatch:mocha-phantomjs meteor test --once --driver-package dispatch:mocha-phantomjs

(The --once argument ensures the Meteor process stops once the test is done). We can also add that command to our package.json as a test script: { "scripts": { "test": "meteor test --once --driver-package dispatch:mocha-phantomjs" } }

Now we can run the tests with meteor npm test .

CircleCI CircleCI is a great continuous integration service that allows us to run (possibly time consuming) tests on every push to a repository like GitHub. To use it with the commandline test we've defined above, we can follow their standard getting started tutorial and use a circle.yml file similar to this:

machine: node: version: 0.10.43 dependencies: override: - curl https://install.meteor.com | /bin/sh - npm install checkout: post: - git submodule update --init

139

URLs and Routing

After reading this guide, you'll know: 1. The role URLs play in a client-rendered app, and how it's different from a traditional server-rendered app. 2. How to define client and server routes for your app using Flow Router. 3. How to have your app display different content depending on the URL. 4. How to construct links to routes and go to routes programmatically.

Client-side Routing In a web application, routing is the process of using URLs to drive the user interface (UI). URLs are a prominent feature in every single web browser, and have several main functions from the user's point of view: 1. Bookmarking - Users can bookmark URLs in their web browser to save content they want to come back to later. 2. Sharing - Users can share content with others by sending a link to a certain page. 3. Navigation - URLs are used to drive the web browser's back/forward functions. In a traditional web application stack, where the server renders HTML one page at a time, the URL is the fundamental entry point for the user to access the application. Users navigate an application by clicking through URLs, which are sent to the server via HTTP, and the server responds appropriately via a server-side router. In contrast, Meteor operates on the principle of data on the wire, where the server doesn’t think in terms of URLs or HTML pages. The client application communicates with the server over DDP. Typically as an application loads, it initializes a series of subscriptions which fetch the data required to render the application. As the user interacts with the application, different subscriptions may load, but there’s no technical need for URLs to be involved in this process - you could easily have a Meteor app where the URL never changes. However, most of the user-facing features of URLs listed above are still relevant for typical Meteor applications. Since the server is not URL-driven, the URL just becomes a useful representation of the client-side state the user is currently looking at. However, unlike in a server-rendered application, it does not need to describe the entirety of the user’s current state; it simply needs to contain the parts that you want to be linkable. For example, the URL should contain any search filters applied on a page, but not necessarily the state of a dropdown menu or popup.

Using Flow Router

140

URLs and Routing

To add routing to your app, install the kadira:flow-router package: meteor add kadira:flow-router

Flow Router is a community routing package for Meteor. At the time of writing this guide, it is at version 2.x. For detailed information about all of the features Flow Router has to offer, refer to the Kadira Meteor routing guide.

Defining a simple route The basic purpose of a router is to match certain URLs and perform actions as a result. This all happens on the client side, in the app user's browser or mobile app container. Let's take an example from the Todos example app: FlowRouter.route('/lists/:_id', { name: 'Lists.show', action(params, queryParams) { console.log("Looking at a list?"); } });

This route handler will run in two situations: if the page loads initially at a URL that matches the URL pattern, or if the URL changes to one that matches the pattern while the page is open. Note that, unlike in a server-side-rendered app, the URL can change without any additional requests to the server. When the route is matched, the action method executes, and you can perform any actions you need to. The name property of the route is optional, but will let us refer to this route more conveniently later on.

URL pattern matching Consider the following URL pattern, used in the code snippet above: '/lists/:_id'

The above pattern will match certain URLs. You may notice that one segment of the URL is prefixed by : - this means that it is a url parameter, and will match any string that is present in that segment of the path. Flow Router will make that part of the URL available on the params property of the current route.

141

URLs and Routing

Additionally, the URL could contain an HTTP query string (the part after an optional ? ). If so, Flow Router will also split it up into named parameters, which it calls queryParams . Here are some example URLs and the resulting params and queryParams : URL

matches pattern?

params

queryParams

/

no

/about

no

/lists/

no

/lists/eMtGij5AFESbTKfkT

yes

{ _id: "eMtGij5AFESbTKfkT"}

{ }

/lists/1

yes

{ _id: "1"}

{ }

/lists/1?todoSort=top

yes

{ _id: "1"}

{ todoSort: "top" }

Note that all of the values in params and queryParams are always strings since URLs don't have any way of encoding data types. For example, if you wanted a parameter to represent a number, you might need to use parseInt(value, 10) to convert it when you access it.

Accessing Route information In addition to passing in the parameters as arguments to the action function on the route, Flow Router makes a variety of information available via (reactive and otherwise) functions on the global singleton FlowRouter . As the user navigates around your app, the values of these functions will change (reactively in some cases) correspondingly. Like any other global singleton in your application (see the data loading for info about stores), it's best to limit your access to FlowRouter . That way the parts of your app will remain modular and more independent. In the case of FlowRouter , it's best to access it solely from the top of your component hierarchy, either in the "page" component, or the layouts that wrap it. Read more about accessing data in the UI article.

The current route It's useful to access information about the current route in your code. Here are some reactive functions you can call: FlowRouter.getRouteName() gets the name of the route FlowRouter.getParam(paramName) returns the value of a single URL parameter FlowRouter.getQueryParam(paramName) returns the value of a single URL query

142

URLs and Routing

parameter In our example of the list page from the Todos app, we access the current list's id with FlowRouter.getParam('_id') (we'll see more on this below).

Highlighting the active route One situation where it is sensible to access the global FlowRouter singleton to access the current route's information deeper in the component hierarchy is when rendering links via a navigation component. It's often required to highlight the "active" route in some way (this is the route or section of the site that the user is currently looking at). A convenient package for this is zimme:active-route : meteor add zimme:active-route

In the Todos example app, we link to each list the user knows about in the App_body template: {{#each list in lists}} ... {{list.name}} {{/each}}

We can determine if the user is currently viewing the list with the activeListClass helper: Template.App_body.helpers({ activeListClass(list) { const active = ActiveRoute.name('Lists.show') && FlowRouter.getParam('_id') === list._id; return active && 'active'; } });

Rendering based on the route Now we understand how to define routes and access information about the current route, we are in a position to do what you usually want to do when a user accesses a route---render a user interface to the screen that represents it.

143

URLs and Routing

In this section, we'll discuss how to render routes using Blaze as the UI engine. If you are building your app with React or Angular, you will end up with similar concepts but the code will be a bit different. When using Flow Router, the simplest way to display different views on the page for different URLs is to use the complementary Blaze Layout package. First, make sure you have the Blaze Layout package installed: meteor add kadira:blaze-layout

To use this package, we need to define a "layout" component. In the Todos example app, that component is called App_body : ... {{> Template.dynamic template=main}} ...

(This is not the entire App_body component, but we highlight the most important part here). Here, we are using a Blaze feature called Template.dynamic to render a template which is attached to the main property of the data context. Using Blaze Layout, we can change that main property when a route is accessed.

We do that in the action function of our Lists.show route definition: FlowRouter.route('/lists/:_id', { name: 'Lists.show', action() { BlazeLayout.render('App_body', {main: 'Lists_show_page'}); } });

What this means is that whenever a user visits a URL of the form /lists/X , the Lists.show route will kick in, triggering the BlazeLayout call to set the main property of

the App_body component.

Components as pages Notice that we called the component to be rendered Lists_show_page (rather than Lists_show ). This indicates that this template is rendered directly by a Flow Router action

and forms the 'top' of the rendering hierarchy for this URL.

144

URLs and Routing

The Lists_show_page template renders without arguments---it is this template's responsibility to collect information from the current route, and then pass this information down into its child templates. Correspondingly the Lists_show_page template is very tied to the route that rendered it, and so it needs to be a smart component. See the article on UI/UX for more about smart and reusable components. It makes sense for a "page" smart component like Lists_show_page to: 1. Collect route information, 2. Subscribe to relevant subscriptions, 3. Fetch the data from those subscriptions, and 4. Pass that data into a sub-component. In this case, the HTML template for Lists_show_page will look very simple, with most of the logic in the JavaScript code: {{#each listId in listIdArray}} {{> Lists_show (listArgs listId)}} {{else}} {{> App_notFound}} {{/each}}

(The {% raw %}{{#each listId in listIdArray}}{% endraw %}} is an animation technique for page to page transitions).

145

URLs and Routing

Template.Lists_show_page.helpers({ // We use #each on an array of one item so that the "list" template is // removed and a new copy is added when changing lists, which is // important for animation purposes. listIdArray() { const instance = Template.instance(); const listId = instance.getListId(); return Lists.findOne(listId) ? [listId] : []; }, listArgs(listId) { const instance = Template.instance(); return { todosReady: instance.subscriptionsReady(), // We pass `list` (which contains the full list, with all fields, as a function // because we want to control reactivity. When you check a todo item, the // `list.incompleteCount` changes. If we didn't do this the entire list would // re-render whenever you checked an item. By isolating the reactiviy on the list // to the area that cares about it, we stop it from happening. list() { return Lists.findOne(listId); }, // By finding the list with only the `_id` field set, we don't create a dependen cy on the // `list.incompleteCount`, and avoid re-rendering the todos when it changes todos: Lists.findOne(listId, {fields: {_id: true}}).todos() }; } });

It's the listShow component (a reusuable component) that actually handles the job of rendering the content of the page. As the page component is passing the arguments into the reusuable component, it is able to be quite mechanical and the concerns of talking to the router and rendering the page have been separated.

Changing page when logged out There are types of rendering logic that appear related to the route but which also seem related to user interface rendering. A classic example is authorization; for instance, you may want to render a login form for some subset of your pages if the user is not yet logged in. It's best to keep all logic around what to render in the component hierarchy (i.e. the tree of rendered components). So this authorization should happen inside a component. Suppose we wanted to add this to the Lists_show_page we were looking at above. We could do something like:

146

URLs and Routing

{{#if currentUser}} {{#each listId in listIdArray}} {{> Lists_show (listArgs listId)}} {{else}} {{> App_notFound}} {{/each}} {{else}} Please log in to edit posts. {{/if}}

Of course, we might find that we need to share this functionality between multiple pages of our app that require access control. We can easily share functionality between templates by wrapping them in a wrapper "layout" component which includes the behavior we want. You can create wrapper components by using the "template as block helper" ability of Blaze (see the Blaze Article). Here's how we could write an authorization template: {{#if currentUser}} {{> Template.contentBlock}} {{else}} Please log in see this page. {{/if}}

Once that template exists, we can simply wrap our Lists_show_page : {{#App_forceLoggedIn}} {{#each listId in listIdArray}} {{> Lists_show (listArgs listId)}} {{else}} {{> App_notFound}} {{/each}} {{/App_forceLoggedIn}}

The main advantage of this approach is that it is immediately clear when viewing the Lists_show_page what behavior will occur when a user visits the page.

Multiple behaviors of this type can be composed by wrapping a template in multiple wrappers, or creating a meta-wrapper that combines multiple wrapper templates.

147

URLs and Routing

Changing Routes Rendering an updated UI when a user reaches a new route is not that useful without giving the user some way to reach a new route! The simplest way is with the trusty tag and a URL. You can generate the URLs yourself using FlowRouter.pathFor , but it is more convenient to use the arillo:flow-router-helpers package that defines some helpers for you: meteor add arillo:flow-router-helpers

Now that you have this package, you can use helpers in your templates to display a link to a certain route. For example, in the Todos example app, our nav links look like:

Routing programmatically In some cases you want to change routes based on user action outside of them clicking on a link. For instance, in the example app, when a user creates a new list, we want to route them to the list they just created. We do this by calling FlowRouter.go() once we know the id of the new list: import { insert } from '../../api/lists/methods.js'; Template.App_body.events({ 'click .js-new-list'() { const listId = insert.call(); FlowRouter.go('Lists.show', { _id: listId }); } });

You can also change only part of the URL if you want to, using the FlowRouter.setParams() and FlowRouter.setQueryParams() . For instance, if we were viewing one list and wanted to go to another, we could write: FlowRouter.setParams({_id: newList._id});

Of course, calling FlowRouter.go() , will always work, so unless you are trying to optimize for a specific situation it's better to use that.

148

URLs and Routing

Storing data in the URL As we discussed in the introduction, the URL is really just a serialization of some part of the client-side state the user is looking at. Although parameters can only be strings, it's possible to convert any type of data to a string by serializing it. In general if you want to store arbitrary serializable data in a URL param, you can use EJSON.stringify() to turn it into a string. You'll need to URL-encode the string using encodeURIComponent to remove any characters that have meaning in a URL:

FlowRouter.setQueryParams({data: encodeURIComponent(EJSON.stringify(data))});

You can then get the data back out of Flow Router using EJSON.parse() . Note that Flow Router does the URL decoding for you automatically: const data = EJSON.parse(FlowRouter.getQueryParam('data'));

Redirecting Sometimes, your users will end up on a page that isn't a good place for them to be. Maybe the data they were looking for has moved, maybe they were on an admin panel page and logged out, or maybe they just created a new object and you want them to end up on the page for the thing they just created. Usually, we can redirect in response to a user's action by calling FlowRouter.go() and friends, like in our list creation example above, but if a user browses directly to a URL that doesn't exist, it's useful to know how to redirect immediately. If a URL is simply out-of-date (sometimes you might change the URL scheme of an application), you can redirect inside the action function of the route: FlowRouter.route('/old-list-route/:_id', { action(params) { FlowRouter.go('Lists.show', params); } });

Redirecting dynamically

149

URLs and Routing

The above approach will only work for static redirects. However, sometimes you need to load some data to figure out where to redirect to. In this case you'll need to render part of the component hierarchy to subscribe to the data you need. For example, in the Todos example app, we want to make the root ( / ) route redirect to the first known list. To achieve this, we need to render a special App_rootRedirector route: FlowRouter.route('/', { name: 'App.home', action() { BlazeLayout.render('App_body', {main: 'App_rootRedirector'}); } });

The App_rootRedirector component is rendered inside the App_body layout, which takes care of subscribing to the set of lists the user knows about before rendering its subcomponent, and we are guaranteed there is at least one such list. This means that if the App_rootRedirector ends up being created, there'll be a list loaded, so we can simply do:

Template.App_rootRedirector.onCreated(function rootRedirectorOnCreated() { // We need to set a timeout here so that we don't redirect from inside a redirection // which is a limitation of the current version of FR. Meteor.setTimeout(() => { FlowRouter.go('Lists.show', Lists.findOne()); }); });

If you need to wait on specific data that you aren't already subscribed to at creation time, you can use an autorun and subscriptionsReady() to wait on that subscription: Template.App_rootRedirector.onCreated(function rootRedirectorOnCreated() { // If we needed to open this subscription here this.subscribe('lists.public'); // Now we need to wait for the above subscription. We'll need the template to // render some kind of loading state while we wait, too. this.autorun(() => { if (this.subscriptionsReady()) { FlowRouter.go('Lists.show', Lists.findOne()); } }); });

Redirecting after a user's action

150

URLs and Routing

Often, you just want to go to a new route programmatically when a user has completed a certain action. Above we saw a case (creating a new list) when we wanted to do it optimistically---i.e. before we hear back from the server that the Method succeeded. We can do this because we reasonably expect that the Method will succeed in almost all cases (see the UI/UX article for further discussion of this). However, if we wanted to wait for the method to return from the server, we can put the redirection in the callback of the method: Template.App_body.events({ 'click .js-new-list'() { lists.insert.call((err, listId) => { if (!err) { FlowRouter.go('Lists.show', { _id: listId }); } }); } });

You will also want to show some kind of indication that the method is working in between their click of the button and the redirect completing. Don't forget to provide feedback if the method is returning an error.

Advanced Routing Missing pages If a user types an incorrect URL, chances are you want to show them some kind of amusing not-found page. There are actually two categories of not-found pages. The first is when the URL typed in doesn't match any of your route definitions. You can use FlowRouter.notFound to handle this: // the App_notFound template is used for unknown routes and missing lists FlowRouter.notFound = { action() { BlazeLayout.render('App_body', {main: 'App_notFound'}); } };

The second is when the URL is valid, but doesn't actually match any data. In this case, the URL matches a route, but once the route has successfully subscribed, it discovers there is no data. It usually makes sense in this case for the page component (which subscribes and fetches the data) to render a not-found template instead of the usual template for the page:

151

URLs and Routing

{{#each listId in listIdArray}} {{> Lists_show (listArgs listId)}} {{else}} {{> App_notFound}} {{/each}}

Analytics It's common to want to know which pages of your app are most commonly visited, and where users are coming from. You can read about how to set up Flow Router based analytics in the Deployment Guide.

Server Side Routing As we've discussed, Meteor is a framework for client rendered applications, but this doesn't always remove the requirement for server rendered routes. There are two main use cases for server-side routing.

Server Routing for API access Although Meteor allows you to write low-level connect handlers to create any kind of API you like on the server-side, if all you want to do is create a RESTful version of your Methods and Publications, you can often use the simple:rest package to do this easily. See the Data Loading and Methods articles for more information. If you need more control, you can use the comprehensive nimble:restivus package to create more or less whatever you need in whatever ontology you require.

Server Rendering The Blaze UI library does not have support for server-side rendering, so it's not possible to render your pages on the server if you use Blaze. However, the React UI library does. This means it is possible to render HTML on the server if you use React as your rendering framework. Although Flow Router can be used to render React components more or less as we've described above for Blaze, at the time of this writing Flow Router's support for SSR is still experimental. However, it's probably the best approach right now if you want to use SSR for Meteor.

152

URLs and Routing

153

User Interfaces

After reading this guide, you'll know: 1. How to build reusable client side components in any user interface framework. 2. How to build a style guide to allow you to visually test such reusable components. 3. Patterns for building front end components in a performant way in Meteor. 4. How to build user interfaces in a maintainable and extensible way. 5. How to build components that can cope with a variety of different data sources. 6. How to use animation to keep users informed of changes.

View layers Meteor officially supports three user interface (UI) rendering libraries, Blaze, React and Angular. Blaze was created as part of Meteor when it launched in 2011, React was created by Facebook in 2013, and Angular was created by Google in 2010. All three have been used successfully by large production apps. Blaze is the easiest to learn and has the most fullstack Meteor packages, but React and Angular are more developed and have larger communities.

Syntax Blaze uses an easy-to-learn Handlebars-like template syntax, with logic like {{#if}} and {{#each}} interspersed in your HTML files. Template functions and CSS-selector events maps are written in JavaScript files. React uses JSX, with which you write your HTML in JavaScript. While it doesn't have the logic-view separation most libraries have, it also has the most flexibility. Template functions and event handlers are defined in the same file as the HTML part of the component, which usually makes it easier to understand how they are tied together. Angular uses HTML with special attribute syntax for logic and events. Template helpers are written in the accompanying JavaScript file along with events, which are called by name from inside HTML attributes. React and Angular enforce a better component structure, which makes developing larger apps easier. (Although you can add component structure to Blaze by following conventions or using the Blaze Components or ViewModel packages.)

Community Blaze has many full-stack Meteor packages on Atmosphere, such as useraccounts:core and aldeed:autoform .

React has 42k stars on Github and 13k npm libraries. Angular has 12k stars on Github and 4k npm libraries.

154

User Interfaces

Performance Render performance varies a lot depending on the situation. All three libraries are very quick at rendering simple apps, but can take a noticeable amount of time with more complex apps. Angular and React have had more performance optimization work put into them than Blaze and in general will perform better. However, there are some cases when Blaze does better (for instance an {{#each}} over a changing cursor). One test benchmarks Angular 2 as the best, followed by React and Angular 1, followed by Blaze.

Mobile Cordova All three libraries work fine in a Cordova web view, and you can use mobile CSS libraries like Ionic's CSS with any view library. The most advanced mobile web framework is Ionic 2, which uses Angular 2. Ionic 1 uses Angular 1, but there are also Blaze and React ports. Another good option is Onsen UI, which includes a React version. Native You can connect any native iOS or Android app to a Meteor server via DDP. For iOS, use the meteor-ios framework. You can write apps with native UI elements in JavaScript using React Native. For the most recent information on how to use React Native with Meteor, see this reference.

UI components Regardless of the view layer that you are using, there are some patterns in how you build your User Interface (UI) that will help make your app's code easier to understand, test, and maintain. These patterns, much like general patterns of modularity, revolve around making the interfaces to your UI elements very clear and avoiding using techniques that bypass these known interfaces. In this article, we'll refer to the elements in your user interface as "components". Although in some systems, you may refer to them as "templates", it can be a good idea to think of them as something more like a component, which has an API and internal logic, rather than a template, which is just a bit of HTML. To begin with, let's consider two categories of UI components that are useful to think about, "reusable" and "smart":

155

User Interfaces

Reusable components A "reusable" component is a component which doesn't rely on anything from the environment it renders in. It renders purely based on its direct inputs (its template arguments in Blaze, or props in React) and internal state. In Meteor specifically, this means a component which does not access data from any global sources---Collections, Stores, routers, user data, or similar. For instance, in the Todos example app, the Lists_show template takes in the list it is rendering and the set of todos for that list, and it never looks directly in the Todos or Lists collections. Reusable components have many advantages: 1. They are easy to reason about---you don't need to understand how the data in the global store changes, simply how the arguments to the component change. 2. They are easy to test---you don't need to be careful about the environment you render them in, all you need to do is provide the right arguments. 3. They are easy to add to component style guides---as we'll see in the section about component style guides, when creating a style guide, a clean environment makes things much easier to work with. 4. You know exactly what dependencies you need to provide for them to work in different environments. There's also an even more restricted type of reusable component, a "pure" component, which does not have any internal state. For instance in the Todos app, the Todos_item template decides what to render solely based on its arguments. Pure components are even easier to reason about and test than reusable ones and so should be preferred wherever possible.

Global data stores So which are the global data stores that you should be avoiding in reusable components? There are a few. Meteor is built to optimize speed of development, which means you can access a lot of things globally. Although this is convenient when building "smart" components (see below), you'll need to avoid these data sources in reusable components: Your collections, as well as the Meteor.users collection, Accounts information, like Meteor.user() and Meteor.loggingIn() Current route information Any other client-side data stores (read more in the Data Loading article)

156

User Interfaces

Smart components While most of the components in your app should be reusable, they need to get their data passed in from somewhere. This is where "smart" components come in. Such components typically do the following things: 1. Subscribe to data 2. Fetch data from those subscriptions 3. Fetch global client-side state from stores such as the Router, Accounts, and your own stores Ideally, once a smart component has assembled such a set of data, it passes it off to a reusable component child to render with. Smart components usually don't render anything apart from one or more reusable children. This makes it easy to separate rendering and data loading in your tests. A typical use case for a smart component is the "page" component that the router points you to when you access a URL. Such a component typically needs to do the three things above and then can pass the resulting arguments into child components. In the Todos example app, the listShowPage does exactly this, resulting in a template with very simple HTML: {{#each listId in listIdArray}} {{> Lists_show (listArgs listId)}} {{else}} {{> App_notFound}} {{/each}}

The JavaScript of this component is responsible for subscribing and fetching the data that's used by the Lists_show template itself:

157

User Interfaces

Template.Lists_show_page.onCreated(function() { this.getListId = () => FlowRouter.getParam('_id'); this.autorun(() => { this.subscribe('todos.inList', this.getListId()); }); }); Template.Lists_show_page.helpers({ // We use #each on an array of one item so that the "list" template is // removed and a new copy is added when changing lists, which is // important for animation purposes. listIdArray() { const instance = Template.instance(); const listId = instance.getListId(); return Lists.findOne(listId) ? [listId] : []; }, listArgs(listId) { const instance = Template.instance(); return { todosReady: instance.subscriptionsReady(), // We pass `list` (which contains the full list, with all fields, as a function // because we want to control reactivity. When you check a todo item, the // `list.incompleteCount` changes. If we didn't do this the entire list would // re-render whenever you checked an item. By isolating the reactiviy on the list // to the area that cares about it, we stop it from happening. list() { return Lists.findOne(listId); }, // By finding the list with only the `_id` field set, we don't create a dependen cy on the // `list.incompleteCount`, and avoid re-rendering the todos when it changes todos: Lists.findOne(listId, {fields: {_id: true}}).todos() }; } });

Visually testing reusable components A useful property of reusable components is that you can render them anywhere because they don't rely on complicated environments. This is very useful when paired with component explorers, debug-only apps that allow you to explore, visualize, and test your UI components.

158

User Interfaces

A component explorer does two things: 1. Indexes your apps components so they are easy to find 2. Renders components using developer-defined states and stubbed data For instance, in Galaxy, we use a component explorer called Chromatic to render each component one specification at a time or with all specifications at once.

Chromatic component explorer walkthrough

Playback isn't supported on this device.

0:00 / 1:54

Using Chromatic enables rapid development of complex components. Typically in a large application, it can be quite difficult to achieve certain states of components purely by "using" the application. For example, a component in Galaxy can enter a complex state if two deploys of the same app happen simultaneously. With Chromatic we're able to define this state at the component level and test it independently of the application logic. You can use Chromatic component explorer in your Meteor + React app with meteor add mdg:chromatic . Similar projects built in React are UI Harness by Phil Cockfield and React

Storybook by Arunoda Susiripala.

User interface patterns

159

User Interfaces

Here are some patterns that are useful to keep in mind when building the user interface of your Meteor application.

Internationalization Internationalization (i18n) is the process of generalizing the UI of your app in such a way that it's easy to render all text in a different language. Meteor's package ecosystem includes internationalization options tailored to your frontend framework of choice.

Places to translate It's useful to consider the various places in the system that user-readable strings exist and make sure that you are properly using the i18n system to generate those strings in each case. We'll go over the implementation for each case in the sections about tap:i18n and universe:i18n below.

1. HTML templates and components. This is the most obvious place---in the content of UI components that the user sees. 2. Client JavaScript messages. Alerts or other messages that are generated on the client side are shown to the user, and should also be translated. 3. Server JavaScript messages and emails. Messages or errors generated by the server can often be user visible. An obvious place is emails and any other server generated messages, such as mobile push notifications, but more subtle places are return values and error messages on method calls. Errors should be sent over the wire in a generic form and translated on the client. 4. Data in the database. A final place where you may want to translate is actual usergenerated data in your database. For example, if you are running a wiki, you might want to have a mechanism for the wiki pages to be translated to different languages. How you go about this will likely be unique to your application.

Using `tap:i18n` in JavaScript In Meteor, the excellent tap:i18n package provides an API for building translations and using them in your components and frontend code. To use tap:i18n , first meteor add tap:i18n to add it to your app. Then we need to add a translation JSON file for our default language ( en for English) -- we can put it at i18n/en.i18n.json . Once we've done that we can import and use the TAPi18n.__()

function to get translations for strings or keys within our JavaScript code.

160

User Interfaces

For instance for errors in the Todos example app, we create an errors module that allows us to easily alert a translated error for all of the errors that we can potentially throw from methods: import { TAPi18n } from 'meteor/tap:i18n'; export const displayError = (error) => { if (error) { // It would be better to not alert the error here but inform the user in some // more subtle way alert(TAPi18n.__(error.error)); } };

The error.error field is the first argument to the Meteor.Error constructor, and we use it to uniquely name and namespace all the errors we use in the application. We then define the English text of those errors in i18n/en.i18n.json : { "lists": { "makePrivate": { "notLoggedIn": "Must be logged in to make private lists.", "lastPublicList": "Cannot make the last public list private." }, "makePublic": { ... } ... }

Using `tap:i18n` in Blaze We can also easily use translations in Blaze templates. To do so, we can use the {% raw %} {{_ }}{% endraw %} helper. In the Todos app we use the actual string that we want to output

in English as the i18n key, which means we don't need to provide an English translation, although perhaps in a real app you might want to provide keys from the beginning. For example in app-not-found.html :

161

User Interfaces

{{_ 'Page not found'}}

Changing language To set and change the language that a user is seeing, you should call TAPi18n.setLanguage(fn) , where fn is a (possibly reactive) function that returns the current

language. For instance you could write // A store to use for the current language export const CurrentLanguage = new ReactiveVar('en');

import CurrentLanguage from '../stores/current-language.js'; TAPi18n.setLanguage(() => { CurrentLanguage.get(); });

Then somewhere in your UI you can CurrentLanguage.set('es') when a user chooses a new language.

Using `universe:i18n` in React For React-based apps, the universe:18n package presents an alternative solution to tap:i18n . universe:i18n adopts similar conventions to tap:i18n , but also includes a

convenient drop-in React component and omits tap:i18n's dependencies on Meteor's templating and jquery packages. universe:i18n was intended for Meteor React

applications using ES2015 modules, but it can be used without React or modules.

Using `universe:i18n` in JS

162

User Interfaces

To get started, run meteor add universe:i18n to add it to your app. Add an English ( en-US ) translation file in JSON format to your app with the name en-us.i18n.json . Translation files can be identified by file name or with the {"_locale": "en-US"} JSON property. The YAML file format is also supported. If your app uses ES2015 modules included from client/main.js and server/main.js entry points, import your JSON file(s) there. The i18n.__() function will now locate keys you pass. Borrowing from the tap:i18n example above, in universe:i18n our displayError function now looks like this: import i18n from 'meteor/universe:i18n'; export const displayError = (error) => { if (error) { alert(i18n.__(error.error)); } };

To change the user's language, use i18n.setLocale('en-US') . universe:i18n allows retrieval of additional translations by method as well as including JSON files with a client bundle.

Using `universe:i18n` in React components To add reactive i18n inline in your React components, simply use the i18n.createComponent() function and pass it keys from your translation file. Here's an

example of a simple component wrapping i18n's translation component: import React from 'react'; import i18n from 'meteor/universe:i18n'; const T = i18n.createComponent(); // displays 'hello world!' where our en-us.i18n.json // has the key/value { "hello": "hello world!" } const Welcome = (props) => hello ; export default Welcome;

See the documentation for universe:i18n for additional options and configuration.

163

User Interfaces

Event handling A large part of your UI involves responding to events initated by the user, and there are some steps that you should take to make sure your application performs well in the face of rapid input. An application lagging in response to user actions is one of the most noticeable performance problems.

Throttling method calls on user action It's typical to make some kind of change to the database when a user takes an action. However it's important to make sure you don't do this too rapidly. For instance, if you wish to save the user's text as they type in a text box, you should take steps to make sure that you don't send method calls to your server more than every few hundred milliseconds. If you do not, you'll see performance problems across the board: you'll be flooding the user's network connection with a lot of small changes, the UI will update on every keystroke, potentially causing poor performance, and your database will suffer with a lot of writes. To throttle writes, a typical approach is to use underscore's .throttle() or .debounce() functions. For instance, in the Todos example app, we throttle writes on user input to 300ms: import { updateText, } from '../../api/todos/methods.js';

Template.Todos_item.events({ // update the text of the item on keypress but throttle the event to ensure // we don't flood the server with updates (handles the event at most once // every 300ms) 'keyup input[type=text]': _.throttle(function(event) { updateText.call({ todoId: this.todo._id, newText: event.target.value }, (err) => { err && alert(err.error); }); }, 300) });

Typically, you use .throttle() if you are OK with the event happening during the user series of actions (i.e. you don't mind the multiple, throttled events happening over time, as in this case), whereas you use .debounce() if you want the events to happen whenever (in this example) the user stops typing for 300ms or longer.

164

User Interfaces

Limiting re-rendering Even if you aren't saving data over the wire to the database on every user input, sometimes you still may wish to update in-memory data stores on every user change. If updating that data store triggers a lot of UI changes, you can see poor performance and missed keystrokes when you update it too often. In such cases you can limit re-rendering by throttling in a similar way how we throttled the method call above. You could also use .debounce() to ensure the changes happen only after the user has stopped typing.

User experience patterns User experience, or UX, describes the experience of a user as they interact with your application. There are several UX patterns that are typical to most Meteor apps which are worth exploring here. Many of these patterns are tied to the way data is loaded as the user interacts with your app, so there are similar sections in the data loading article talking about how to implement these patterns using Meteor's publications and subscriptions.

Subscription readiness When you subscribe to data in Meteor, it does not become instantly available on the client. Typically the user will need to wait for a few hundred milliseconds, or as long as a few seconds (depending on the connection speed), for the data to arrive. This is especially noticeable when the app is first starting up or you move between screens that are displaying completely new data. There are a few UX techniques for dealing with this waiting period. The simplest is simply to switch out the page you are rendering with a generic "loading" page while you wait for all the data (typically a page may open several subscriptions) to load. As an example, in the Todos example app, we wait until all the public lists and the user's private lists have loaded before we try to render the actual page:

165

User Interfaces

{{#if Template.subscriptionsReady}} {{> Template.dynamic template=main}} {{else}} {{> App_loading}} {{/if}}

We do this with Blaze's Template.subscriptionsReady which is perfect for this purpose, as it waits for all the subscriptions that the current component has asked for to become ready.

Per-component loading state Usually it makes for a better UX to show as much of the screen as possible as quickly as possible and to only show loading state for the parts of the screen that are still waiting on data. So a nice pattern to follow is "per-component loading". We do this in the Todos app when you visit the list page---we instantly render the list metadata, such as its title and privacy settings, and render a loading state for the list of todos while we wait for them to appear.

166

User Interfaces

We achieve this by passing the readiness of the todos list down from the smart component which is subscribing (the listShowPage ) into the reusable component which renders the data: {{> Lists_show todosReady=Template.subscriptionsReady list=list}}

And then we use that state to determine what to render in the reusable component ( listShow ): {{#if todosReady}} {{#with list._id}} {{#each todo in (todos this)}} {{> Todos_item (todoArgs todo)}} {{else}} No tasks here Add new tasks using the field above {{/each}} {{/with}} {{else}} Loading tasks... {{/if}}

Showing placeholders You can take the above UI a step further by showing placeholders whilst you wait for the data to load. This is a UX pattern that has been pioneered by Facebook which gives the user a more solid impression of what data is coming down the wire. It also prevents parts of the UI from moving around when data loads, if you can make the placeholder have the same dimensions as the final element. For example, in Galaxy, while you wait for your app's log to load, you see a loading state indicating what you might see:

167

User Interfaces

Using the style guide to prototype loading state Loading states are notoriously difficult to work on visually as they are by definition transient and often are barely noticeable in a development environment where subscriptions load almost instantly. This is one reason why being able to achieve any state at will in the component style guide is so useful. As our reusable component Lists_show simply chooses to render based on its todosReady argument and does not concern itself with a subscription, it is trivial to render its

loading state in a style guide.

Pagination In the Data Loading article we discuss a pattern of paging through an "infinite scroll" type subscription which loads one page of data at a time as a user scrolls down the page. It's interesting to consider UX patterns to consume that data and indicate what's happening to the user.

A list component

168

User Interfaces

Let's consider any generic item-listing component. To focus on a concrete example, we could consider the todo list in the Todos example app. Although it does not in our current example app, in a future version it could paginate through the todos for a given list. There are a variety of states that such a list can be in: 1. Initially loading, no data available yet. 2. Showing a subset of the items with more available. 3. Showing a subset of the items with more loading. 4. Showing all the items - no more available. 5. Showing no items because none exist. It's instructive to think about what arguments such a component would need to differentiate between those five states. Let's consider a generic pattern that would work in all cases where we provide the following information: A count of the total number of items. A countReady boolean that indicates if we know that count yet (remember we need to load even that information). A number of items that we have requested . A list of items that we currently know about. We can now distinguish between the 5 states above based on these conditions: 1.

countReady is false, or count > 0 and items is still empty. (These are actually two

different states, but it doesn't seem important to visually separate them). 2.

items.length === requested && requested < count

3.

0 < items.length < requested

4.

items.length === requested && count > 0

5.

count === 0

You can see that although the situation is a little complex, it's also completely determined by the arguments and thus very much testable. A component style guide helps immeasurably in seeing all these states easily! In Galaxy we have each state in our style guide for each of the lists of our app and we can ensure all work as expected and appear correctly:

169

User Interfaces

A pagination "controller" pattern A list is also a good opportunity to understand the benefits of the smart vs reusable component split. We've seen above that correctly rendering and visualizing all the possible states of a list is non-trivial and is made much easier by having a reusable list component that takes all the required information in as arguments. However, we still need to subscribe to the list of items and the count, and collect that data somewhere. To do this, it's sensible to use a smart wrapper component (analogous to an MVC "controller") whose job it is to subscribe and fetch the relevant data. In the Todos example app, we already have a wrapping component for the list that talks to the router and sets up subscriptions. This component could easily be extended to understand pagination:

170

User Interfaces

const PAGE_SIZE = 10; Template.Lists_show_page.onCreated(function() { // We use internal state to store the number of items we've requested this.state = new ReactiveDict(); this.getListId = () => FlowRouter.getParam('_id'); this.autorun(() => { // As the `requested` state increases, we re-subscribe to a greater number of todos this.subscribe('List.todos', this.getListId(), this.state.get('requested')); this.countSub = this.subscribe('Lists.todoCount', this.getListId()); }); // The `onNextPage` function is used to increment the `requested` state variable. It 's passed // into the listShow subcomponent to be triggered when the user reaches the end of t he visible todos this.onNextPage = () => { this.state.set('requested', this.state.get('requested') + PAGE_SIZE); }; }); Template.Lists_show_page.helpers({ listArgs(listId) { const instance = Template.instance(); const list = Lists.findOne(listId); const requested = instance.state.get('requested'); return { list, todos: list.todos({}, {limit: requested}), requested, countReady: instance.countSub.ready(), count: Counts.get(`list/todoCount${listId}`), onNextPage: instance.onNextPage }; } });

UX patterns for displaying new data An interesting UX challenge in a realtime system like Meteor involves how to bring new information (like changing data in a list) to the user's attention. As Dominic points out, it's not always a good idea to simply update the contents of a list as quickly as possible, as it's easy to miss changes or get confused about what's happened.

171

User Interfaces

One solution to this problem is to animate list changes (which we'll look at in the animation section), but this isn't always the best approach. For instance, if a user is reading a list of comments, they may not want to see any changes until they are done with the current comment thread. An option in this case is to call out that there are changes to the data the user is looking at without actually making UI updates. In a system like Meteor which is reactive by default, it isn't necessarily easy to stop such changes from happening! However, it is possible to do this thanks to our split between smart and reusable components. The reusable component simply renders what it's given, so we use our smart component to control that information. We can use a local collection to store the rendered data, and then push data into it when the user requests an update: Template.Lists_show_page.onCreated(function() { // ... // The visible todos are the todos that the user can // actually see on the screen (whereas Todos are the // todos that actually exist) this.visibleTodos = new Mongo.Collection(null); this.getTodos = () => { const list = Lists.findOne(this.getListId()); return list.todos({}, {limit: instance.state.get('requested')}); }; // When the user requests it, we should sync the visible todos to // reflect the true state of the world this.syncTodos = (todos) => { todos.forEach(todo => this.visibleTodos.insert(todo)); this.state.set('hasChanges', false); }; this.onShowChanges = () => { this.syncTodos(this.getTodos()); }; this.autorun((computation) => { const todos = this.getTodos(); // If this autorun re-runs, the list id or set of todos must have // changed, so we should flag it to the user so they know there // are changes to be seen. if (!computation.firstRun) { this.state.set('hasChanges', true); } else { this.syncTodos(todos); } }); });

172

User Interfaces

Template.Lists_show_page.helpers({ listArgs(listId) { const instance = Template.instance(); const list = Lists.findOne(listId); const requested = instance.state.get('requested'); return { list, // we pass the *visible* todos through here todos: instance.visibleTodos.find({}, {limit: requested}), requested, countReady: instance.countSub.ready(), count: Counts.get(`list/todoCount${listId}`), onNextPage: instance.onNextPage, // These two properties allow the user to know that there // are changes to be viewed and allow them to view them hasChanges: instance.state.get('hasChanges'), onShowChanges:instance.onShowChanges }; } });

The reusable sub-component can then use the hasChanges argument to determine if it should show some kind of callout to the user to indicate changes are available, and then use the onShowChanges callback to trigger them to be shown.

Optimistic UI One nice UX pattern which Meteor makes much easier than other frameworks is Optimistic UI. Optimistic UI is the process of showing user-generated changes in the UI without waiting for the server to acknowledge that the change has succeeded, resulting in a user experience that seems faster than is physically possible, since you don't need to wait for any server roundtrips. Since most user actions in a well-designed app will be successful, it makes sense for almost all parts of an app to be optimistic in this way. However, it's not always necessarily a good idea to be optimistic. Sometimes we may actually want to wait for the server's response. For instance, when a user is logging in, you have to wait for the server to check the password is correct before you can start allowing them into the site. So when should you wait for the server and when not? It basically comes down to how optimistic you are; how likely it is that something will go wrong. In the case of a password, you really can't tell on the client, so you need to be conservative. In other cases, you can be pretty confident that the Method call will succeed, and so you can move on. For instance, in the Todos example app, when creating a new list, the list creation will basically always succeed, so we write:

173

User Interfaces

import { insert } from '../../api/lists/methods.js'; Template.App_body.events({ 'click .js-new-list'() { const listId = insert.call((err) => { if (err) { // At this point, we have already redirected to the new list page, but // for some reason the list didn't get created. This should almost never // happen, but it's good to handle it anyway. FlowRouter.go('App.home'); alert('Could not create list.'); } }); FlowRouter.go('Lists.show', { _id: listId }); } });

We place the FlowRouter.go('Lists.show') outside of the callback of the Method call, so that it runs right away. First we simulate the method (which creates a list locally in Minimongo), then route to it. Eventually the server returns, usually creating the exact same list (which the user will not even notice). In the unlikely event that the server call fails, we show an error and redirect back to the homepage. Note that the listId returned by the list method (which is the one generated by the client stub) is guaranteed to be the same as the one generated on the server, due to the way that Meteor generates IDs and ensures they are the same between client and server.

Indicating when a write is in progress Sometimes the user may be interested in knowing when the update has hit the server. For instance, in a chat application, it's a typical pattern to optimistically display the message in the chat log, but indicate that it is "pending" until the server has acknowledged the write. We can do this easily in Meteor by simply modifying the Method to act differently on the client:

174

User Interfaces

Messages.methods.insert = new ValidatedMethod({ name: 'Messages.methods.insert', validate: new SimpleSchema({ text: {type: String} }).validator(), run(message) { // In the simulation (on the client), we add an extra pending field. // It will be removed when the server comes back with the "true" data. if (this.isSimulation) { message.pending = true; } Messages.insert(message); } })

Of course in this scenario, you also need to be prepared for the server to fail, and again, indicate it to the user somehow.

Unexpected failures We've seen examples above of failures which you don't really anticipate will happen. It's difficult and inefficient to defend against every possible error, however unlikely. However, there are some catch-all patterns that you can use for unexpected failures. Thanks to Meteor's automatic handling of optimistic UI, if a method unexpectedly fails the optimistic changes will roll back and the Minimongo database will end up in a consistent state. If you are rendering directly from Minimongo, the user will see something that is consistent, even if it's not what they anticipated of course. In some cases when you have state you are keeping outside of Minimongo, you may need to make changes to it manually to reflect this. You can see this in the example above where we had to update the router manually after an operation failed. However, it's terrible UX to simply jump the user to an unexpected state without explaining what's happened. We used a alert() above, which is a pretty poor option, but gets the job done. One better approach is to indicate changes via a "flash notification", which is a UI element that's displayed "out-of-band", typically in the top right of the screen, given the user some indication of what's happened. Here's an example of a flash notification in Galaxy, at the top right of the page:

175

User Interfaces

Animation Animation is the process of indicating changes in the UI smoothly over time rather than instantly. Although animation is often seen as "window dressing" or purely aesthetic, in fact it serves a very important purpose, highlighted by the example of the changing list above. In a connected-client world where changes in the UI aren't always initiated by user action (i.e. sometimes they happen as a result of the server pushing changes made by other users), instant changes can result in a user experience where it's difficult to understand what is happening.

Animating changes in visiblity Probably the most fundamental type of UI change that requires animation is when items appear or disappear. In Blaze, we can use the percolate:momentum package to plug a standard set of animations from the velocity animation library into such state changes. A good example of this is the editing state of the list from the Todos example app:

176

User Interfaces

{{#momentum plugin="fade"}} {{#if instance.state.get 'editing'}} ... {{else}} ... {{/if}} {{/momentum}}

Momentum works by overriding the way that child HTML elements appear and disappear. In this case, when the list component goes into the editing state, the .nav-group disappears, and the form appears. Momentum takes care of the job of making sure that both items fade, making the change a lot clearer.

Animating changes to attributes Another common type of animation is when an attribute of an element changes. For instance, a button may change color when you click on it. These type of animations are most easily achieved with CSS transitions. For example, we use a CSS transition for the hover state of links in the Todos example app: a { transition: all 200ms ease-in; color: @color-secondary; cursor: pointer; text-decoration: none; &:hover { color: darken(@color-primary, 10%); } &:active { color: @color-well; } &:focus { outline:none; } //removes FF dotted outline }

Animating page changes Finally, it's common to animate when the user switches between routes of the application. Especially on mobile, this adds a sense of navigation to the app via positioning pages relative to each other. This can be done in a similar way to animating things appearing and disappearing (after all one page is appearing and other is disappearing), but there are some tricks that are worth being aware of. Let's consider the case of the Todos example app. Here we do a similar thing to achieve animation between pages, by using Momentum in the main layout template:

177

User Interfaces

{{#momentum plugin="fade"}} {{#if Template.subscriptionsReady}} {{> Template.dynamic template=main}} {{else}} {{> App_loading}} {{/if}} {{/momentum}}

This looks like it should just work, but there's one problem: Sometimes the rendering system will prefer to simply change an existing component rather than switching it out and triggering the animation system. For example in the Todos example app, when you navigate between lists, by default Blaze will try to simply re-render the Lists_show component with a new listId (a changed argument) rather than pull the old list out and put in a new one. This is

an optimization that is nice in principle, but that we want to avoid here for animation purposes. More specifically, we want to make sure the animation only happens when the listId changes and not on other reactive changes.

To do so in this case, we can use a little trick (that is specific to Blaze, although similar techniques apply to other view layers) of using the fact that the {% raw %}{{#each}}{% endraw %} helper diffs arrays of strings, and completely re-renders elements when they change.

{{#each listId in listIdArray}} {{> Lists_show (listArgs listId)}} {{else}} {{> App_notFound}} {{/each}}

Template.Lists_show_page.helpers({ // We use #each on an array of one item so that the "list" template is // removed and a new copy is added when changing lists, which is // important for animation purposes. listIdArray() { const instance = Template.instance(); const listId = instance.getListId(); return Lists.findOne(listId) ? [listId] : []; } });

178

Blaze

This content has moved to the Blaze Community Site.

179

React

After reading this guide, you'll know: 1. What React is, and why you would consider using it with Meteor. 2. How to install React in your Meteor application, and how to use it correctly. 3. How to integrate React with Meteor's realtime data layer. 4. How to route in a React/Meteor application.

Introduction React is a JavaScript library for building reactive user interfaces developed and distributed by the Facebook team. React is one of the three rendering libraries supported by Meteor; the alternatives are Blaze and Angular. Here's a comparison of all three. React has a vibrant and growing ecosystem and is used widely in production in a variety of combinations with different frameworks. To learn more about using React in general and coming up to speed with the library, you should check out the React documentation, especially the thinking in React post, which explains the React philosophy well. To get started with React in Meteor, you can follow along the React tutorial. To see an example of a more complete Meteor application built with React, check out the react branch of the Todos example application. Where applicable, code examples in this article will reference that app.

Installing and using React To install React in Meteor 1.3 you should simply add it as an npm dependency: meteor npm install --save react react-dom

This will install react into your project and allow you to access it within your files with import React from 'react' . Most React code is written in JSX, which you can use by

default in Meteor if you include the ecmascript package (which is installed in all Meteor apps by default).

180

React

import React from 'react'; export default class HelloWorld extends React.Component { render() { return ( Hello World ); } }

You can render a component heirarchy to the DOM using the react-dom package: import { Meteor } from 'meteor/meteor'; import React from 'react'; import { render } from 'react-dom'; import HelloWorld from './HelloWorld.js'; Meteor.startup(() => { render(, document.getElementById('app')); });

You need to include a in your body's HTML somewhere of course. Every new Meteor app includes Blaze, Meteor's default templating system, by default. If you are not planning on using React and Blaze together, you can remove Blaze from your project by running: meteor remove blaze-html-templates meteor add static-html

Using 3rd party packages If you'd like to use a third party React component that has been published on npm, you can meteor npm install --save them and import from within your app.

For example, to use the excellent Griddle React package for making tables, you could run meteor npm install --save griddle-react

Then, like with any other npm package, you can import the component in your application:

181

React

import React from 'react'; import Griddle from 'griddle-react'; export default class MyGriddler extends React.Component { render() { return (); } }

If you are looking to write an Atmosphere package that wraps such a component, you need to take some further steps.

React Components in Blaze If you'd like to use React within a larger app built with Blaze (which is a good strategy if you'd like to incrementally migrate an app from Blaze to React), you can use the reacttemplate-helper component which renders a react component inside a Blaze template. First

run meteor add react-template-helper , then use the React helper in your template: Hello, {{username}} {{> React component=UserAvatar userId=_id}}

You will need to pass in the component class with a helper: import { Template } from 'meteor/templating'; import './userDisplay.html'; import UserAvatar from './UserAvatar.js'; Template.userDisplay.helpers({ UserAvatar() { return UserAvatar; } })

The component argument is the React component to include, which should be passed in with a helper. Every other argument is passed as a prop to the component when it is rendered. Note that there a few caveats:

182

React

React components must be the only thing in the wrapper element. Due to a limitation of React (see facebook/react #1970, #2484), a React component must be rendered as the only child of its parent node, meaning it cannot have any siblings. This means a React component also can't be the only thing in a Blaze template, because it's impossible to tell where the template will be used.

Passing callbacks to a React component To pass a callback to a React component that you are including with this helper, simply make a template helper that returns a function, and pass it in as a prop, like so: Template.userDisplay.helpers({ onClick() { const instance = Template.instance(); // Return a function from this helper, where the template instance is in // a closure return () => { instance.hasBeenClicked.set(true) } } });

To use it in Blaze: {{> React component=UserAvatar userId=_id onClick=onClick}}

Blaze Templates in React Just like we can use React components in Blaze templates, we can also use Blaze templates in React components. This is similarly useful for a gradual transition strategy; but more importantly, it allows us to continue to use the multitude of Atmosphere packages built for Blaze in our React projects, as well as core packages like accounts-ui . One easy way to do this is with the gadicc:blaze-react-component package. First run meteor add gadicc:blaze-react-component , then import and use it in your components as follows:

183

React

import React from 'react'; import Blaze from 'meteor/gadicc:blaze-react-component'; const App = () => ( );

The line is the same as if you had written {% raw %}{{> itemsList items=items}}{% endraw %} inside of a Blaze template. For other options

and further information, see the package's project page.

Using Meteor's data system React is a front-end rendering library and as such doesn't concern itself with how data gets into and out of components. On the other hand, Meteor has strong opinions about data! Meteor operates in terms of publications and methods, used to subscribe to and modify the data in your application. To integrate the two systems, we've developed a react-meteor-data package which allows React components to respond to data changes via Meteor's Tracker reactivity system.

Using `createContainer` Once you've run meteor add react-meteor-data , you'll be able to import the createContainer function, which allows you to create a container component which

provides data to your presentational components. Note that "container components" are analogous to the "smart components" and "presentational components" to the "reusable components" in the pattern we document in the UI/UX article, if you'd like to read more about how this philosophy relates to Meteor. For example, in the Todos example app, we have a ListPage component, which renders list metadata and the tasks in the list. In order to do so, it needs to subscribe to the todos.inList publication, check that subscription's readiness, then fetch the list of todos

from the Todos collection. It also needs to be responsive to reactive changes in the state of those actions (for instance if a todo changes due to the action of another user). All this data loading complexity is a typical use-case for a container-presentational component split, and the createContainer() function makes it simple to do this. 184

React

We simply define the ListPage component as a presentational component that expects its data to be passed in using React props : import React from 'react'; export default class ListPage extends React.Component { ... } ListPage.propTypes = { list: React.PropTypes.object, todos: React.PropTypes.array, loading: React.PropTypes.bool, listExists: React.PropTypes.bool, };

Then we create a ListPageContainer container component which wraps it and provides a data source: import { Meteor } from 'meteor/meteor'; import { Lists } from '../../api/lists/lists.js'; import { createContainer } from 'meteor/react-meteor-data'; import ListPage from '../pages/ListPage.js'; export default ListPageContainer = createContainer(({ params }) => { const { id } = params; const todosHandle = Meteor.subscribe('todos.inList', id); const loading = !todosHandle.ready(); const list = Lists.findOne(id); const listExists = !loading && !!list; return { loading, list, listExists, todos: listExists ? list.todos().fetch() : [], }; }, ListPage);

It's a good habit to name your container exactly like the component that it wraps, with the word “Container” tacked onto the end. This way, when you're attempting to track down issues in your code, it makes it much easier to locate the appropriate files/classes. The container component created by createContainer() will reactively rerender the wrapped component in response to any changes to reactive data sources accessed from inside the function provided to it.

185

React

Although this ListPageContainer container is intended to be instantiated by the React Router (which passes in the props automatically), if we did ever want to create one manually, we would need to pass in the props to the container component (which then get passed into our data function above):

Preventing re-renders Sometimes changes in your data can trigger re-computations which you know won't affect your UI. Although React is in general quite efficient in the face of unnecessary re-renders, if you need to control re-rendering, the above pattern allows you to easily use React's shouldComponentUpdate on the presentational component to avoid re-renders.

Routing There are two main options for routing with Meteor and React. Either way, we recommend consulting our Routing article for some general principles of routing in Meteor before writing your app. kadira:flow-router is a Meteor specific router that can be used both with React and

Blaze. It is documented in detail in the Routing article. react-router is a React-specific router very popular in the React community. It can

also be used easily with Meteor.

Flow Router Using Flow Router with React is very similar to using it with Blaze. The only difference is that in your route actions, you should use the react-mounter package to mount components with a layout. Once you meteor npm install --save react-mounter , you can do the following:

186

React

import React from 'react'; import { FlowRouter } from 'meteor/kadira:flow-router'; import { mount } from 'react-mounter'; import AppContainer from '../../ui/containers/AppContainer.js'; import ListPageContainer from '../../ui/containers/ListPageContainer.js';

FlowRouter.route('/lists/:_id', { name: 'Lists.show', action() { mount(AppContainer, { main: , }); }, });

Note that react-mounter automatically mounts the layout component on a #react-root node, which you can change by using the withOptions() function. In the below example, your App component would receive a main prop with a instantiated React Element to render: const App = (props) => ( {props.main} ); export default AppContainer = createContainer(props => { // props here will have `main`, passed from the router // anything we return from this function will be *added* to it return { user: Meteor.user(), }; }, App);

React Router Using React Router is also straightforward. Once you meteor npm install --save reactrouter , you can simply export a list of nested routes as you would in any other React Router

driven React application:

187

React

import React from 'react'; import { Router, Route, browserHistory } from 'react-router'; // route components import AppContainer from '../../ui/containers/AppContainer.js'; import ListPageContainer from '../../ui/containers/ListPageContainer.js'; import AuthPageSignIn from '../../ui/pages/AuthPageSignIn.js'; import AuthPageJoin from '../../ui/pages/AuthPageJoin.js'; import NotFoundPage from '../../ui/pages/NotFoundPage.js'; export const renderRoutes = () => ( );

With React Router, you'll also need to explicity render the exported routes in a startup function: import { Meteor } from 'meteor/meteor'; import { render } from 'react-dom'; import { renderRoutes } from '../imports/startup/client/routes.js'; Meteor.startup(() => { render(renderRoutes(), document.getElementById('app')); });

When using React Router in Meteor, you can follow roughly the same principles as when using Flow Router, but you should also consider the idioms outlined in React Router's own documentation. These include some notable differences like: React Router encourages you to couple your URL design and layout hierarchy in the route definition. Flow Router is more flexible, although it can involve much more boilerplate as a result. React Router embraces React-specific functionality like the use of context, although you can also explicitly pass your FlowRouter instance around in context if you'd like (in fact this is probably the best thing to do).

Meteor and React 188

React

Using React in Atmosphere Packages If you are writing an Atmosphere package and want to depend on React or an npm package that itself depends on React, you can't use Npm.depends() and Npm.require() , as this will result in 2 copies of React being installed into the application (and besides Npm.require() only works on the server). Instead, you need to ask your users to install the correct npm packages in the application itself. This will ensure that only one copy of React is shipped to the client and there are no version conflicts. In order to check that a user has installed the correct versions of npm packages, you can use the tmeasday:check-npm-versions package to check dependency versions at runtime.

189

Angular

Angular is a frontend rendering library that is officially supported by Meteor. The best place to read about how to use both Angular 1 and Angular 2 in Meteor is the Angular-Meteor site. The two alteratives to Angular are Blaze and React. Here's a comparison of all three.

190

Atmosphere vs. npm

Building an application completely from scratch is a tall order. This is one of the main reasons you might consider using Meteor in the first place - you can focus on writing the code that is specific to your app, instead of reinventing wheels like user login and data synchronization. To streamline your workflow even further, it makes sense to use community packages from npm and Atmosphere. Many of these packages are recommended in the guide, and you can find more in the online directories. With the release of version 1.3, Meteor has full support for npm. In the future, there will be a time when all packages will be migrated to npm, but currently there are benefits to both systems.

When to use Atmosphere packages Atmosphere packages are packages written specifically for Meteor and have several advantages over npm when used with Meteor. In particular, Atmosphere packages can: Depend on core Meteor packages, such as ddp and blaze Explicitly include non-javascript files including CSS, Less, Sass, Stylus and static assets Take advantage of Meteor's build system to be automatically transpiled from languages like CoffeeScript Have a well defined way to ship different code for client and server, enabling different behavior in each context Get direct access to Meteor's package namespacing and package global exports without having to explicitly use ES2015 import Enforce exact version dependencies between packages using Meteor's constraint resolver Include build plugins for Meteor's build system Include pre-built binary code for different server architectures, such as Linux or Windows If your package depends on an Atmosphere package (which, in Meteor 1.3, includes the Meteor core packages), or needs to take advantage of Meteor's build system, writing an Atmosphere package might be the best option for now.

When to use npm packages npm is a repository of general JavaScript packages. These packages were originally intended solely for the Node.js server-side environment, but as the JavaScript ecosystem matured, solutions arose to enable the use of npm packages in other environments such as the browser. Today, npm is used for all types of JavaScript packages.

191

Atmosphere vs. npm

If you want to distribute and reuse code that you've written for a Meteor application, then you should consider publishing that code on npm if it's general enough to be consumed by a wider JavaScript audience. It's simple to use npm packages in Meteor applications, and possible to use npm packages within Atmosphere packages, so even if your main audience is Meteor developers, npm might be the best choice. Meteor comes with npm bundled so that you can type meteor npm without worrying about installing it yourself. If you like, you can also use a globally installed npm to manage your packages.

192

Using Atmosphere Packages

Searching for packages There are a few ways to search for Meteor packages published to Atmosphere: 1. Search on the Atmosphere website. 2. Use meteor search from the command line. 3. Use a community package search website like Fastosphere. The main Atmosphere website provides additional curation features like trending packages, package stars, and flags, but some of the other options can be faster if you're trying to find a specific package. For example, you can use meteor show kadira:flow-router from the command line to see the description of that package and different available versions.

Package naming You may notice that, with the exception of Meteor platform packages, all packages on Atmosphere have a name of the form prefix:package-name . The prefix is the Meteor Developer username of the organization or user that published the package. Meteor uses such a convention for package naming to make sure that it's clear who has published a certain package, and to avoid an ad-hoc namespacing convention. Meteor platform packages do not have any prefix: .

Installing Atmosphere Packages To install an Atmosphere package, you simply run meteor add : meteor add kadira:flow-router

This will add the newest version of the desired package that is compatible with the other packages in your app. If you want to specify a particular version, you can specify it by adding a suffix to the package name like: meteor add kadira:[email protected] . Regardless of how you add the package to your app, its actual version will be tracked in the file at .meteor/versions . This means that anybody collaborating with you on the same app is guaranteed to have the same package versions as you. If you want to update to a newer version of a package after installing it, use meteor update . You can run meteor update without any arguments to update all packages and Meteor itself to their latest versions, or pass a specific package to update just that one, for example meteor update kadira:flowrouter .

193

Using Atmosphere Packages

If your app is running when you add a new package, Meteor will automatically download it and restart your app for you. The actual files for a given version of an Atmosphere package are stored in your local ~/.meteor/packages directory.

To see all the Atmosphere packages installed run: meteor list

To remove an unwanted Atmosphere package run: meteor remove kadira:flow-router

You can get more details on all the package commands in the Meteor Command line documentation.

Using Atmosphere Packages To use an Atmosphere Package in your app you can import it with the meteor/ prefix: import { SimpleSchema } from 'meteor/aldeed:simple-schema';

Typically a package will export one or more symbols, which you'll need to reference with the destructuring syntax. You can find these exported symbols by either looking in that package's package.js file for api.export calls or by looking in that package's main JavaScript file for ES2015 export calls like export const packageName = 'package-name'; . Sometimes a package will have no exports and simply have side effects when included in your app. In such cases you don't need to import the package at all after installing. For backwards compatibility with Meteor 1.2 and early releases, Meteor by default makes available directly to your app all symbols referenced in api.export in any packages you have installed. However, it is recommended that you import these symbols first before using them.

Importing styles from Atmosphere packages Using any of Meteor's supported CSS pre-processors you can import other style files using the {package-name} syntax as long as those files are designated to be lazily evaluated as "import" files. To get more details on how to determine this see CSS source versus import

194

Using Atmosphere Packages

files. @import '{prefix:package-name}/buttons/styles.import.less';

CSS files in an Atmosphere package are declared with api.addFiles , and therefore will be eagerly evaluated by default, and then bundled with all the other CSS in your app.

Peer npm dependencies Atmosphere packages can ship with contained npm dependencies, in which case you don't need to do anything to make them work. However, some Atmosphere packages will expect that you have installed certain "peer" npm dependencies in your application. Typically the package will warn you if you have not done so. For example, if you install the react-meteor-data package into your app, you'll also need to install the react and the react-addons-pure-render-mixin packages:

meteor npm install --save react react-addons-pure-render-mixin meteor add react-meteor-data

Atmosphere package namespacing Each Atmosphere package that you use in your app exists in its own separate namespace, meaning that it sees only its own global variables and any variables provided by the packages that it specifically uses. When a top-level variable is defined in a package, it is either declared with local scope or package scope. /** * local scope - this variable is not visible outside of the block it is * declared in and other packages and your app won't see it */ const alicePerson = {name: "alice"}; /** * package scope - this variable is visible to every file inside of the * package where it is declared and to your app */ bobPerson = {name: "bob"};

195

Using Atmosphere Packages

Notice that this is just the normal JavaScript syntax for declaring a variable that is local or global. Meteor scans your source code for global variable assignments and generates a wrapper that makes sure that your globals don't escape their appropriate namespace. In addition to local scope and package scope, there are also package exports. A package export is a "pseudo global" variable that a package makes available for you to use when you install that package. For example, the email package exports the Email variable. If your app uses the email package (and only if it uses the email package!) then your app can access the Email symbol and you can call Email.send . Most packages have only one export, but some packages might have two or three (for example, a package that provides several classes that work together). It is recommended that you use the ecmascript package and first call import { Email } from 'meteor/email'; before calling Email.send in your app. It is also recommended

that package developers now use ES2015 export from their main JavaScript file instead of api.export . Your app sees only the exports of the packages that you use directly. If you use package A, and package A uses package B, then you only see package A's exports. Package B's exports don't "leak" into your namespace just because you used package A. Each app or package only sees their own globals plus the APIs of the packages that they specifically use and depend upon.

196

Using npm Packages

Searching for packages The best way to find npm packages is by searching on npmjs.com. There are also some websites that have special search features specifically for certain kinds of packages, like the aptly named react-components.com.

npm on the client Tools like browserify and webpack are designed to provide a Node-like environment on the client so that many npm packages, even ones originally intended for the server, can run unmodified. Meteor's ES2015 module system does this for you out of the box with no additional configuration necessary. In most cases, you can simply import npm dependencies from a client file, just as you would on the server. When creating a new application Meteor installs the meteor-node-stubs npm package to help provide this client browser compatibility. If you are upgrading an application to Meteor 1.3 you may have to run meteor npm install --save meteor-node-stubs manually.

Installing npm Packages npm packages are configured in a package.json file at the root of your project. If you create a new Meteor project, you will have such a file created for you. If not you can run meteor npm init to create one.

To install a package into your app you run the npm install command with the --save flag: meteor npm install --save moment

This will both update your package.json with information about the dependency and download the package into your app's local node_modules/ directory. Typically, you don't check the node_modules/ directory into source control and your teammates run meteor npm install to get up to date when dependencies change:

meteor npm install

197

Using npm Packages

If the package is just a development dependency (i.e. it's used for testing, linting or the like) then you should use --save-dev . That way if you have some kind of build script, it can do npm install --production and avoid installing packages it doesn't need.

For more information about npm install , check out the official documentation. Meteor comes with npm bundled so that you can type meteor npm without worrying about installing it yourself. If you like, you can also use a globally installed npm to manage your packages.

Using npm Packages To use an npm package from a file in your application you simply import the name of the package: import moment from 'moment'; // this is equivalent to the standard node require: const moment = require('moment');

This imports the default export from the package into the symbol moment . You can also import specific functions from a package using the destructuring syntax: import { isArray } from 'lodash';

You can also import other files or JS entry points from a package: import { parse } from 'graphql/language';

Importing styles from npm Using any of Meteor's supported CSS pre-processors you can import other style files provided by an NPM into your application using both relative and absolute paths. However, this will only work for the top-level app and will not work inside an Atmosphere package. Importing styles from an npm package with an absolute path using the {} syntax, for instance with Less: @import '{}/node_modules/npm-package-name/button.less';

198

Using npm Packages

Importing styles from an npm package with a relative path: @import '../../node_modules/npm-package-name/colors.less';

You can also import CSS directly from a JavaScript file to control load order if you have the ecmascript package installed:

import 'npm-package-name/stylesheets/styles.css';

When importing CSS from a JavaScript file, that CSS is not bundled with the rest of the CSS processed with the Meteor Build tool, but instead is put in your app's tag inside ... after the main concatenated CSS file.

npm Shrinkwrap package.json typically encodes a version range, and so each npm install command can

sometimes lead to a different result if new versions have been published in the meantime. In order to ensure that you and the rest of your team are using the same exact same version of each package, it's a good idea to use npm shrinkwrap after making any dependency changes to package.json : # after installing meteor npm install --save moment meteor npm shrinkwrap

This will create an npm-shrinkwrap.json file containing the exact versions of each dependency, and you should check this file into source control. For even more precision (the contents of a given version of a package can change), and to avoid a reliance on the npm server during deployment, you should consider using npm shrinkpack .

Asyncronous Callbacks Many npm packages rely on an asynchronous, callback or promise-based coding style. For several reasons, Meteor is currently built around a synchronous-looking but still non-blocking style using Fibers. The global Meteor server context and every method and publication initialize a new fiber so that they can run concurrently. Many Meteor APIs, for example collections, rely on running inside a fiber. They also rely on an internal Meteor mechanism that tracks server

199

Using npm Packages

"environment" state, like the currently executing method. This means you need to initialize your own fiber and environment to use asynchronous Node code inside a Meteor app. Let's look at an example of some code that won't work, using the code example from the nodegithub repository: // Inside a Meteor method definition updateGitHubFollowers() { github.user.getFollowingFromUser({ user: 'stubailo' }, (err, res) => { // Using a collection here will throw an error // because the asynchronous code is not in a fiber Followers.insert(res); }); }

Let's look at a few ways to resolve this issue.

`Meteor.bindEnvironment` In most cases, simply wrapping the callback in Meteor.bindEnvironment will do the trick. This function both wraps the callback in a fiber, and does some work to maintain Meteor's serverside environment tracking. Here's the same code with Meteor.bindEnvironment : // Inside a Meteor method definition updateGitHubFollowers() { github.user.getFollowingFromUser({ user: 'stubailo' }, Meteor.bindEnvironment((err, res) => { // Everything is good now Followers.insert(res); })); }

However, this won't work in all cases - since the code runs asynchronously, we can't use anything we got from an API in the method return value. We need a different approach that will convert the async API to a synchronous-looking one that will allow us to return a value.

`Meteor.wrapAsync` Many npm packages adopt the convention of taking a callback that accepts (err, res) arguments. If your asynchronous function fits this description, like the one above, you can use Meteor.wrapAsync to convert to a fiberized API that uses return values and exceptions instead of callbacks, like so:

200

Using npm Packages

// Setup sync API const getFollowingFromUserFiber = Meteor.wrapAsync(github.user.getFollowingFromUser, github.user); // Inside a Meteor method definition updateGitHubFollowers() { const res = getFollowingFromUserFiber({ user: 'stubailo' }); Followers.insert(res); // Return how many followers we have return res.length; }

If you wanted to refactor this and create a completely fiber-wrapper GitHub client, you could write some logic to loop over all of the methods available and call Meteor.wrapAsync on them, creating a new object with the same shape but with a more Meteor-compatible API.

Promises Recently, a lot of npm packages have been moving to Promises instead of callbacks for their API. This means you actually get a return value from the asynchronous function, but it's just an empty shell where the real value is filled in later. The good news is that Promises can be used with the new ES2015 async/await syntax (available in the ecmascript package since Meteor 1.3) in a natural and synchronouslooking style on both the client and the server. If you declare your function async (which ends up meaning it returns a Promise itself), then you can use the await keyword to wait on other promise inside. This makes it very easy to serially call Promise-based libraries: async function sendTextMessage(user) { const toNumber = await phoneLookup.findFromEmail(user.emails[0].address); return await client.sendMessage({ to: toNumber, from: '+14506667788', body: 'Hello world!' }); }

Shrinkpack 201

Using npm Packages

Shrinkpack is a tool that gives you more bulletproof and repeatable builds than you get by using npm shrinkwrap alone. Essentially it copies a tarball of the contents of each of your npm dependencies into your application source repository. This is essentially a more robust version of the npmshrinkwrap.json file that shrinkwrap creates, because it means your application's npm

dependencies can be assembled without the need or reliance on the npm servers being available or reliable. This is good for repeatable builds especially when deploying. To use shrinkpack, first globally install it: npm install -g shrinkpack

Then use it directly after you shrinkwrap meteor npm install moment meteor npm shrinkwrap shrinkpack

You should then check the generated node_shrinkwrap/ directory into source control, but ensure it is ignored by your text editor. NOTE: Although this is a good idea for projects with a lot of npm dependencies, it will not affect Atmosphere dependencies, even if they themselves have direct npm dependencies.

202

Writing npm Packages

To create a new npm package: mkdir my-package cd my-package/ meteor npm init

The last command creates a package.json file and prompts you for the package information. You may skip everything but name , version , and entry point . You can use the default index.js for entry point . This file is where you set your package's exports: // my-package/index.js exports.myPackageLog = function() { console.log("logged from my-package"); };

Now apps that include this package can do: import { myPackageLog } from 'my-package' myPackageLog(); // > "logged from my-package"

When choosing a name for your npm package, be sure to follow the npm guidelines.

Including in your app When you are developing a new npm package for your app, there are a couple methods for including the package in your app: Inside node_modules: Place the package in your app's node_modules/ directory, and add the package to source control. Do this when you want everything in a single repository. cd my-app/node_modules/ mkdir my-package cd my-package/ meteor npm init git add -f ./ # or use a git submodule

npm link: Place the package outside your app's directory in a separate repository and use npm link . Do this when you want to use the package in multiple apps.

203

Writing npm Packages

cd ~/ mkdir my-package cd my-package/ meteor npm init cd ~/my-app/ meteor npm link ~/my-package

Other developers will also need to run the npm link command. After either method, edit the dependencies attribute of my-app/package.json , adding "mypackage": "1.0.0" (use the same version number you chose during meteor npm init ).

Publishing your package You can share your package with others by publishing it to the npm registry. While most packages are public, you can control who may view and use your package with private modules). To publish publicly, follow these instructions. When you're done, anyone can add your package to their app with npm install --save your-package . If you want to share packages during development, we recommend using the above methods instead of the registry. If you use the registry, then every time you change the package, you need to increment the version number, publish, and then npm update mypackage inside your app.

Overriding packages with a local version If you need to modify a package to do something that the published version doesn't do, you can edit a local version of the package on your computer. Let's say you want to modify the left-pad npm package. If you haven't already, run inside your app directory: meteor npm install --save left-pad

Now left-pad is included in your package.json , and the code has been downloaded to node_modules/left_pad/ . Add the new directory to source control with:

git add -f node_modules/left_pad/

204

Writing npm Packages

Now you can edit the package, commit, and push, and your teammates will get your version of the package. To ensure that your package doesn't get overwritten during an npm update , change the default caret version range in your package.json to an exact version. Before: "left-pad": "^1.0.2",

After: "left-pad": "1.0.2",

An alternative method is maintaining a separate repository for the package and changing the package.json version number to a git URL or tarball, but every time you edit the separate

repo, you'll need to commit, push, and npm update left-pad .

205

Mobile

After reading this guide, you'll know: 1. What Cordova is, and how Meteor integrates with it to build mobile apps from a single codebase 2. How to set up your local machine for mobile development 3. How to run and debug your app on a mobile device or simulator/emulator 4. How hot code push allows you to update your mobile app's code without reinstalling the app on your device or submitting a new version to the store 5. How to use Cordova plugins to take advantage of native device features 6. How to access local files and remote resources from your app 7. What you can do to create a good mobile user experience for your app 8. How to configure your app to use your own app icon, launch screen, and set other preferences 9. How to build your project and submit your mobile app to the store

Meteor Cordova integration Meteor integrates with Cordova, a well-known Apache open source project, to build mobile apps from the same codebase you use to create regular web apps. With the Cordova integration in Meteor, you can take your existing app and run it on an iOS or Android device with a few simple commands. A Cordova app is a web app written using HTML, CSS, and JavaScript as usual, but it runs in a web view embedded in a native app instead of in a stand-alone mobile browser. An important benefit of packaging up your web app as a Cordova app is that all your assets are bundled with the app. This ensures your app will load faster than a web app running on a remote server could, which can make a huge difference for users on slow mobile connections. Another feature of the Cordova integration in Meteor is support for hot code push, which allows you to update your app on users' devices without going through the usual app store review process. Cordova also opens up access to certain native device features through a plugin architecture. Plugins allow you to use features not usually available to web apps, such as accessing the device camera or the local file system, interact with barcode or NFC readers, etc. Because a Cordova app is a web app, this means you use standard web elements to create your user interface instead of relying on platform-specific native UI components. Creating a good mobile user experience is an art in itself, but is fortunately helped by the availability of various frameworks and libraries.

206

Mobile

What about PhoneGap? You may have heard of PhoneGap, and wonder how it relates to Cordova. PhoneGap is a product name used by Adobe since 2011, when they acquired a company called Nitobi, the original creators of what is now the Cordova project. When Adobe donated the code to Apache in 2012 to ensure a more open governance model, the open source project was rebranded as Cordova. PhoneGap is now one of the distributions of Cordova, on a par with other distributions like Ionic, Telerik, Monaca, or Intel XDK. These distributions mainly differ in tooling and integration with cloud services, but they share the underlying platform and plugins. Meteor could also be considered a Cordova distribution.

How does it work? With Meteor, there is no need to install Cordova yourself, or use the cordova command directly. Cordova project creation happens as part of the Meteor run and build commands, and the project itself is considered a build artifact (stored in .meteor/local/cordova-build in your app directory) that can be deleted and recreated at any time. Instead of having you modify Cordova's config.xml file, Meteor reads a mobile-config.js file in the root of your app directory and uses the settings specified there to configure the generated project. Cordova apps don’t load web content over the network, but rely on locally stored HTML, CSS, JavaScript code and other assets. While Cordova by default uses file:// URLs to load the app, Meteor includes an integrated file serving mechanism on the device to support both bundling the initial assets and incrementally updating your app through hot code push. This means your app will be served from http://localhost: , which also has the benefit that web views consider it a secure origin and won't block any sensitive features (which they increasingly do for file:// URLs).

207

Mobile

What port will your app be served from? While Meteor uses a built-in request interception mechanism on Android, supporting WKWebView on iOS requires running a real embedded web server instead. That means

the local web server needs a port to bind to, and we can’t simply use a fixed port because that might lead to conflicts when running multiple Meteor Cordova apps on the same device. The easiest solution may seem to use a randomized port, but this has a serious drawback: if the port changes each time you run the app, web features that depend on the origin (like caching, localStorage, IndexedDB) won’t persist between runs, and you also wouldn't be able to specify a stable OAuth redirect URL. So instead we now pick a port from a predetermined range (12000-13000), calculated based on the appId , a unique identifier that is part of every Meteor project. That ensures the same app will always use the same port, but it hopefully avoids collisions betweens apps as much as possible. (There is still a theoretical possibility of the selected port being in use. Currently, starting the local server will fail in that case.)

The runtime environment Cordova apps run in a web view. A web view is basically a browser without the browser UI. Browser engines differ in their underlying implementation and in what web standards they support. As a result, what web view your app runs on can have a huge impact on your app's performance and on the features you get to use. (If you want to know what features are supported on what browsers and versions, caniuse.com is a great resource.)

iOS The browser on iOS is Safari, which is based on the open source WebKit project, but tends to be somewhat slow in enabling new features. Because they use the same underlying framework, the features available to a web view match the features supported by Safari on the iOS release you're running on. Meteor uses WKWebView by default, on both iOS 8 and iOS 9. WKWebView is part of the modern WebKit API introduced in iOS 8, and replaces UIWebView, which has been in iOS from the beginning. Its main benefit is that it runs in a separate process, allowing for much higher JavaScript performance (3–4x in some benchmarks!) because it can take advantage of Just-In-Time compilation (which UIWebView, running in the same process as your app, cannot do for security reasons).

208

Mobile

You may be aware that WKWebView on iOS 8 doesn't allow files to be loaded from the local filesystem. This is problematic for standard Cordova apps, because these use file:// URLs to load the app. But because the Meteor integration serves assets from localhost , WKWebView works fine on both iOS 8 and iOS 9.

Android The web view situation on Android is a little more complicated. On older Android versions, the included web view is known to be rather slow and buggy. That improved somewhat with Android 4.4, which includes a web view based on Chromium, the open source project behind the Chrome browser. Android 5.0 also comes with a web view based on Chromium known as the Android System Web View, but a big improvement is that it can be automatically updated through the Play Store. This means updates to the web view happen more regularly and are independent of OS updates. This threatens to leave many older Android devices behind however, because they would be stuck on the web view included with the OS and are often unable to update to newer OS versions. Fortunately, the Crosswalk plugin allows you to embed Chromium in your app and use it instead of the web view that comes with the OS on any of the Android versions supported by Cordova (currently Android 4.0 or higher). Embedding Chromium means the size of your APK will grow by about 20MB, but the benefit is that you can rely on a consistent web view with considerably better performance and enhanced standards support. You can add the Crosswalk plugin to your app with meteor add crosswalk . If you receive an error message trying to run the app on your device after adding or removing the Crosswalk plugin, you may have to remove the existing app from your device first.

Adding Cordova platforms Every Meteor project targets a set of platforms. Platforms can be added to a Meteor project with meteor add-platform . meteor add-platform ios adds the iOS platform to a project. meteor add-platform android adds the Android platform to a project. meteor remove-platform ios android will remove the iOS and Android platforms from a

project. meteor list-platforms lists the platforms targeted by your project.

209

Mobile

If your local machine does not (yet) fulfill the prerequisites for building apps for a mobile platform, an error message with a list of missing requirements is printed (but the platform is still added). You will have to make sure these requirements are fulfilled before you're able to build and run mobile apps from your machine.

Installing prerequisites In order to build and run mobile apps, you will need to install some prerequisites on your local machine.

iOS In order to build and run iOS apps, you will need a Mac with Xcode 7.2 or higher installed.

Installing Xcode from the App Store meteor add-platform ios will open a dialog asking you whether you want to install the

'command line developer tools'. Do not select 'Install' here, because a full Xcode installation is required to build and run iOS apps. Instead, selecting 'Get Xcode' will open the Mac App Store page for Xcode and you can click install there. (Alternatively, you can open the Mac App Store and search for 'Xcode' to get to that same page.)

Accepting the license agreement After the download and installation completes, you will need to accept the license agreement. If you start Xcode for the first time, a dialog will pop up where you can read the license agreement and accept it. You can close Xcode directly afterwards. A shortcut is to run sudo xcodebuild -license accept from the command line. (You will still be expected to have read and understood the Xcode and Apple SDKs Agreement).

Android In order to build and run Android apps, you will need to: Install a Java Development Kit (JDK) Install the Android SDK and download the required tools, platforms, and other components (which is done most easily by installing Android Studio) Set ANDROID_HOME and add the tools directories to your PATH Optionally: Create an Android Virtual Device to run apps on an emulator

210

Mobile

Installing the Java Development Kit (JDK) On Linux, you may want to use your distribution's package manager to install a JDK; on Ubuntu, you can even use Ubuntu Make to install Android Studio and all dependencies at the same time. 1. Open the Oracle Java website, and select the Java Platform (JDK) 2. Check the box to accept the license agreement, and select the correct download for your platform 3. After it has downloaded, launch the installer, and complete the installation steps

Installing Android Studio The easiest way to get a working Android development environment is by installing Android Studio, which offers a setup wizard on first launch that installs the Android SDK for you, and downloads a default set of tools, platforms, and other components that you will need to start developing. Please refer to the Android Studio installation instructions for more details on the exact steps to follow. There is no need to use Android Studio if you prefer a stand-alone install. Just make sure you install the most recent versions of the Android SDK Tools and download the required additional packages yourself using the Android SDK Manager. Make sure to select SDK Platform API 23, because that is what the version of Cordova we bundle requires.

Using Ubuntu Make If you're running Ubuntu, the easiest way to install both a Java Development Kit and Android Studio is by using Ubuntu Make, a command line tool that sets up development environments and dependencies for you. If you're on Ubuntu 14.04 LTS, you'll have to add the Ubuntu Make ppa first: sudo add-apt-repository ppa:ubuntu-desktop/ubuntu-make sudo apt-get update

Then, you can install Ubuntu Make itself: sudo apt-get install ubuntu-make

And finally you use Ubuntu Make to install Android Studio and all dependencies: umake android

211

Mobile

Setting `ANDROID_HOME` and adding the tools directories to your `PATH` Cordova will detect an Android SDK installed in various standard locations automatically, but in order to use tools like android or adb from the terminal, you will have to make some changes to your environment. Mac Set the ANDROID_HOME environment variable to the location of the Android SDK. If you've used the Android Studio setup wizard, it should be installed in ~/Library/Android/sdk by default. Add $ANDROID_HOME/tools , and $ANDROID_HOME/platform-tools to your PATH You can do this by adding these lines to your ~/.bash_profile file (or the equivalent file for your shell environment, like ~/.zshrc ): # Android export ANDROID_HOME="$HOME/Library/Android/sdk" export PATH=$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools

You will then have to reload .bash_profile (by executing source ~/.bash_profile ) or open a new terminal session to apply the new environment.

Optionally: Creating an Android Virtual Device (AVD) to run apps on an emulator The current Android emulator tends to be rather slow and can be unstable, so our recommendation is to run your app on a physical device instead. If you do want to run on an emulator however, you will have to create an Android Virtual Device (AVD) using the AVD Manager. Make sure to configure one with API level 23, because that is what the version of Cordova we bundle requires.

Developing on a device During development, the Meteor build tool integrates with Cordova to run your app on a physical device or the iOS Simulator/Android emulator. In addition to starting a development server and MongoDB instance as usual, meteor run accepts arguments to run the app on one or more mobile targets: ios : Runs the app on the iOS Simulator

212

Mobile

Currently, this will always run your app on a simulated iPhone 6s Plus. Use iosdevice to open Xcode and select another simulator instead. ios-device : Opens Xcode, where you can run the app on a connected iOS device or

simulator android : Runs the app on the Android emulator

The current Android emulator tends to be rather slow and can be unstable. Our recommendation is to run on a physical device or to use an alternative emulator like Genymotion. android-device : Runs the app on a connected Android device

You can specify multiple targets, so meteor run ios android-device will run the app on both the iOS Simulator and an Android device for example.

Connecting to the server A Meteor app should be able to connect to a server in order to load data and to enable hot code push, which automatically updates a running app when you make changes to its files. During development, this means the device and the computer you run meteor on will have to be part of the same WiFi network, and the network configuration shouldn't prevent the device from reaching the server. You may have to change your firewall or router settings to allow for this (no client isolation). meteor run will try to detect the local IP address of the computer running the command

automatically. If this fails, or if you would like your mobile app to connect to a different server, you can specify an address using the --mobile-server option.

On iOS Note: If you haven't previously developed iOS apps, or haven't used the connected device for development, a series of dialogs and warnings may appear as Xcode resolves code signing issues. It may also prompt you for permission to access the key in your keychain. See Apple's instructions for more information. 1. Make sure the device is connected to your computer via a USB cable. 2. Connect the device to a WiFi network that allows for communication with the server. 3. Run meteor run ios-device to open your project in Xcode. 4. In the project navigator, choose your device from the Scheme toolbar menu:

213

Mobile

5. Click the Run button: 6. Xcode builds the app, installs it on the device, and launches it.

On Android 1. Make sure the device is connected to your computer via a USB cable. 2. Connect the device to a WiFi network that allows for communication with the server. 3. Make sure your device is set up for development as explained here.

214

Mobile

4. You may also need to click 'Allow' on the Allow USB debugging? prompt on the device. 5. Run meteor run android-device to build the app, install it on the device, and launch it. To check if your device has been connected and set up correctly, you can run adb devices to get a list of devices.

Logging and debugging A full-stack mobile app consists of many moving parts, and this can make it difficult to diagnose issues. Logging is indispensable in keeping track of what's going on in your app, and may show warnings and errors that you would otherwise miss. Even more powerful is remote debugging, which is the ability to interact with a mobile app running on a remote device from a debugging interface in Safari (for iOS) or Chrome (for Android).

Different types of logs You will encounter three types of logs in a Meteor Cordova app: Server-side logs - Messages printed by the Meteor build system, and the result of console logging calls from server-side code.

Client-side web logs - Warnings and errors from the web view, and the result of console logging calls from client-side code.

Client-side native logs - Messages from system components and Cordova plugins. This also includes more detailed logging from the Meteor plugin used for hot code push. When using meteor run , server-side logs will be printed in the terminal as usual. In addition, running on an Android device or emulator will print a subset of the logs to that same terminal (these logs also include console logging calls made from client-side code). Running on iOS will not show client-side logs in the terminal, but Xcode will show native logs as usual in the debug console. You can add cordova-plugin-console to your project to output console logging calls to the native logs (which Android does by default), but this isn't

recommended because it has a substantial performance impact, and remote debugging gives you much nicer and more complete console output. Although having client-side logs in the terminal can be useful, in most cases remote debugging is a much better option. This allows you to use the debugging tools built into Safari (for iOS apps) or Chrome (for Android apps) to investigate an app running on a remote device or a simulator/emulator. Here, you can not only view the logs, but also interact with running JavaScript code and the DOM, monitor network access, etc.

Debugging on iOS with Safari 215

Mobile

1. To use remote debugging in Safari, you'll first need to enable the Developer menu. Go to Safari > Preferences and make sure 'Show Develop menu in menu bar' is checked:

216

Mobile

2. You'll also need to enable the Web Inspector on your iOS device. Go to Settings > Safari > Advanced and enable 'Web Inspector':

3. Launch the app on your device and open remote debugger by choosing Develop > > /localhost. 4. Because you can only connect to your app after it has started up, you sometimes miss startup warnings and errors. You can invoke location.reload() in the Web Inspector console to reload a running app, this time with the remote debugger connected. You can find more information about remote debugging in the Safari Developer Guide.

217

Mobile

Debugging on Android with Chrome See this article for instructions on how to remote debug your Android app with the Chrome DevTools. Because you can only connect to your app after it has started up, you sometimes miss startup warnings and errors. You can invoke location.reload() in the DevTools console to reload a running app, this time with the remote debugger connected.

Hot code push on mobile During development, the Meteor build tool detects any relevant file changes, recompiles the necessary files, and notifies all connected clients a new version is available. Clients can then automatically reload the app, switching over to the new version of the code. This is referred to as hot code push. Meteor supports hot code push on both browser and mobile clients, but the process on mobile is a bit different. In a browser, reloading the app will re-request assets from the server, and the server will respond with the most recent versions. Because Cordova apps rely on locally stored assets however, hot code push on mobile is a two step process: 1. Updated assets are downloaded from the server using native downloading mechanisms, and stored on the device 2. The page is reloaded and the web view re-requests the assets from the local web server An important benefit of this is that while downloading may be slow over mobile connections, this is done in the background, and we won't attempt to reload the app until all assets have been downloaded to the device. Downloading updates is done incrementally, so we only download assets that have actually changed (based on a content hash). In addition, if we haven't been able to download all changed assets in one go, because of a network failure or because the app was closed before we finished, we will reuse the ones that have already completed downloading the next time the app starts up or the network connection is restored.

In production Hot code push greatly improves the development experience, but on mobile, it is also a really useful feature for production apps, because it allows you to quickly push updates to devices without having users update the app through the store and without going through a possibly lengthy review process to get your update accepted.

218

Mobile

However, it is important to realize that hot code push can only be used to update the HTML, CSS, JavaScript code and other assets making up your web app. Changes to native code will still require you to submit a new version of your app to the store. In order to avoid a situation where JavaScript code that relies on changed native code is pushed to a client, we calculate a compatibility version from the Cordova platform and plugin versions, and only download a new version to a device when there is an exact match. This means any change to the list of plugins, or updating to a Meteor release which contains a new platform version, will block hot code push to existing mobile clients until the app has been updated from the store. Something else to keep in mind is that your server-side code should be prepared to handle requests from older client versions, which may not yet have been updated. As you make changes to your data schema or publication functions for example, you may want to reflect on how this will impact backwards compatibility.

Configuring your server As mentioned before, mobile apps need to be able to connect to a server to support hot code push. In production, you will need to specify which server to connect to when building the app using the --server option. The specified server address is used to set ROOT_URL in __meteor_runtime_config__ , which is defined as part of the generated index.html in the

app bundle. In addition, you will need to configure the server with the right connection address. This happens automatically if you're using meteor deploy to deploy to Galaxy, but when deploying to your own server you'll have to make sure to define the ROOT_URL environment variable there. (For Meteor Up, you can configure this in mup.json .) The reason this is needed is because updates delivered through hot code push replace the initially bundled index.html with a freshly generated one. If the ROOT_URL on your server hasn't been set, it defaults to localhost:3000 , and this would leave the app unable to connect to the server, both for data loading and for receiving further hot code pushes. In Meteor 1.3, we protect against this by blocking updates that would change the ROOT_URL to localhost , but the consequence of this is that hot code push is disabled until you configure ROOT_URL correctly.

Recovering from faulty versions Hot code pushing updated JavaScript code to a device could accidentally push code containing errors, which might leave users with a broken app (a 'white screen of death', in the worst case), and could even disable hot code push (because the code that makes a

219

Mobile

connection to the server may no longer run). To avoid this, we try to detect faulty versions and revert to the last known good version when this happens. The way detection works is that we expect all Meteor.startup() callbacks to complete within a set period of time. If this doesn't happen we consider the version faulty and will rollback the update. Unless the version on the server has been updated in the meantime, the server will try to hot code push the faulty version again. Therefore, we blacklist faulty versions on the device so we know not to retry. By default, the startup timeout is set to 20 seconds. If your app needs more time to startup (or considerably less), you can use App.setPreference to set WebAppStartupTimeout to another value.

Native features with Cordova plugins Cordova comes with a plugin architecture that opens up access to features not usually available to web apps. Plugins are installable add-ons that contain both JavaScript and native code, which allows them to translate calls from your web app to platform-specific APIs. The Apache Cordova project maintains a set of core plugins that provide access to various native device features such as the camera, contacts, or access to the file system. But anyone can write a Cordova plugin to do basically anything that can be done from native code, and many third-party plugins are available. You can search for plugins on the Cordova website or directly on npm. Be warned however, that although the core plugins are generally well maintained and up to date with the rest of Cordova, the quality of third-party plugins can be a bit of a gamble. You also have to make sure the plugin you want to use is compatible with the Cordova platform versions Meteor bundles.

Installing plugins Plugins are identified by a name, which is generally the same as their npm package name. The current convention is for plugin names to start with cordova-plugin- , but not all thirdparty plugins adhere to this. You can add Cordova plugins to your project either directly, or as a dependency of a Meteor package. If you want to add a plugin to your project directly, you use the same meteor add command you use for Meteor packages, but with a cordova: prefix:

220

Mobile

meteor add cordova:[email protected]

In contrast to Meteor packages, you'll have to specify the exact version of the plugin. This can be a bit of a pain because you first need to look up what the most recent (compatible) version of a plugin is before you can add it. A Meteor package can register a dependency on a Cordova plugin with the Cordova.depends() syntax. For example, a Meteor package that depends on the Cordova

camera plugin would add the following to its package.js : Cordova.depends({ 'cordova-plugin-camera': '1.2.0' });

This means adding the Meteor package to your project would also install the specified Cordova plugin. Note: If multiple Meteor packages add the same Cordova plugin but at different versions, there is no clear way of telling which version will end up being installed. Plugins added to your project directly however, will always override versions of the same plugin added as a dependency of packages. Because installing plugins into a Cordova project already containing plugins can lead to indeterminate results, Meteor will remove and add back all plugins whenever a change to any of the plugins in your project is made. Cordova downloads plugins from npm, and caches them (in ~/.cordova/lib/npm_cache ) so they don't have to be downloaded repeatedly if you rebuild or use them again in another project.

221

Mobile

Making sure a plugin is compatible with the bundled Cordova platform versions Because there is a tight coupling between plugin versions and Cordova platform versions, you may encounter build time or runtime errors as a result of incompatible plugins. If this happens, you will have to install a different plugin version, or it may turn out a plugin is not (yet) compatible with the Cordova platform versions we bundle. In order to help with this, we pin core plugins to a minimum version known to work with the Cordova versions we bundle. This mechanism doesn't apply to third-party plugins however, so you'll have to assess compatibility for these yourself. There is ongoing work in the Cordova project that will improve this situation and make it easier for plugins to specify their platform dependencies, so Cordova can determine compatible versions.

Setting plugin parameters Some Cordova plugins require certain parameters to be set as part of the build process. For example, com-phonegap-plugins-facebookconnect requires you to specify an APP_ID and APP_NAME . You can set these using App.configurePlugin in your mobile-config.js.

Installing a plugin from Git Alternatively, if unreleased changes have been made to a plugin you'd like to use, you can also have Cordova download plugin code from a Git repository. Note that this will clone the plugin repository on every rebuild however, so this can be rather slow and should be avoided where possible. In contrast to default Cordova, Meteor requires you to specify the exact SHA hash for a commit, rather than allow you to refer to a branch or tag. This is done to guarantee repeatable builds and also avoids unnecessary reinstallation of all plugins because as long as the SHA is the same we know nothing has changed. The syntax to add a plugin from Git is kind of awkward. The name (the part before the @ ) is the plugin ID and will have to match what is specified in the plugin's plugin.xml . Instead of a version, you specify a URL to a Git repository with the SHA hash as an anchor (the part after the # ): meteor add cordova:com.phonegap.plugins.facebookconnect@https://github.com/Wizcorp/pho negap-facebook-plugin.git#5dbb1583168558b4447a13235283803151cb04ec

Meteor packages can also depend on plugins downloaded from Git:

222

Mobile

Cordova.depends({ 'com.phonegap.plugins.facebookconnect': 'https://github.com/Wizcorp/phonegap-faceb ook-plugin.git#5dbb1583168558b4447a13235283803151cb04ec' });

Installing a plugin from the local file system Finally, especially if you're developing your own plugin, installing it from the local filesystem can be a convenient way to keep up with changes you make to plugin code. The downside of this is that Meteor will reinstall all plugins on every build however, so this could really slow things down. We do add local plugins with the --link option however, so Cordova will try to install the plugin's files using symlinks instead of copying them, which means changes to files will be reflected in the generated native project (e.g. an Xcode project) and may not require a rebuild. You install plugins from the local file system by specifying a file:// URL, which gets interpreted relative to the project directory: meteor add cordova:cordova-plugin-underdevelopment@file://../plugins/cordova-plugin-un derdevelopment

Meteor packages can also depend on plugins installed from the local file system, although this probably only makes sense for local packages: Cordova.depends({ 'cordova-plugin-underdevelopment': 'file://../plugins/cordova-plugin-underdevelopm ent' });

Removing directly installed plugins You can remove a previously added plugin using meteor remove : meteor remove cordova:cordova-plugin-camera meteor remove cordova:com.phonegap.plugins.facebookconnect meteor remove cordova:cordova-plugin-underdevelopment

Using plugins

223

Mobile

You should wrap any functionality which relies on a Cordova plugin in a Meteor.startup() block to make sure the plugin has been fully initialized (by listening to the deviceready event). For example, when using the Cordova geolocation plugin: // The plugin may not have been initialized here navigator.geolocation.getCurrentPosition(success); Meteor.startup(function() { // Here we can be sure the plugin has been initialized navigator.geolocation.getCurrentPosition(success); });

Detecting Cordova in your JavaScript code Just as you can use Meteor.isServer and Meteor.isClient to separate your client-side and server-side code, you can use Meteor.isCordova to separate your Cordova-specific code from the rest of your code. if (Meteor.isServer) { console.log("Printed on the server"); } if (Meteor.isClient) { console.log("Printed in browsers and mobile apps"); } if (Meteor.isCordova) { console.log("Printed only in mobile Cordova apps"); }

In addition, packages can include a different set of files for Cordova builds and browser builds with addFiles : api.addFiles('foo.js', 'web.cordova') : includes foo.js in only Cordova builds. api.addFiles('bar.js', 'web.browser') : includes bar.js in only browser builds. api.addFiles('baz.js', 'web') : includes baz.js in all client builds.

The same syntax can be used for api.use , api.imply , and api.export .

Accessing local files and remote resources As a web app, Cordova apps are subject to various security mechanisms designed to protect the integrity of your code and to avoid certain types of attacks. Which security mechanisms are in use may depend on the type and version of the web view your app runs

224

Mobile

in. In addition, Cordova itself, and in some cases the OS, adds different levels of access control that may also affect what content can and cannot be loaded. All this can make it fairly confusing to understand why something is not working, and even harder to understand the security implications of the various ways of configuring these mechanisms.

Local files Because the Cordova integration in Meteor does not serve your app from file:// URLs, access to local files through file:// URLs is not allowed either due to the same-origin policy. The file serving mechanism used in Meteor allows for local file access through URLs of the form http://localhost:/local-filesystem/ ) however. You can construct these file system URLs manually, or use WebAppLocalServer.localFileSystemUrl() to convert file:// URLs. You can use this to convert URLs received from plugins like cordovaplugin-file and cordova-plugin-camera for example.

Domain whitelisting Cordova controls access to external domains through a whitelisting mechanism, which is implemented as cordova-plugin-whitelist in the version of Cordova we bundle. In Meteor, you use App.accessRule in mobile-config.js to set additional rules. (These correspond to , and tags in the generated config.xml .)

On iOS, these settings also control Application Transport Security (ATS), which is an OS level mechanism to enforce security best practices new to iOS 9. If the server you're connecting to does not (yet) fulfill these requirements, you can use additional options to override them for specific domains: App.accessRule('https://domain.com', { 'minimum-tls-version': 'TLSv1.0', 'requires-forward-secrecy': false, });

By default, Cordova apps in Meteor are only allowed access to localhost (the device itself, to serve the app from) and the server your app connects to for data loading and hot code push (either an automatically detected IP address an explicitly configured mobile server domain). These restrictions also apply to loading files in iframes and to opening files in other apps (including the mobile browser).

225

Mobile

Note that these restrictions mean you will have to explicitly allow loading data: URLs. For example, to allow loading data: URLs in iframes you would add: App.accessRule('data:*', { type: 'navigation' });

Content Security Policy (CSP) In addition to the domain whitelisting mechanism Cordova implements, the web view itself may also enforce access rules through Content Security Policy (CSP). For now, Meteor adds a permissive { return "http://mycdn.com/" + asset });



CDNs and webfonts If you are hosting a webfont as part of your application and serving it via a CDN, you may need to configure the served headers for the font to allow cross-origin resource sharing (as the webfont is now served from a different origin to your site itself). You can do this easily enough in Meteor by adding a handler (you'll need to ensure your CDN is passing the header through): import { WebApp } from 'meteor/webapp'; WebApp.rawConnectHandlers.use(function(req, res, next) { if (req._parsedUrl.pathname.match(/\.(ttf|ttc|otf|eot|woff|woff2|font\.css|css)$/)) { res.setHeader('Access-Control-Allow-Origin', /* your hostname, or just '*' */); } next(); });

And then for example with Cloudfront, you would: Select your distribution Behavior tab Select your app origin Edit button Under "Whitelist Headers", scroll down to select "Origin"

256

Deployment and Monitoring

Add button "Yes, Edit" button

Deployment options Meteor is an open source platform, and you can run the apps that you make with Meteor anywhere just like regular Node.js applications. But operating Meteor apps correctly, so that your apps work for everyone, can be tricky if you are managing your infrastructure manually. This is why we recommend running production Meteor apps on Galaxy.

Galaxy (recommended) The easiest way to operate your app with confidence is to use Galaxy, the service built by Meteor Development Group specifically to run Meteor apps. Galaxy is a distributed system that runs on Amazon AWS. If you understand what it takes to run Meteor apps correctly and just how Galaxy works, you’ll come to appreciate Galaxy’s value, and that it will save you a lot of time and trouble. Most large Meteor apps run on Galaxy today, and many of them have switched from custom solutions they used prior to Galaxy’s launch. In order to deploy to Galaxy, you'll need to sign up for an account, and separately provision a MongoDB database (see below). Once you've done that, it's easy to deploy to Galaxy. You just need to add some environment variables to your settings file to point it at your MongoDB, and you can deploy with: DEPLOY_HOSTNAME=us-east-1.galaxy-deploy.meteor.com meteor deploy your-app.com --settin gs production-settings.json

In order for Galaxy to work with your custom domain ( your-app.com in this case), you need to set up your DNS to point at Galaxy. Once you've done this, you should be able to reach your site from a browser. You can also log into the Galaxy UI at https://galaxy.meteor.com. Once there you can manage your applications, monitor the number of connections and resource usage, view logs, and change settings.

257

Deployment and Monitoring

If you are following our advice, you'll probably want to set up SSL on your Galaxy application with the certificate and key for your domain. The key things here are to add the force-ssl package and to use the Galaxy UI to add your SSL certificate. Once you are setup with Galaxy, deployment is simple (just re-run the meteor deploy command above), and scaling is even easier---simply log into galaxy.meteor.com, and scale instantly from there.

258

Deployment and Monitoring

MongoDB hosting services to use with Galaxy If you are using Galaxy (or need a production quality, managed MongoDB for one of the other options listed here), it's usually a good idea to use a MongoDB hosting provider. There are a variety of options out there, but a good choice is mLab. The main things to look for are support for oplog tailing, and a presence in the us-east-1 or eu-west-1 AWS region.

Meteor Up Meteor Up, often referred to as "mupx" or "mup", is a third-party open-source tool that can be used to deploy Meteor application to any online server over SSH. It handles some of the essential deployment requirements, but you will still need to do a lot of work to get your load balancing and version updates working smoothly. It's essentially a way to automate the manual steps of using meteor build and putting that bundle on your server. You can obtain a server running Ubuntu or Debian from many generic hosting providers and Meteor Up can SSH into your server with the keys you provide in the config. You can also watch this video for a more complete walkthrough on how to do it. Meteor Up has multiple projects so select what is best for your project:

259

Deployment and Monitoring

Original Meteor Up (not generally recommended any longer) The mupx branch (best for pre-Meteor 1.4) The kadirahq/mup fork (best for Meteor 1.4 or higher) Currently, using Meteor Up with Meteor 1.4 requires kadirahq/mup (still in development) and a special docker image with the correct Node version. For further assistance, consult the documentation for the option you select.

Custom deployment If you want to figure out your hosting solution completely from scratch, the Meteor tool has a command meteor build that creates a deployment bundle that contains a plain Node.js application. Any npm dependencies must be installed before issuing the meteor build command to be included in the bundle. You can host this application wherever you like and there are many options in terms of how you set it up and configure it. NOTE it's important that you build your bundle for the correct architecture. If you are building on your development machine, there's a good chance you are deploying to a different server architecture. You'll want to specify the correct architecture with --architecture : # for example if deploying to a Ubuntu linux server: npm install --production meteor build /path/to/build --architecture os.linux.x86_64

This will provide you with a bundled application .tar.gz which you can extract and run without the meteor tool. The environment you choose will need the correct version of Node.js and connectivity to a MongoDB server. Depending on the version of Meteor you are using, you should install the proper version of node using the appropriate installation process for your platform.

Node 4.4.7 for Meteor 1.4.x Node 0.10.43 for Meteor 1.3.x and earlier If you use a mis-matched version of Node when deploying your application, you will encounter errors! You can then run the application by invoking node with a ROOT_URL , and MONGO_URL . These instructions are also available in the README file found in the root of the bundle you built above.

260

Deployment and Monitoring

cd my_build_bundle_directory (cd programs/server && npm install) MONGO_URL=mongodb://localhost:27017/myapp ROOT_URL=http://my-app.com node main.js

ROOT_URL is the base URL for your Meteor project MONGO_URL is a Mongo connection string URI supplied by the MongoDB provider.

Unless you have a specific need to roll your own hosting environment, the other options here are definitely easier, and probably make for a better setup than doing everything from scratch. Operating a Meteor app in a way that it works correctly for everyone can be complex, and Galaxy handles a lot of the specifics like routing clients to the right containers and handling coordinated version updates for you.

Deployment process Although it's much easier to deploy a web application than release most other types of software, that doesn't mean you should be cavalier with your deployment. It's important to properly QA and test your releases before you push them live, to ensure that users don't have a bad experience, or even worse, data get corrupted. It's a good idea to have a release process that you follow in releasing your application. Typically that process looks something like: 1. Deploy the new version of the application to your staging server. 2. QA the application on the staging server. 3. Fix any bugs found in step 2. and repeat. 4. Once you are satisfied with the staging release, release the exact same version to production. 5. Run final QA on production. Steps 2. and 5. can be quite time-consuming, especially if you are aiming to maintain a high level of quality in your application. That's why it's a great idea to develop a suite of acceptance tests (see our Testing Article for more on this). To take things even further, you could run a load/stress test against your staging server on every release.

Continuous deployment Continuous deployment refers to the process of deploying an application via a continuous integration tool, usually when some condition is reached (such as a git push to the master branch). You can use CD to deploy to Galaxy, as Nate Strauser explains in a blog post on the subject.

261

Deployment and Monitoring

Rolling deployments and data versions It's important to understand what happens during a deployment, especially if your deployment involves changes in data format (and potentially data migrations, see the Collections Article). When you are running your app on multiple servers or containers, it's not a good idea to shut down all of the servers at once and then start them all back up again. This will result in more downtime than necessary, and will cause a huge spike in CPU usage when all of your clients reconnect again at the same time. To alleviate this, Galaxy stops and re-starts containers one by one during deployment. There will be a time period during which some containers are running the old version and some the new version, as users are migrated incrementally to the new version of your app.

If the new version involves different data formats in the database, then you need to be a little more careful about how you step through versions to ensure that all the versions that are running simultaneously can work together. You can read more about how to do this in the collections article.

262

Deployment and Monitoring

Monitoring users via analytics It's common to want to know which pages of your app are most commonly visited, and where users are coming from. Here's a simple setup that will get you URL tracking using Google Analytics. We'll be using the okgrow:analytics package. meteor add okgrow:analytics

Now, we need to configure the package with our Google Analytics key (the package also supports a large variety of other providers, check out the documentation on Atmosphere). Pass it in as part of Meteor settings: { "public": { "analyticsSettings": { // Add your analytics tracking id's here "Google Analytics" : {"trackingId": "Your tracking ID"} } } }

The analytics package hooks into Flow Router (see the routing article for more) and records all of the page events for you. You may want to track non-page change related events (for instance publication subscription, or method calls) also. To do so you can use the custom event tracking functionality: export const updateText = new ValidatedMethod({ ... run({ todoId, newText }) { // We use `isClient` here because we only want to track // attempted method calls from the client, not server to // server method calls if (Meteor.isClient) { analytics.track('todos.updateText', { todoId, newText }); } // ... } });

To achieve a similar abstraction for subscriptions/publications, you may want to write a simple wrapper for Meteor.subscribe() .

263

Deployment and Monitoring

Monitoring your application When you are running an app in production, it's vitally important that you keep tabs on the performance of your application and ensure it is running smoothly.

Understanding Meteor performance Although a host of tools exist to monitor the performance of HTTP, request-response based applications, the insights they give aren't necessarily useful for a connected client system like a Meteor application. Although it's true that slow HTTP response times would be a problem for your app, and so using a tool like Pingdom can serve a purpose, there are many kinds of issues with your app that won't be surfaced by such tools.

Monitoring with Galaxy Galaxy offers turnkey Meteor hosting and provides tools that are useful to debug the current and past state of your application. CPU and Memory load graphs in combination with connected user counts can be vital to determining if your setup is handling the current load (or if you need more containers), or if there's some specific user action that's causing disproportionate load (if they don't seem to be correlated):

264

Deployment and Monitoring

Galaxy's UI provides a detailed logging system, which can be invaluable to determine which action it is causing that extra load, or to generally debug other application issues:

265

Deployment and Monitoring

Kadira If you really want to understand the ins and outs of running your Meteor application, you should give Kadira a try. Kadira is a full featured Application Performance Monitoring (APM) solution that's built from the ground up for Meteor. Kadira operates by taking regular client and server side observations of your application's performance as it conducts various activities and reporting them back to a master server. When you visit the Kadira application, you can view current and past behavior of your application over various useful metrics. Kadira's documentation is extensive and invaluable, but we'll discuss a few key areas here.

Method and Publication Latency Rather than monitoring HTTP response times, in a Meteor app it makes far more sense to consider DDP response times. The two actions your client will wait for in terms of DDP are method calls and publication subscriptions. Kadira includes tools to help you discover which of your methods and publications are slow and resource intensive.

266

Deployment and Monitoring

In the above screenshot you can see the response time breakdown of the various methods commonly called by the Atmosphere application. The median time of 56ms and 99th percentile time of 200ms seems pretty reasonable, and doesn't seem like too much of a concern You can also use the "traces" section to discover particular cases of the method call that are particular slow:

267

Deployment and Monitoring

In the above screenshot we're looking at a slower example of a method call (which takes 214ms), which, when we drill in further we see is mostly taken up waiting on other actions on the user's connection (principally waiting on the searches/top and counts publications). So we could consider looking to speed up the initial time of those subscriptions as they are slowing down searches a little in some cases.

Livequery Monitoring A key performance characteristic of Meteor is driven by the behavior of livequery, the key technology that allows your publications to push changing data automatically in realtime. In order to achieve this, livequery needs to monitor your MongoDB instance for changes (by tailing the oplog) and decide if a given change is relevant for the given publication. If the publication is used by a lot of users, or there are a lot of changes to be compared, then these livequery observers can do a lot of work. So it's immensely useful that Kadira can tell you some statistics about your livequery usage:

268

Deployment and Monitoring

In this screenshot we can see that observers are fairly steadily created and destroyed, with a pretty low amount of reuse over time, although in general they don't survive for all that long. This would be consistent with the fact that we are looking at the package publication of Atmosphere which is started everytime a user visits a particular package's page. The behavior is more or less what we would expect so we probably wouldn't be too concerned by this information.

Enabling SEO If your application contains a lot of publicly accessible content, then you probably want it to rank well in Google and other search engines' indexes. As most webcrawlers do not support client-side rendering (or if they do, have spotty support for websockets), it's better to render the site on the server and deliver it as HTML in this special case. To do so, we can use the Prerender.io service, thanks to the dfischer:prerenderio package. It's a simple as meteor add -ing it, and optionally setting your prerender token if you have a premium prerender account and would like to enable more frequent cache changes.

269

Deployment and Monitoring

If you’re using Galaxy to host your meteor apps, you can also take advantage of built-in automatic Prerender.io integration. Simply add mdg:seo to your app and Galaxy will take care of the rest. Chances are you also want to set tags and other content to make your site appear nicer in search results. The best way to do so is to use the kadira:dochead package. The sensible place to call out to DocHead is from the onCreated callbacks of your page-level components.

270