diff --git a/.github/workflows/guide-main-deploy.yml b/.github/workflows/guide-main-deploy.yml
new file mode 100644
index 0000000000..ad8811e6f6
--- /dev/null
+++ b/.github/workflows/guide-main-deploy.yml
@@ -0,0 +1,52 @@
+name: Meteor Guide main deploy
+on:
+ push:
+ paths:
+ - 'guide/**/*'
+jobs:
+ test:
+ runs-on: ubuntu-latest
+ defaults:
+ run:
+ working-directory: guide/site/
+ if:
+ contains('
+ refs/heads/devel
+ refs/heads/master
+ ', github.ref)
+ steps:
+ - uses: actions/checkout@v2
+ - name: Test build
+ uses: actions/setup-node@v1
+ with:
+ node-version: 12.x
+ - run: npm ci && npm run build
+ deploy:
+ runs-on: ubuntu-latest
+ defaults:
+ run:
+ working-directory: guide/site/
+ needs: [test]
+ if:
+ contains('
+ refs/heads/devel
+ refs/heads/master
+ ', github.ref)
+ steps:
+ - uses: actions/checkout@v2
+ - uses: actions/setup-node@v1
+ with:
+ node-version: 12.x
+ - name: Build the Guide
+ run: npm ci && npm run build
+ - name: Deploy to Netlify for preview
+ uses: nwtgck/actions-netlify@v1.2.2
+ with:
+ publish-dir: './guide/site/public'
+ production-branch: devel
+ github-token: ${{ secrets.GITHUB_TOKEN }}
+ deploy-message: "Deploy from GitHub Actions"
+ netlify-config-path: './guide/netlify.toml'
+ env:
+ NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+ NETLIFY_SITE_ID: ${{ secrets.NETLIFY_GUIDE_SITE_ID }}
diff --git a/.github/workflows/guide.yml b/.github/workflows/guide.yml
new file mode 100644
index 0000000000..1349619fcd
--- /dev/null
+++ b/.github/workflows/guide.yml
@@ -0,0 +1,62 @@
+name: Meteor Guide PR
+on:
+ push:
+ paths:
+ - 'guide/**/*'
+ pull_request:
+ paths:
+ - 'guide/**/*'
+jobs:
+ preview:
+ runs-on: ubuntu-latest
+ defaults:
+ run:
+ working-directory: guide/site/
+ steps:
+ - uses: actions/checkout@v2
+ - uses: actions/setup-node@v1
+ with:
+ node-version: 12.x
+ - name: Build the Guide
+ run: npm ci && npm run build
+ - name: Deploy to Netlify for preview
+ uses: nwtgck/actions-netlify@v1.2.2
+ with:
+ publish-dir: './guide/site/public'
+ production-branch: devel
+ github-token: ${{ secrets.GITHUB_TOKEN }}
+ deploy-message: "Deploy from GitHub Actions"
+ netlify-config-path: './guide/netlify.toml'
+ alias: deploy-preview-${{ github.event.number }}
+ env:
+ NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+ NETLIFY_SITE_ID: ${{ secrets.NETLIFY_GUIDE_SITE_ID }}
+ deploy-branch:
+ runs-on: ubuntu-latest
+ defaults:
+ run:
+ working-directory: guide/site/
+ if:
+ contains('
+ refs/heads/release-
+ ', github.ref)
+ steps:
+ - uses: actions/checkout@v2
+ - uses: actions/setup-node@v1
+ with:
+ node-version: 12.x
+ - name: Build the Guide
+ run: npm ci && npm run build
+ - name: Deploy to Netlify for preview
+ uses: nwtgck/actions-netlify@v1.2.2
+ with:
+ publish-dir: './guide/site/public'
+ production-branch: devel
+ github-token: ${{ secrets.GITHUB_TOKEN }}
+ deploy-message: "Deploy from GitHub Actions"
+ netlify-config-path: './guide/netlify.toml'
+ alias: ${{ github.head_ref }}
+ env:
+ NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+ NETLIFY_SITE_ID: ${{ secrets.NETLIFY_GUIDE_SITE_ID }}
+
diff --git a/.gitmodules b/.gitmodules
index 98c826a7a2..bb583d831f 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -1,7 +1,9 @@
[submodule "packages/non-core/blaze"]
path = packages/non-core/blaze
url = https://github.com/meteor/blaze.git
+[submodule "guide/site/themes/meteor"]
+ path = guide/site/themes/meteor
+ url = https://github.com/meteor/hexo-theme-meteor.git
[submodule "docs/themes/meteor"]
path = docs/themes/meteor
url = https://github.com/meteor/hexo-theme-meteor.git
-
diff --git a/Readme.md b/Readme.md
new file mode 100644
index 0000000000..ec46004063
--- /dev/null
+++ b/Readme.md
@@ -0,0 +1 @@
+# Readme
\ No newline at end of file
diff --git a/guide/.gitignore b/guide/.gitignore
new file mode 100644
index 0000000000..36c97bc1a3
--- /dev/null
+++ b/guide/.gitignore
@@ -0,0 +1,3 @@
+.DS_Store
+npm-debug.log
+.idea/
diff --git a/guide/CHANGELOG.md b/guide/CHANGELOG.md
new file mode 100644
index 0000000000..fc0e4771ff
--- /dev/null
+++ b/guide/CHANGELOG.md
@@ -0,0 +1,39 @@
+---
+title: Changelog
+order: 1001
+description: A log of significant changes to the Meteor Guide.
+---
+- 2021/07/21: Added "Apollo" article
+- 2021/07/20: Tweaked VueJS navigation structure and updated some information. Mention Picker in server-side routing.
+- 2020/09/13: Removed the section about crosswalk from the Cordova guide
+- 2020/08/08: Added "Hot Code Push" guide
+- 2020/04/26: Added "React Native" section to build, and renamed "Mobile" to "Cordova"
+- 2020/02/03: Added "Preventing unnecessary data retrieval" section to Accounts
+- 2018/10/23: Added VueJS SSR Rendering for Meteor guide
+- 2018/10/14: Added VueJS Integration guide
+- 2018/03/03: Added HTTP Headers to the production security section and made Helmet the official recommendation. Update Mobile section to refer to HTTP header section for CSP instead of Browser Policy package. [#750](https://github.com/meteor/guide/pull/750)
+- 2017/10/28: Removed mention of `react-addons-pure-render-mixin` package from "Using Meteor's data system" section as it is no longer needed.
+- 2017/09/08: Updated "Using Meteor's data system" section to describe the new `withTracker` function as it now replaces `createContainer`.
+- 2017/03/22: Added Docker section within Deployment and Monitoring.
+- 2017/03/05: Updated "Testing" to use the replacement `dispatch:mocha` package instead of the previous suggestions from `dispatch:*`. [PR#618](https://github.com/meteor/guide/pull/618) [PR#614](https://github.com/meteor/guide/pull/614)
+- 2017/02/08: Updated MongoDb hosting services with more details and recommendations. [PR#609](https://github.com/meteor/guide/pull/609)
+- 2017/01/19: Updated recommendations for forcing SSL to avoid the `force-ssl` package when possible.
+- 2017/01/07: Created new section "TypeScript".
+- 2017/01/04: Changed "Testing" section to reference `dburles:factory` in the same spirit as the `meteor/todos` app [PR #598](https://github.com/meteor/guide/pull/598)
+- 2016/07/02: Created new section in ui-ux on use of i18n with React.
+- 2016/05/28: Created new section "A simple React unit test" [PR #466](https://github.com/meteor/guide/pull/466).
+- 2016/05/22: Created new section "Testing publications" for separated `publication-collector` package (as [discussed here](https://github.com/meteor/todos/issues/119)).
+- 2016/05/05: Changed Build Section organization to separate Atmosphere and npm. [Discussed here](https://github.com/meteor/guide/pull/390#issuecomment-212577341). [PR #410](https://github.com/meteor/guide/pull/410)
+- 2016/04/16: Switch order of Code Style and Application structure sections. [PR #383](https://github.com/meteor/guide/pull/383)
+- 2016/04/16: Added [Writing Packages - Creating an npm package](https://guide.meteor.com/writing-packages.html#creating-npm) and [Using Packages - Overriding packages - npm](https://guide.meteor.com/using-packages.html#npm-overriding). [PR #381](https://github.com/meteor/guide/pull/381)
+- 2016/04/16: Added "Writing Packages - Creating an npm package" and "Using Packages - Overriding packages - npm". [PR #381](https://github.com/meteor/guide/pull/381)
+Fixed old changelog PR reference
+- 2016/04/07: Add more examples and details on application structure using imports. [PR #356](https://github.com/meteor/guide/pull/356)
+- 2016/04/04: Add more content on writing and publishing Atmosphere packages. [PR #339](https://github.com/meteor/guide/pull/339)
+- 2016/04/03: Add back in build tool default loading order rules. [PR #340](https://github.com/meteor/guide/pull/340)
+- 2016/04/01: Added CoffeeScript exports syntax. [PR #328](https://github.com/meteor/guide/pull/328)
+- 2016/04/01: Changed Mocha test code snippets to use function expressions instead of arrow functions, after the discussion on [Issue #318](https://github.com/meteor/guide/issues/318). [PR #323](https://github.com/meteor/guide/pull/323)
+- 2016/04/01: Added `gadicc:blaze-react-component` in a new "Blaze in React" section of the React article. [PR #325](https://github.com/meteor/guide/pull/325)
+- 2016/03/31: Added Chromatic demo video and React Storybook to User Interfaces article. [PR #320](https://github.com/meteor/guide/pull/320)
+
+Changelog is only tracked since the Meteor 1.3 release.
diff --git a/guide/CONTRIBUTING.md b/guide/CONTRIBUTING.md
new file mode 100644
index 0000000000..97566ab217
--- /dev/null
+++ b/guide/CONTRIBUTING.md
@@ -0,0 +1,67 @@
+---
+title: Contribution Guidelines
+order: 1000
+description: Tips for contributing to the Meteor Guide.
+---
+
+Please submit clarifications and improvements to the Guide! If it's just a small fix, go ahead and open a PR. If it's something more major, please file an issue for discussion first.
+
+### Using the change log
+
+If you are adding significant new content, please take a moment to include an update to the [changelog](changelog.html) in your PR.
+
+### Writing tips
+
+Things to be aware of:
+
+#### Always use specific IDs on headers so that we can change them later:
+
+```markdown
+// bad
+## Using schemas with collections
+
+// good
+
Using schemas with collections
+```
+
+#### Titles and headers
+
+Article titles are `Title Case`, and headers are `Sentence case`.
+
+#### Always put a blank line after each header
+
+Otherwise, the following paragraph isn't parsed correctly.
+
+```markdown
+// bad
+
Using schemas with collections
+This is some text
+
+// good
+
Using schemas with collections
+
+This is some text
+```
+
+#### Escape handlebars syntax inside inline code snippets
+
+Note: you don't need to escape things in fenced/multiline code snippets, only in inline ones.
+
+```markdown
+// will break
+Render multiple items in your template with `{{#each}}`
+
+// good
+Render multiple items in your template with `{% raw %}{{#each}}{% endraw %}`
+```
+
+### Running the static site generator locally
+
+The site is built using hexo, a static site generator. To run it locally, perform the following steps:
+
+```shell
+git submodule update --init --recursive
+cd site
+npm install
+npm start
+```
diff --git a/guide/LICENSE.txt b/guide/LICENSE.txt
new file mode 100644
index 0000000000..9384c902f6
--- /dev/null
+++ b/guide/LICENSE.txt
@@ -0,0 +1,18 @@
+========================================
+Meteor is licensed under the MIT License
+========================================
+
+Copyright (C) 2011-present Meteor Development Group
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+====================================================================
+This license applies to all code in Meteor that is not an externally
+maintained library. Externally maintained libraries have their own
+licenses, included in the LICENSES directory.
+====================================================================
diff --git a/guide/README.md b/guide/README.md
new file mode 100644
index 0000000000..28dd424e5c
--- /dev/null
+++ b/guide/README.md
@@ -0,0 +1,3 @@
+# Meteor Guide
+
+[Read the guide!!](http://guide.meteor.com/)
diff --git a/guide/content/1.10-migration.md b/guide/content/1.10-migration.md
new file mode 100644
index 0000000000..095411a235
--- /dev/null
+++ b/guide/content/1.10-migration.md
@@ -0,0 +1,64 @@
+---
+title: Migrating to Meteor 1.10
+description: How to migrate your application to Meteor 1.10.
+---
+
+Most of the new features in Meteor 1.10 are either applied directly behind the scenes (in a backwards compatible manner) or are opt-in. For a complete breakdown of the changes, please refer to the [changelog](http://docs.meteor.com/changelog.html).
+
+The above being said, some breaking changes to note and migration steps for a bug that you might encounter.
+
+
Unexpected mongo exit code 62
+
+If you get `Unexpected mongo exit code 62. Restarting.` when starting your local
+MongoDB, you can either reset your project (`meteor reset`)
+(if you don't care about your local data)
+or you will need to update the feature compatibility version of your local MongoDB:
+
+ 1. Downgrade your app to earlier version of Meteor `meteor update --release 1.9.2`
+ 2. Start your application
+ 3. While your application is running open a new terminal window, navigate to the
+ app directory and open `mongo` shell: `meteor mongo`
+ 4. Use: `db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 })` to
+ check the current feature compatibility.
+ 5. If the returned version is less than 4.0 update like this:
+ `db.adminCommand({ setFeatureCompatibilityVersion: "4.2" })`
+ 6. You can now stop your app and update to Meteor 1.10.
+
+ For more information about this, check out [MongoDB documentation](https://docs.mongodb.com/manual/release-notes/4.2-upgrade-standalone/).
+
+
Cordova upgrade
+
+Cordova has been updated from version 7 to 9. We recommend that you test
+your features that are taking advantage of Cordova plugins to be sure
+they are still working as expected.
+
+
WKWebViewOnly
+
+WKWebViewOnly is set by default now as true so if you are relying on
+UIWebView or plugins that are using UIWebView APIs you probably want to
+set it as false, you can do this by calling
+`App.setPreference('WKWebViewOnly', false);` in your mobile-config.js. But we
+don't recommend turning this into false because
+[Apple have said](https://developer.apple.com/news/?id=12232019b) they are
+going to reject apps using UIWebView.
+
+
Windows 32-bit support dropped
+
+Because MongoDB since 3.4 no longer supports 32-bit Windows, Meteor 1.10 has
+also dropped support for 32-bit Windows. In other words, Meteor 1.10 supports
+64-bit Mac, Windows 64-bit, and Linux 64-bit.
+
+
Migrating from a version older than 1.9.3?
+
+If you're migrating from a version of Meteor older than Meteor 1.9.3, there may be important considerations not listed in this guide (which specifically covers 1.9.3 to 1.10). Please review the older migration guides for details:
+
+* [Migrating to Meteor 1.9.3](1.9.3-migration.html) (from 1.9)
+* [Migrating to Meteor 1.9](1.9-migration.html) (from 1.8.3)
+* [Migrating to Meteor 1.8.3](1.8.3-migration.html) (from 1.8.2)
+* [Migrating to Meteor 1.8.2](1.8.2-migration.html) (from 1.8)
+* [Migrating to Meteor 1.8](1.8-migration.html) (from 1.7)
+* [Migrating to Meteor 1.7](1.7-migration.html) (from 1.6)
+* [Migrating to Meteor 1.6](1.6-migration.html) (from 1.5)
+* [Migrating to Meteor 1.5](1.5-migration.html) (from 1.4)
+* [Migrating to Meteor 1.4](1.4-migration.html) (from 1.3)
+* [Migrating to Meteor 1.3](1.3-migration.html) (from 1.2)
diff --git a/guide/content/1.10.2-migration.md b/guide/content/1.10.2-migration.md
new file mode 100644
index 0000000000..80ced95c78
--- /dev/null
+++ b/guide/content/1.10.2-migration.md
@@ -0,0 +1,44 @@
+---
+title: Migrating to Meteor 1.10.2
+description: How to migrate your application to Meteor 1.10.2.
+---
+
+Most of the new features in Meteor 1.10.2 are either applied directly behind the scenes (in a backwards compatible manner) or are opt-in. For a complete breakdown of the changes, please refer to the [changelog](http://docs.meteor.com/changelog.html).
+
+The above being said, there is a breaking change for those using the Flow syntax.
+
+
Flow syntax not supported
+
+The `babel-compiler` package, used by both `ecmascript` and
+`typescript`, no longer supports stripping [Flow](https://flow.org/)
+type annotations by default, which may be a breaking change if your
+application (or Meteor package) relied on Flow syntax.
+
+If you still need Babel's Flow plugins, you can install them with npm
+and then enable them with a custom `.babelrc` file in your application's
+(or package's) root directory:
+
+```json
+{
+"plugins": [
+ "@babel/plugin-syntax-flow",
+ "@babel/plugin-transform-flow-strip-types"
+]
+}
+```
+
+
Migrating from a version older than 1.10?
+
+If you're migrating from a version of Meteor older than Meteor 1.10, there may be important considerations not listed in this guide (which specifically covers 1.10 to 1.10.2). Please review the older migration guides for details:
+
+* [Migrating to Meteor 1.10](1.10-migration.html) (from 1.9.3)
+* [Migrating to Meteor 1.9.3](1.9.3-migration.html) (from 1.9)
+* [Migrating to Meteor 1.9](1.9-migration.html) (from 1.8.3)
+* [Migrating to Meteor 1.8.3](1.8.3-migration.html) (from 1.8.2)
+* [Migrating to Meteor 1.8.2](1.8.2-migration.html) (from 1.8)
+* [Migrating to Meteor 1.8](1.8-migration.html) (from 1.7)
+* [Migrating to Meteor 1.7](1.7-migration.html) (from 1.6)
+* [Migrating to Meteor 1.6](1.6-migration.html) (from 1.5)
+* [Migrating to Meteor 1.5](1.5-migration.html) (from 1.4)
+* [Migrating to Meteor 1.4](1.4-migration.html) (from 1.3)
+* [Migrating to Meteor 1.3](1.3-migration.html) (from 1.2)
diff --git a/guide/content/1.11-migration.md b/guide/content/1.11-migration.md
new file mode 100644
index 0000000000..34564f8b23
--- /dev/null
+++ b/guide/content/1.11-migration.md
@@ -0,0 +1,36 @@
+---
+title: Migrating to Meteor 1.11
+description: How to migrate your application to Meteor 1.11.
+---
+
+Most of the new features in Meteor 1.11 are either applied directly behind the scenes (in a backwards compatible manner) or are opt-in. For a complete breakdown of the changes, please refer to the [changelog](http://docs.meteor.com/changelog.html).
+
+The above being said, there some breaking changes to note and migration steps for a bug that you might encounter.
+
+
Email DNS lookup
+
+`email` package dependencies have been update and package version has been bumped to 2.0.0
+There is a potential breaking change as the underlying package started to use `dns.resolve()`
+instead of `dns.lookup()` which might be breaking on some environments.
+See [nodemailer changelog](https://github.com/nodemailer/nodemailer/blob/master/CHANGELOG.md) for more information.
+
+
Cordova now working with Git urls
+
+Cordova add plugin is not working with plugin name in the git URL when the plugin id was different than the name in the config.xml.
+
+
Migrating from a version older than 1.10.2?
+
+If you're migrating from a version of Meteor older than Meteor 1.10.2, there may be important considerations not listed in this guide (which specifically covers 1.10.2 to 1.11). Please review the older migration guides for details:
+
+* [Migrating to Meteor 1.10.2](1.10.2-migration.html) (from 1.10)
+* [Migrating to Meteor 1.10](1.10-migration.html) (from 1.9.3)
+* [Migrating to Meteor 1.9.3](1.9.3-migration.html) (from 1.9)
+* [Migrating to Meteor 1.9](1.9-migration.html) (from 1.8.3)
+* [Migrating to Meteor 1.8.3](1.8.3-migration.html) (from 1.8.2)
+* [Migrating to Meteor 1.8.2](1.8.2-migration.html) (from 1.8)
+* [Migrating to Meteor 1.8](1.8-migration.html) (from 1.7)
+* [Migrating to Meteor 1.7](1.7-migration.html) (from 1.6)
+* [Migrating to Meteor 1.6](1.6-migration.html) (from 1.5)
+* [Migrating to Meteor 1.5](1.5-migration.html) (from 1.4)
+* [Migrating to Meteor 1.4](1.4-migration.html) (from 1.3)
+* [Migrating to Meteor 1.3](1.3-migration.html) (from 1.2)
diff --git a/guide/content/1.12-migration.md b/guide/content/1.12-migration.md
new file mode 100644
index 0000000000..12c0443d60
--- /dev/null
+++ b/guide/content/1.12-migration.md
@@ -0,0 +1,42 @@
+---
+title: Migrating to Meteor 1.12
+description: How to migrate your application to Meteor 1.12.
+---
+
+Most of the new features in Meteor 1.12 are either applied directly behind the scenes (in a backwards compatible manner) or are opt-in. For a complete breakdown of the changes, please refer to the [changelog](http://docs.meteor.com/changelog.html).
+
+The above being said, there are some breaking changes to note.
+
+
Importing types
+
+When importing types in Typescript, you might need to use the "type" qualifier, like so:
+```js
+import { Point } from 'react-easy-crop/types';
+```
+to
+```ts
+import type { Point } from 'react-easy-crop/types';
+```
+Because now `emitDecoratorsMetadata` is enabled.
+
+
Typescript upgraded to 4.1.2
+
+Refer to typescript breaking changes before migrating your existing project, from 3.7.6 to 4.1.2: https://github.com/Microsoft/TypeScript/wiki/Breaking-Changes
+
+
Migrating from a version older than 1.11?
+
+If you're migrating from a version of Meteor older than Meteor 1.11, there may be important considerations not listed in this guide (which specifically covers 1.11 to 1.12). Please review the older migration guides for details:
+
+* [Migrating to Meteor 1.11](1.11-migration.html) (from 1.10.2)
+* [Migrating to Meteor 1.10.2](1.10.2-migration.html) (from 1.10)
+* [Migrating to Meteor 1.10](1.10-migration.html) (from 1.9.3)
+* [Migrating to Meteor 1.9.3](1.9.3-migration.html) (from 1.9)
+* [Migrating to Meteor 1.9](1.9-migration.html) (from 1.8.3)
+* [Migrating to Meteor 1.8.3](1.8.3-migration.html) (from 1.8.2)
+* [Migrating to Meteor 1.8.2](1.8.2-migration.html) (from 1.8)
+* [Migrating to Meteor 1.8](1.8-migration.html) (from 1.7)
+* [Migrating to Meteor 1.7](1.7-migration.html) (from 1.6)
+* [Migrating to Meteor 1.6](1.6-migration.html) (from 1.5)
+* [Migrating to Meteor 1.5](1.5-migration.html) (from 1.4)
+* [Migrating to Meteor 1.4](1.4-migration.html) (from 1.3)
+* [Migrating to Meteor 1.3](1.3-migration.html) (from 1.2)
diff --git a/guide/content/1.3-migration.md b/guide/content/1.3-migration.md
new file mode 100644
index 0000000000..4880298a99
--- /dev/null
+++ b/guide/content/1.3-migration.md
@@ -0,0 +1,238 @@
+---
+title: Migrating to Meteor 1.3
+description: How to migrate your application to use recommended best practice as of Meteor 1.3.
+discourseTopicId: 20190
+---
+
+
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.
+
+ - Ensure that your project has a [`package.json`](https://docs.npmjs.com/files/package.json) file, which will be the foundation for npm package installs. You can create this by running:
+ ```
+ meteor npm init -y
+ ```
+ - Files in a directory named `imports/` will no longer load eagerly. (You should probably rename such a directory as it is the basis of our new [module system](#modules)).
+
+ - Files within your app named `*.test[s].*`, `*.app-test[s].*`, `*.spec[s].*` and `*.app-spec[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](#testing)).
+
+ - 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](#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](https://developer.mozilla.org/en/docs/web/javascript/reference/statements/import) 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.
+
+- You should load all Meteor "pseudo-globals" using the `import { Name } from 'meteor/package'` syntax. For instance:
+
+```js
+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:
+
+```bash
+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](http://docs.meteor.com/#/full/packagejs) 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.
+
+```js
+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](structure.html) of the Meteor Guide, and how to test them in the [Testing article](testing.html).
+
+- If you are using Atmosphere packages which wrap npm packages, both on the client and server, it is now recommended that you 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 a development dependency for testing etc.). We have [some tips](using-packages.html#async-callbacks) about how to use npm packages written in an asynchronous style.
+
+Also, you should no longer need to use the [`meteorhacks:npm`](https://atmospherejs.com/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. Use [`import`](structure.html#intro-to-import-export) 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()`](http://1.3-docs.meteorapp.com/#/full/modularpackagestructure) 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`](https://github.com/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](#angular-meteor-packages). Read more about this in the [Writing Packages article](writing-packages.html#peer-npm-dependencies).
+
+
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](testing.html).
+
+
Full app testing
+
+If you were previously using [Velocity](http://xolv.io/velocity-announcement/) 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.
+
+- 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`](https://atmospherejs.com/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*](testing.html#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](#modules) 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](#full-app-testing)) 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](https://github.com/meteor/todos)
+
+
Recommendations: Mobile
+
+Alongside some of the breaking mobile changes [listed above](#breaking-changes-mobile), 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
+
+In Meteor 1.3, we recommend installing `react` and `react-dom` [into your app using npm](react.html#using-with-meteor), and importing them from your app code:
+
+```js
+import React from 'react';
+import ReactDOM from 'react-dom';
+```
+
+As mentioned in the [breaking changes](#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](using-packages.html) 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](react.html) 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](#modules):
+
+```js
+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](react.html#data) for combining Meteor's data system with React in an idiomatic way. We encourage you to use containers to separate your data loading concerns from your presentational components!
+
+
Install Angular from npm
+
+With an Angular Meteor app you can safely update to Meteor 1.3 without any changes to your code.
+You 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:
+```js
+import angular from 'angular';
+import angular-meteor from 'angular-meteor';
+```
+
+Read the [Using Packages](using-packages.html) 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](#modules):
+
+```js
+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 unbreaking update process:
+
+Change your `angular:angular` dependency into a weak dependency:
+```js
+api.use('angular:angular@1.5.3', 'client', { weak: true });
+```
+and then add a dependency check for both Meteor 1.2 and 1.3 before initializing your angular module:
+```js
+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](structure.html) article which explains how to structure your files and use the module system.
+
+ - There's a [Code Style](code-style.html) article that makes recommendations about how to ensure consistent formatting for your code.
+
+ - There's a [Testing](testing.html) article which covers how to do various kinds of testing in Meteor.
+
+ - There's a [React](react.html) article which explains how to best use React with Meteor
+
+ - There's a [Mobile](mobile.html) article which covers how to best use our Cordova integration.
+
+ - There's a [Using Packages](using-packages.html) article which explains how best to use both npm and Atmosphere packages in your app.
+
+- There's a [Writing Packages](writing-packages.html) 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](ui-ux.html#i18n) in Meteor applications.
diff --git a/guide/content/1.4-migration.md b/guide/content/1.4-migration.md
new file mode 100644
index 0000000000..0d48d5d79a
--- /dev/null
+++ b/guide/content/1.4-migration.md
@@ -0,0 +1,89 @@
+---
+title: Migrating to Meteor 1.4
+description: How to migrate your application to use recommended best practice as of Meteor 1.4.
+discourseTopicId: 26998
+---
+
+
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](#recommendations).
+
+### The `babel-runtime` npm is usually required
+
+
+The `babel-runtime` npm package is generally required as a dependency since the Meteor `babel-runtime` package no longer attempts to provide custom implementations of Babel helper functions. To install the `babel-runtime` npm, run the following command in any Meteor application:
+```
+meteor npm install --save babel-runtime
+```
+New projects created with `meteor create ` will automatically have this package added to their `package.json`'s `dependencies`.
+
+
Binary Packages require a Build Toolchain
+
+The headline feature of Meteor 1.4 is the upgrade to Node version 4. 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](http://railsapps.github.io/xcode-command-line-tools.html) (in short, run `xcode-select --install`).
+
+ - Windows users should install the [MS Build Tools](https://www.microsoft.com/en-us/download/details.aspx?id=48159).
+
+ - 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
+
+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](#update-to-mongo-3_2) 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](https://www.mongodb.com/support-policy) 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](https://docs.mongodb.com/manual/release-notes/2.6-upgrade/) 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](https://github.com/meteor/meteor/blob/devel/History.md#v14) and [the oplog documentation](https://github.com/meteor/docs/blob/master/long-form/oplog-observe-driver.md#oplogobservedriver-in-production)).
+
+> NOTE: Some MongoDB hosting providers may have a deployment setup that doesn't require you to use a `replicaSet` argument. For example, [Compose.io](https://www.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](https://docs.mongodb.com/manual/release-notes/3.0-scram/#upgrade-mongodb-cr-to-scram), 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
+
+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](https://docs.mongodb.com/manual/release-notes/3.2-upgrade/). To update your storage engine, you should ensure you follow the ["Change Storage Engine to WiredTiger"](https://docs.mongodb.com/v3.0/release-notes/3.0-upgrade/#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](https://www.npmjs.com/package/reify) library, Meteor now fully supports nested `import` declarations in both application and package modules, whereas previously they were only allowed in application code:
+
+```js
+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](https://github.com/meteor/todos/commit/3963a65d96cd7ef235a95d5e3a331d6f0606f70f) — you can now use `import` wherever you like, without having to organize your tests in `client` or `server` directories.
diff --git a/guide/content/1.5-migration.md b/guide/content/1.5-migration.md
new file mode 100644
index 0000000000..917bbb0230
--- /dev/null
+++ b/guide/content/1.5-migration.md
@@ -0,0 +1,28 @@
+---
+title: Migrating to Meteor 1.5
+description: How to migrate your application to Meteor 1.5.
+discourseTopicId: 37099
+---
+
+This guide is quite short and we think you'll find the upgrade from 1.4 to 1.5 quite painless. We encourage reading [full history](http://docs.meteor.com/changelog.html) and comparing the full differences between the versions you are upgrading from and to.
+
+> If you find details which are not covered here, please discuss it using the "Discuss" button above, or if you have something super important, open a pull-request to this article using the "Edit on GitHub" button above!
+
+
Migrating from a version older than 1.4?
+
+If you're migrating from a version of Meteor older than Meteor 1.4, there may be important considerations not listed in this guide (which specifically covers 1.4 to 1.5). Please review the older migration guides for details:
+
+* [Migrating to Meteor 1.4](1.4-migration.html) (from 1.3)
+* [Migrating to Meteor 1.3](1.3-migration.html) (from 1.2)
+
+
`MAIL_URL` should be reviewed
+
+Due to an upgrade in the underlying dependency for the [`email` package](http://docs.meteor.com/api/email.html), it is necessary to check that your `MAIL_URL` is using the correct scheme (e.g. `smtps://` or `smtp://`).
+
+Previously, Meteor would automatically assume that any `MAIL_URL` using port 465 was to be encrypted and automatically changed `smtp://` to `smtps://`. However, this is not always desired, and not always a safe assumption for Meteor.
+
+If your `MAIL_URL` is TLS/SSL-only (and does not need [`STARTTLS`](https://en.wikipedia.org/wiki/Opportunistic_TLS)), be sure that the `MAIL_URL` starts with `smtps://` and not `smtp://`.
+
+Again, generally speaking, this applies to applications whose `MAIL_URL` already includes `:465`. If an application's mail provider supports `STARTTLS` (i.e. if the `MAIL_URL` uses `:587` and _sometimes_ `:25`), the application can continue to use `smtp://` (without the `s`) and the TLS/SSL upgrade will be made by the mail server, if supported.
+
+Unfortunately, the e-mail ecosystem is [confusing](http://busylog.net/smtp-tls-ssl-25-465-587/). More information can be found in the [Nodemailer docs](https://nodemailer.com/smtp/).
diff --git a/guide/content/1.6-migration.md b/guide/content/1.6-migration.md
new file mode 100644
index 0000000000..874197c893
--- /dev/null
+++ b/guide/content/1.6-migration.md
@@ -0,0 +1,32 @@
+---
+title: Migrating to Meteor 1.6
+description: How to migrate your application to Meteor 1.6.
+discourseTopicId: 40314
+---
+
+Most changes in Meteor 1.6 are related to the underlying Node.js upgrade . We encourage reading [full history](http://docs.meteor.com/changelog.html) and comparing the full differences between the versions you are upgrading from and to.
+
+> If you find details which are not covered here, please discuss it using the "Discuss" button above. If you find any important details which are not included here, please open a pull-request to this article using the "Edit on GitHub" button above to help other members of the community!
+
+
Migrating from a version older than 1.5?
+
+If you're migrating from a version of Meteor older than Meteor 1.5, there may be important considerations not listed in this guide (which specifically covers 1.5 to 1.6). Please review the older migration guides for details:
+
+* [Migrating to Meteor 1.5](1.5-migration.html) (from 1.4)
+* [Migrating to Meteor 1.4](1.4-migration.html) (from 1.3)
+* [Migrating to Meteor 1.3](1.3-migration.html) (from 1.2)
+
+
Node.js Breaking Changes
+
+The most significant update in Meteor 1.6 is the upgrade of the underlying Node.js version which Meteor relies on. While Meteor itself has made the appropriate changes, any core Node.js module usage within applications is subject to the breaking changes outlined by the Node.js change logs below which, when combined, cover the transition from Node.js 4 to 8:
+
+* [Breaking changes between v4 and v6](https://github.com/nodejs/node/wiki/Breaking-changes-between-v4-LTS-and-v6-LTS).
+* [Breaking changes between v6 and v7](https://github.com/nodejs/node/wiki/Breaking-changes-between-v6-and-v7).
+* [Changelog for Node 8](https://github.com/nodejs/node/blob/master/doc/changelogs/CHANGELOG_V8.md).
+ > At the time of writing, the official "_Breaking changes between v6 and v8_" was not yet available from the Node.js Foundation. The "Notable changes" section within this changelog is the best alternative resource.
+
+
Node.js Notable Changes
+
+While the Node.js change-logs are quite extensive, it is our experience so far that the most common change are the deprecations of the `new Buffer()` and `Buffer()` constructors. See the Node.js [`Buffer` documentation](https://nodejs.org/dist/latest-v8.x/docs/api/buffer.html#buffer_class_buffer) for more information on the correct replacements.
+
+When reviewing the changelog, pay close attention to any items which are marked as "removed".
diff --git a/guide/content/1.7-migration.md b/guide/content/1.7-migration.md
new file mode 100644
index 0000000000..2c732fad63
--- /dev/null
+++ b/guide/content/1.7-migration.md
@@ -0,0 +1,35 @@
+---
+title: Migrating to Meteor 1.7
+description: How to migrate your application to Meteor 1.7.
+---
+
+Most of the new features in Meteor 1.7 are either applied directly behind the scenes (in a backwards compatible manner) or are opt-in. For a complete breakdown of the changes, please refer to the [changelog](http://docs.meteor.com/changelog.html).
+
+The above being said, there are a few items that require additional attention, which are outlined below.
+
+
Babel / `meteor-node-stubs` updates
+
+After updating to Meteor 1.7 or 1.7.0.1, you should update the `@babel/runtime` npm package (as well as other Babel-related packages), and the `meteor-node-stubs` package, to their latest versions.
+
+```sh
+meteor npm install @babel/runtime@latest meteor-node-stubs@latest
+```
+
+
Mongo 3.6
+
+Mongo has been upgraded to version 3.6.4 for 64-bit systems, and 3.2.19 for 32-bit systems.
+
+After upgrading an application to use Mongo 3.6.4, it has been observed that attempting to run that application with an older version of Meteor (via `meteor --release X`), that uses an older version of Mongo, can prevent the application from starting. This can be fixed by either running `meteor reset` (**WARNING:** will wipe your local DB), or by repairing the Mongo database. To repair the database, find the mongod binary on your system that lines up with the Meteor release you are jumping back to, and run `mongodb --dbpath your-apps-db --repair`. For example:
+
+```sh
+~/.meteor/packages/meteor-tool/1.6.0_1/mt-os.osx.x86_64/dev_bundle/mongodb/bin/mongod --dbpath /my-app/.meteor/local/db --repair
+```
+
+
Migrating from a version older than 1.6?
+
+If you're migrating from a version of Meteor older than Meteor 1.6, there may be important considerations not listed in this guide (which specifically covers 1.6 to 1.7). Please review the older migration guides for details:
+
+* [Migrating to Meteor 1.6](1.6-migration.html) (from 1.5)
+* [Migrating to Meteor 1.5](1.5-migration.html) (from 1.4)
+* [Migrating to Meteor 1.4](1.4-migration.html) (from 1.3)
+* [Migrating to Meteor 1.3](1.3-migration.html) (from 1.2)
diff --git a/guide/content/1.8-migration.md b/guide/content/1.8-migration.md
new file mode 100644
index 0000000000..4d6e4a37e5
--- /dev/null
+++ b/guide/content/1.8-migration.md
@@ -0,0 +1,69 @@
+---
+title: Migrating to Meteor 1.8
+description: How to migrate your application to Meteor 1.8.
+---
+
+Most of the new features in Meteor 1.8 are either applied directly behind the scenes (in a backwards compatible manner) or are opt-in. For a complete breakdown of the changes, please refer to the [changelog](http://docs.meteor.com/changelog.html).
+
+The above being said, there is one required migration step and few things that you should note.
+
+
Update the `@babel/runtime`
+
+Update the `@babel/runtime` npm package to version 7.0.0 or later:
+
+```sh
+meteor npm install @babel/runtime@latest
+```
+
+
web.browser.legacy
+
+Meteor 1.7 introduced a new client bundle called `web.browser.legacy` in
+addition to the `web.browser` (modern) and `web.cordova` bundles.
+Naturally, this extra bundle increased client (re)build times. Since
+developers spend most of their time testing the modern bundle in
+development, and the legacy bundle mostly provides a safe fallback in
+production, Meteor 1.8 cleverly postpones building the legacy bundle
+until just after the development server restarts, so that development
+can continue as soon as the modern bundle has finished building. Since
+the legacy build happens during a time when the build process would
+otherwise be completely idle, the impact of the legacy build on server
+performance is minimal. Nevertheless, the legacy bundle still gets
+rebuilt regularly, so any legacy build errors will be surfaced in a
+timely fashion, and legacy clients can test the new legacy bundle by
+waiting a bit longer than modern clients. Applications using the
+`autoupdate` or `hot-code-push` packages will reload modern and legacy
+clients independently, once each new bundle becomes available.
+
+
Overriding package version
+
+The `.meteor/packages` file supports a new syntax for overriding
+problematic version constraints from packages you do not control.
+
+If a package version constraint in `.meteor/packages` ends with a `!`
+character, any other (non-`!`) constraints on that package elsewhere in
+the application will be _weakened_ to allow any version greater than or
+equal to the constraint, even if the major/minor versions do not match.
+
+For example, using both CoffeeScript 2 and `practicalmeteor:mocha` used
+to be impossible (or at least very difficult) because of this
+[`api.versionsFrom("1.3")`](https://github.com/practicalmeteor/meteor-mocha/blob/3a2658070a920f8846df48bb8d8c7b678b8c6870/package.js#L28)
+statement, which unfortunately constrained the `coffeescript` package to
+version 1.x. In Meteor 1.8, if you want to update `coffeescript` to
+2.x, you can relax the `practicalmeteor:mocha` constraint by putting
+ ```
+ coffeescript@2.2.1_1! # note the !
+ ```
+in your `.meteor/packages` file. The `coffeescript` version still needs
+to be at least 1.x, so that `practicalmeteor:mocha` can count on that
+minimum. However, `practicalmeteor:mocha` will no longer constrain the
+major version of `coffeescript`, so `coffeescript@2.2.1_1` will work.
+
+
Migrating from a version older than 1.7?
+
+If you're migrating from a version of Meteor older than Meteor 1.7, there may be important considerations not listed in this guide (which specifically covers 1.7 to 1.8). Please review the older migration guides for details:
+
+* [Migrating to Meteor 1.7](1.7-migration.html) (from 1.6)
+* [Migrating to Meteor 1.6](1.6-migration.html) (from 1.5)
+* [Migrating to Meteor 1.5](1.5-migration.html) (from 1.4)
+* [Migrating to Meteor 1.4](1.4-migration.html) (from 1.3)
+* [Migrating to Meteor 1.3](1.3-migration.html) (from 1.2)
diff --git a/guide/content/1.8.2-migration.md b/guide/content/1.8.2-migration.md
new file mode 100644
index 0000000000..5ca1685119
--- /dev/null
+++ b/guide/content/1.8.2-migration.md
@@ -0,0 +1,59 @@
+---
+title: Migrating to Meteor 1.8.2
+description: How to migrate your application to Meteor 1.8.2.
+---
+
+Most of the new features in Meteor 1.8.2 are either applied directly behind the scenes (in a backwards compatible manner) or are opt-in. For a complete breakdown of the changes, please refer to the [changelog](http://docs.meteor.com/changelog.html).
+
+The above being said, there are required migration steps that you should perform for this release to run smoothly.
+
+
Update the `@babel/runtime`
+
+Be sure to update the `@babel/runtime` npm package to its latest version
+(currently 7.7.2):
+
+```sh
+meteor npm install @babel/runtime@latest
+```
+
+
Meteor Node Stubs
+
+New Meteor applications now depend on `meteor-node-stubs@1.0.0`, so it
+may be a good idea to update to the same major version:
+
+```sh
+meteor npm install meteor-node-stubs@next
+```
+
+
Packages should be re-published
+
+If you are the author of any Meteor packages, and you encounter errors
+when using those packages in a Meteor 1.8.2 application (for example,
+`module.watch` being undefined), we recommend that you bump the minor
+version of your package and republish it using Meteor 1.8.2, so
+Meteor 1.8.2 applications will automatically use the new version of the
+package, as compiled by Meteor 1.8.2:
+
+```sh
+cd path/to/your/package
+# Add api.versionsFrom("1.8.2") to Package.onUse in package.js...
+meteor --release 1.8.2 publish
+```
+
+This may not be necessary for all packages, especially those that have
+been recently republished using Meteor 1.8.1, or local packages in the
+`packages/` directory (which are always recompiled from source).
+However, republishing packages is a general solution to a wide variety
+of package versioning and compilation problems, and package authors can
+make their users' lives easier by handling these issues proactively.
+
+
Migrating from a version older than 1.8?
+
+If you're migrating from a version of Meteor older than Meteor 1.8, there may be important considerations not listed in this guide (which specifically covers 1.8 to 1.8.2). Please review the older migration guides for details:
+
+* [Migrating to Meteor 1.8](1.8-migration.html) (from 1.7)
+* [Migrating to Meteor 1.7](1.7-migration.html) (from 1.6)
+* [Migrating to Meteor 1.6](1.6-migration.html) (from 1.5)
+* [Migrating to Meteor 1.5](1.5-migration.html) (from 1.4)
+* [Migrating to Meteor 1.4](1.4-migration.html) (from 1.3)
+* [Migrating to Meteor 1.3](1.3-migration.html) (from 1.2)
diff --git a/guide/content/1.8.3-migration.md b/guide/content/1.8.3-migration.md
new file mode 100644
index 0000000000..509309d76c
--- /dev/null
+++ b/guide/content/1.8.3-migration.md
@@ -0,0 +1,35 @@
+---
+title: Migrating to Meteor 1.8.3
+description: How to migrate your application to Meteor 1.8.3.
+---
+
+Most of the new features in Meteor 1.8.3 are either applied directly behind the scenes (in a backwards compatible manner) or are opt-in. For a complete breakdown of the changes, please refer to the [changelog](http://docs.meteor.com/changelog.html).
+
+The above being said, there is a required migration steps for those that use Blaze or jQuery.
+
+
Use NPM jQuery
+
+If your application uses `blaze-html-templates`, the Meteor `jquery`
+package will be automatically installed in your `.meteor/packages` file
+when you update to Meteor 1.8.3. However, this new version of the Meteor
+`jquery` package no longer bundles its own copy of the `jquery` npm
+implementation, so you may need to install `jquery` from npm by running
+
+```sh
+meteor npm i jquery
+```
+
+in your application directory. Symptoms of not installing jquery include
+a blank browser window, with helpful error messages in the console.
+
+
Migrating from a version older than 1.8.2?
+
+If you're migrating from a version of Meteor older than Meteor 1.8.2, there may be important considerations not listed in this guide (which specifically covers 1.8.2 to 1.8.3). Please review the older migration guides for details:
+
+* [Migrating to Meteor 1.8.2](1.8.2-migration.html) (from 1.8)
+* [Migrating to Meteor 1.8](1.8-migration.html) (from 1.7)
+* [Migrating to Meteor 1.7](1.7-migration.html) (from 1.6)
+* [Migrating to Meteor 1.6](1.6-migration.html) (from 1.5)
+* [Migrating to Meteor 1.5](1.5-migration.html) (from 1.4)
+* [Migrating to Meteor 1.4](1.4-migration.html) (from 1.3)
+* [Migrating to Meteor 1.3](1.3-migration.html) (from 1.2)
diff --git a/guide/content/1.9-migration.md b/guide/content/1.9-migration.md
new file mode 100644
index 0000000000..47d9426f78
--- /dev/null
+++ b/guide/content/1.9-migration.md
@@ -0,0 +1,27 @@
+---
+title: Migrating to Meteor 1.9
+description: How to migrate your application to Meteor 1.9.
+---
+
+Most of the new features in Meteor 1.9 are either applied directly behind the scenes (in a backwards compatible manner) or are opt-in. For a complete breakdown of the changes, please refer to the [changelog](http://docs.meteor.com/changelog.html).
+
+The above being said, there is a major breaking change that you should note.
+
+
Discontinuation of 32-bit Unix versions
+
+Because Node.js 12 no longer supports 32-bit Linux, Meteor 1.9 has also
+dropped support for 32-bit Linux. In other words, Meteor 1.9 supports
+64-bit Mac, Windows, and Linux, as well as 32-bit Windows.
+
+
Migrating from a version older than 1.8.3?
+
+If you're migrating from a version of Meteor older than Meteor 1.8.3, there may be important considerations not listed in this guide (which specifically covers 1.8.3 to 1.9). Please review the older migration guides for details:
+
+* [Migrating to Meteor 1.8.3](1.8.3-migration.html) (from 1.8.2)
+* [Migrating to Meteor 1.8.2](1.8.2-migration.html) (from 1.8)
+* [Migrating to Meteor 1.8](1.8-migration.html) (from 1.7)
+* [Migrating to Meteor 1.7](1.7-migration.html) (from 1.6)
+* [Migrating to Meteor 1.6](1.6-migration.html) (from 1.5)
+* [Migrating to Meteor 1.5](1.5-migration.html) (from 1.4)
+* [Migrating to Meteor 1.4](1.4-migration.html) (from 1.3)
+* [Migrating to Meteor 1.3](1.3-migration.html) (from 1.2)
diff --git a/guide/content/1.9.3-migration.md b/guide/content/1.9.3-migration.md
new file mode 100644
index 0000000000..16506760a4
--- /dev/null
+++ b/guide/content/1.9.3-migration.md
@@ -0,0 +1,26 @@
+---
+title: Migrating to Meteor 1.9.3
+description: How to migrate your application to Meteor 1.9.3.
+---
+
+Most of the new features in Meteor 1.9.3 are either applied directly behind the scenes (in a backwards compatible manner) or are opt-in. For a complete breakdown of the changes, please refer to the [changelog](http://docs.meteor.com/changelog.html).
+
+The above being said, there is a fix to an error that you might get to note.
+
+
MongoError unsupported retryable writes
+
+If you get the error `MongoError: This MongoDB deployment does not support retryable writes. Please add retryWrites=false to your connection string.`, append `retryWrites=false` to your MongoDB connection string.
+
+
Migrating from a version older than 1.9?
+
+If you're migrating from a version of Meteor older than Meteor 1.9, there may be important considerations not listed in this guide (which specifically covers 1.9 to 1.9.3). Please review the older migration guides for details:
+
+* [Migrating to Meteor 1.8.2](1.9-migration.html) (from 1.8.3)
+* [Migrating to Meteor 1.8.3](1.8.3-migration.html) (from 1.8.2)
+* [Migrating to Meteor 1.8.2](1.8.2-migration.html) (from 1.8)
+* [Migrating to Meteor 1.8](1.8-migration.html) (from 1.7)
+* [Migrating to Meteor 1.7](1.7-migration.html) (from 1.6)
+* [Migrating to Meteor 1.6](1.6-migration.html) (from 1.5)
+* [Migrating to Meteor 1.5](1.5-migration.html) (from 1.4)
+* [Migrating to Meteor 1.4](1.4-migration.html) (from 1.3)
+* [Migrating to Meteor 1.3](1.3-migration.html) (from 1.2)
diff --git a/guide/content/2.0-migration.md b/guide/content/2.0-migration.md
new file mode 100644
index 0000000000..d21ff3a8bf
--- /dev/null
+++ b/guide/content/2.0-migration.md
@@ -0,0 +1,37 @@
+---
+title: Migrating to Meteor 2.0
+description: How to migrate your application to Meteor 2.0.
+---
+
+Most of the new features in Meteor 2.0 are either applied directly behind the scenes (in a backwards compatible manner) or are opt-in. For a complete breakdown of the changes, please refer to the [changelog](http://docs.meteor.com/changelog.html).
+
+The above being said, there is a thing to note.
+
+
Hot Module Replacement
+
+Updates the javascript modules in a running app that were modified during a rebuild. Reduces the feedback cycle while developing so you can view and test changes quicker (it even updates the app before the build has finished). Enabled by adding the `hot-module-replacement` package to an app. React components are automatically updated by default using React Fast Refresh. Integrations with other libraries and view layers can be provided by third party packages. Support for Blaze is coming soon. This first version supports app code in the modern web architecture. ([docs](https://guide.meteor.com/build-tool.html#hot-module-replacement)) [#11117](https://github.com/meteor/meteor/pull/11117)
+
+
Free tier for Meteor Cloud is back
+
+Free deploy on [Cloud](https://www.meteor.com/cloud): Deploy for free to Cloud with one command: `meteor deploy myapp.meteorapp.com --free`. ([docs](https://docs.meteor.com/commandline.html#meteordeploy))
+
+Deploy including MongoDB on [Cloud](https://www.meteor.com/cloud): Deploy including MongoDB in a shared instance for free to Cloud with one command: `meteor deploy myapp.meteorapp.com --free --mongo`. ([docs](https://docs.meteor.com/commandline.html#meteordeploy))
+
+
Migrating from a version older than 1.12?
+
+If you're migrating from a version of Meteor older than Meteor 1.12, there may be important considerations not listed in this guide (which specifically covers 1.12 to 2.0). Please review the older migration guides for details:
+
+* [Migrating to Meteor 1.12](1.12-migration.html) (from 1.11)
+* [Migrating to Meteor 1.11](1.11-migration.html) (from 1.10.2)
+* [Migrating to Meteor 1.10.2](1.10.2-migration.html) (from 1.10)
+* [Migrating to Meteor 1.10](1.10-migration.html) (from 1.9.3)
+* [Migrating to Meteor 1.9.3](1.9.3-migration.html) (from 1.9)
+* [Migrating to Meteor 1.9](1.9-migration.html) (from 1.8.3)
+* [Migrating to Meteor 1.8.3](1.8.3-migration.html) (from 1.8.2)
+* [Migrating to Meteor 1.8.2](1.8.2-migration.html) (from 1.8)
+* [Migrating to Meteor 1.8](1.8-migration.html) (from 1.7)
+* [Migrating to Meteor 1.7](1.7-migration.html) (from 1.6)
+* [Migrating to Meteor 1.6](1.6-migration.html) (from 1.5)
+* [Migrating to Meteor 1.5](1.5-migration.html) (from 1.4)
+* [Migrating to Meteor 1.4](1.4-migration.html) (from 1.3)
+* [Migrating to Meteor 1.3](1.3-migration.html) (from 1.2)
diff --git a/guide/content/2.2-migration.md b/guide/content/2.2-migration.md
new file mode 100644
index 0000000000..0eecbb73fa
--- /dev/null
+++ b/guide/content/2.2-migration.md
@@ -0,0 +1,44 @@
+---
+title: Migrating to Meteor 2.2
+description: How to migrate your application to Meteor 2.2.
+---
+
+Most of the new features in Meteor 2.2 are either applied directly behind the scenes (in a backwards compatible manner) or are opt-in. For a complete breakdown of the changes, please refer to the [changelog](http://docs.meteor.com/changelog.html).
+
+The above being said, there are a few breaking changes that you might need to apply migration for.
+
+
Running MongoDB on Windows
+
+`meteor-tool` has been updated and you might need to install the new Visual C++ Redistributable for Visual Studio 2019 to run MongoDB 4.4.4 on Windows. [read more](https://docs.meteor.com/windows.html)
+
+
MongoDB `useUnifiedTopology`
+
+`mongo` package is now using `useUnifiedTopology` as `true` by default otherwise the new driver was producing a warning (see details below). It's important to test your app with this change.
+
+
Cordova 10
+
+`cordova` plugins and main libraries were updated from 9 to 10. It's important to test your app with these changes.
+
+
Typescript 4.2.2
+
+`typescript` was updated to 4.2.2, make sure your read the [breaking changes](https://devblogs.microsoft.com/typescript/announcing-typescript-4-2/#breaking-changes).
+
+
Migrating from a version older than 2.0?
+
+If you're migrating from a version of Meteor older than Meteor 2.0, there may be important considerations not listed in this guide (which specifically covers 2.0 to 2.2). Please review the older migration guides for details:
+
+* [Migrating to Meteor 2.0](2.0-migration.html) (from 1.12)
+* [Migrating to Meteor 1.12](1.12-migration.html) (from 1.11)
+* [Migrating to Meteor 1.11](1.11-migration.html) (from 1.10.2)
+* [Migrating to Meteor 1.10.2](1.10.2-migration.html) (from 1.10)
+* [Migrating to Meteor 1.10](1.10-migration.html) (from 1.9.3)
+* [Migrating to Meteor 1.9.3](1.9.3-migration.html) (from 1.9)
+* [Migrating to Meteor 1.9](1.9-migration.html) (from 1.8.3)
+* [Migrating to Meteor 1.8.3](1.8.3-migration.html) (from 1.8.2)
+* [Migrating to Meteor 1.8.2](1.8.2-migration.html) (from 1.8)
+* [Migrating to Meteor 1.8](1.8-migration.html) (from 1.7)
+* [Migrating to Meteor 1.7](1.7-migration.html) (from 1.6)
+* [Migrating to Meteor 1.6](1.6-migration.html) (from 1.5)
+* [Migrating to Meteor 1.5](1.5-migration.html) (from 1.4)
+* [Migrating to Meteor 1.4](1.4-migration.html) (from 1.3)
+* [Migrating to Meteor 1.3](1.3-migration.html) (from 1.2)
diff --git a/guide/content/2.3-migration.md b/guide/content/2.3-migration.md
new file mode 100644
index 0000000000..962beb5216
--- /dev/null
+++ b/guide/content/2.3-migration.md
@@ -0,0 +1,91 @@
+---
+title: Migrating to Meteor 2.3
+description: How to migrate your application to Meteor 2.3.
+---
+
+Most of the new features in Meteor 2.3 are either applied directly behind the scenes (in a backwards compatible manner) or are opt-in. For a complete breakdown of the changes, please refer to the [changelog](http://docs.meteor.com/changelog.html).
+
+The above being said, there are a few breaking changes that you might need to apply migration for.
+
+
Node.js v14
+
+As Node.js version was upgraded to a new major version we recommend that you review if your npm dependencies are compatible with Node.js 14.
+
+- If we receive reports from breaking changes we are going to list them here but so far we are not aware of any.
+- We recommend that you read Node.js [release notes](https://nodejs.org/en/blog/release/v14.0.0/) though.
+- We recommend that you remove your `node_modules` folder (`rm -rf node_modules`) and run `meteor npm i` to be sure you compile all the binary dependencies again using the new Node.js version.
+- Maybe you also want to recreate your lock file.
+- If you get an error try `meteor reset` which will clear caches, beware that this will also remove your local DB for your app.
+
+
`deprecated` option for packages
+
+In `Package.description`, there is a new `deprecated` option. If set to `true` it will inform user when installing that the package has been deprecated. Additionally you can provide a string that will be displayed, where you can direct the users where to go next.
+
+All official packages that have been deprecated have now the deprecated flag and will inform you about that if you install or update them.
+
+
Removal of deprecated package API
+
+Old API for packages definitions has been removed. The old underscore method names (`Package.on_use`, `Package.on_test`, `Package._transitional_registerBuildPlugin` and `api.add_files`) have been removed and will no longer work, please use the camel case method names (e.g. `api.addFiles()`).
+
+
Accounts 2.0
+
+* `accounts-base@2.0.0`
+ - Deprecated backward compatibility function `logoutOtherClients` has been removed.
+
+* `accounts-password@2.0.0`
+ - Deprecated backward compatibility functionality for `SRP` passwords from pre-Meteor 1.0 days has been removed.
+ - Enroll account workflow has been separated from reset password workflow (the enrollment token records are now stored in a separate db field `services.password.enroll`).
+
+* `oauth@2.0.0`
+ - Removed deprecated `OAuth.initiateLogin` and other functionality like the addition of `?close` in return URI for deprecated OAuth flow pre Meteor 1.0
+
+If you are maintaining a package that depends on one of the accounts packages which had a major version bump you will either need to set the new version manually or set `api.versionsFrom('2.3')`.
+You can also have it reference its current version and 2.3 like this: `api.versionsFrom(['1.12', '2.3'])`, for specific package it can be like this: `api.use('accounts-base@1.0.1 || 2.0.0')`.
+
+
HTTP v2
+
+Internally `http` package has replaced the use of http for [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API), should still work as previous version, but edge cases might be different. This is to aid you in transition to fetch. Note that this means that the `npmRequestOptions` parameter to `HTTP.call` has been removed, as `request` is no longer used internally. You should migrate to the use of `fetch`. You can install polyfill package via:
+
+```sh
+meteor add fetch
+```
+
+
Removal of deprecated APIs
+
+In addition to the above mentioned removal of deprecated package API, other long deprecated APIs have been removed and will no longer work.
+
+* Removed deprecated `mobile-port` flag
+* Removed deprecated `raw` name from `isobuild`
+* `ddp-client@2.5.0`
+ - Removed deprecated backward compatibility method names for Meteor before 1.0
+* `ddp-server@2.4.0`
+ - Removed deprecated backward compatibility method names for Meteor before 1.0
+* `meteor-base@1.5.0`
+ - Removed `livedata` dependency which was there for packages build for 0.9.0
+* `minimongo@1.7.0`
+ - Removed the `rewind` method that was noop for compatibility with Meteor 0.8.1
+* `mongo@1.12.0`
+ - Removed the `rewind` method that was noop for compatibility with Meteor 0.8.1
+* `socket-stream-client@0.4.0`
+ - Remove IE8 checks
+
+
Migrating from a version older than 2.2?
+
+If you're migrating from a version of Meteor older than Meteor 2.2, there may be important considerations not listed in this guide (which specifically covers 2.2 to 2.3). Please review the older migration guides for details:
+
+* [Migrating to Meteor 2.2](2.2-migration.html) (from 2.0)
+* [Migrating to Meteor 2.0](2.0-migration.html) (from 1.12)
+* [Migrating to Meteor 1.12](1.12-migration.html) (from 1.11)
+* [Migrating to Meteor 1.11](1.11-migration.html) (from 1.10.2)
+* [Migrating to Meteor 1.10.2](1.10.2-migration.html) (from 1.10)
+* [Migrating to Meteor 1.10](1.10-migration.html) (from 1.9.3)
+* [Migrating to Meteor 1.9.3](1.9.3-migration.html) (from 1.9)
+* [Migrating to Meteor 1.9](1.9-migration.html) (from 1.8.3)
+* [Migrating to Meteor 1.8.3](1.8.3-migration.html) (from 1.8.2)
+* [Migrating to Meteor 1.8.2](1.8.2-migration.html) (from 1.8)
+* [Migrating to Meteor 1.8](1.8-migration.html) (from 1.7)
+* [Migrating to Meteor 1.7](1.7-migration.html) (from 1.6)
+* [Migrating to Meteor 1.6](1.6-migration.html) (from 1.5)
+* [Migrating to Meteor 1.5](1.5-migration.html) (from 1.4)
+* [Migrating to Meteor 1.4](1.4-migration.html) (from 1.3)
+* [Migrating to Meteor 1.3](1.3-migration.html) (from 1.2)
diff --git a/guide/content/2.4-migration.md b/guide/content/2.4-migration.md
new file mode 100644
index 0000000000..3c3fbd3071
--- /dev/null
+++ b/guide/content/2.4-migration.md
@@ -0,0 +1,49 @@
+---
+title: Migrating to Meteor 2.4
+description: How to migrate your application to Meteor 2.4.
+---
+
+Most of the new features in Meteor 2.4 are either applied directly behind the scenes (in a backwards compatible manner) or are opt-in. For a complete breakdown of the changes, please refer to the [changelog](http://docs.meteor.com/changelog.html).
+
+The above being said, there are a few items that you should implement to have easier time in the future.
+
+
createIndex
+
+Previously undocumented `_ensureIndex` has been aligned with MongoDB breaking change in naming and is now usable as `createIndex`. Use of `_ensureIndex` is now deprecated and will throw a warning in development for you.
+
+
Email 2.2
+
+The `email` package had a feature update. You can now override the sending functionality completely with `Email.customTransport` or if you are using [known services](https://nodemailer.com/smtp/well-known/) you can now ditch the `MAIL_URL` environment variable and set it in your `settings.json` file, like so:
+```json
+{
+ "packages": {
+ "email": {
+ "service": "Mailgun",
+ "user": "postmaster@meteor.com",
+ "password": "superDuperPassword"
+ }
+ }
+}
+```
+
+
Migrating from a version older than 2.3?
+
+If you're migrating from a version of Meteor older than Meteor 2.3, there may be important considerations not listed in this guide (which specifically covers 2.2 to 2.3). Please review the older migration guides for details:
+
+* [Migrating to Meteor 2.3](2.3-migration.html) (from 2.2)
+* [Migrating to Meteor 2.2](2.2-migration.html) (from 2.0)
+* [Migrating to Meteor 2.0](2.0-migration.html) (from 1.12)
+* [Migrating to Meteor 1.12](1.12-migration.html) (from 1.11)
+* [Migrating to Meteor 1.11](1.11-migration.html) (from 1.10.2)
+* [Migrating to Meteor 1.10.2](1.10.2-migration.html) (from 1.10)
+* [Migrating to Meteor 1.10](1.10-migration.html) (from 1.9.3)
+* [Migrating to Meteor 1.9.3](1.9.3-migration.html) (from 1.9)
+* [Migrating to Meteor 1.9](1.9-migration.html) (from 1.8.3)
+* [Migrating to Meteor 1.8.3](1.8.3-migration.html) (from 1.8.2)
+* [Migrating to Meteor 1.8.2](1.8.2-migration.html) (from 1.8)
+* [Migrating to Meteor 1.8](1.8-migration.html) (from 1.7)
+* [Migrating to Meteor 1.7](1.7-migration.html) (from 1.6)
+* [Migrating to Meteor 1.6](1.6-migration.html) (from 1.5)
+* [Migrating to Meteor 1.5](1.5-migration.html) (from 1.4)
+* [Migrating to Meteor 1.4](1.4-migration.html) (from 1.3)
+* [Migrating to Meteor 1.3](1.3-migration.html) (from 1.2)
diff --git a/guide/content/CHANGELOG.md b/guide/content/CHANGELOG.md
new file mode 120000
index 0000000000..04c99a55ca
--- /dev/null
+++ b/guide/content/CHANGELOG.md
@@ -0,0 +1 @@
+../CHANGELOG.md
\ No newline at end of file
diff --git a/guide/content/CONTRIBUTING.md b/guide/content/CONTRIBUTING.md
new file mode 120000
index 0000000000..44fcc63439
--- /dev/null
+++ b/guide/content/CONTRIBUTING.md
@@ -0,0 +1 @@
+../CONTRIBUTING.md
\ No newline at end of file
diff --git a/guide/content/accounts.md b/guide/content/accounts.md
new file mode 100644
index 0000000000..7b7c5dd41e
--- /dev/null
+++ b/guide/content/accounts.md
@@ -0,0 +1,766 @@
+---
+title: Users and Accounts
+description: How to build user login functionality into a Meteor app. Let your users log in with passwords, Facebook, Google, GitHub, and more.
+discourseTopicId: 19664
+---
+
+After reading this article, you'll know:
+
+1. What features in core Meteor enable user accounts
+1. How to use accounts-ui for a quick prototype
+1. How to use the useraccounts family of packages to build your login UI
+1. How to build a fully-featured password login experience
+1. How to enable login through OAuth providers like Facebook
+1. How to add custom data to Meteor's users collection
+1. 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 `accounts-base` 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](data-loading.html) and [Methods](methods.html) 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`](http://docs.meteor.com/#/full/meteor_users), and the client-side singletons [`Meteor.userId()`](http://docs.meteor.com/#/full/meteor_userid) and [`Meteor.user()`](http://docs.meteor.com/#/full/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](http://docs.meteor.com/#/full/accounts_api) to find a complete list.
+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 in a blog post](https://dev.to/storytellercz/extending-meteor-accounts-login-system-5h5g).
+
+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 drop in quickly. This is where `accounts-ui` comes in - it's one line that you drop into your app to get an accounts system. To add it:
+
+```js
+meteor add accounts-ui
+```
+
+Then include it anywhere in a Blaze template:
+
+```html
+{{> loginButtons}}
+```
+
+Then, make sure to pick a login provider; they will automatically integrate with `accounts-ui`:
+
+```sh
+# 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 open your app, follow the configuration steps, and you're good to go - if you've done one of our [Meteor tutorials](https://www.meteor.com/developers/tutorials), 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:
+
+
+
+
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](https://github.com/meteor-useraccounts/core/blob/master/Guide.md) 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`](https://atmospherejs.com/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`](https://atmospherejs.com/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.
+- Pre-built templates for [Bootstrap, Semantic UI, Materialize, and more](https://github.com/meteor-useraccounts/core/blob/master/Guide.md#available-versions). 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](https://atmospherejs.com/useraccounts/flow-routing), the router [recommended in this guide](routing.html).
+- [Iron Router](https://atmospherejs.com/useraccounts/iron-routing), 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 drop in a self-managing accounts screen. Wherever you want the accounts UI template to render, include the `atForm` template, like so:
+
+```html
+{{> atForm}}
+```
+
+Once you configure routing according to [the section below](#useraccounts-customizing-routes), 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 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](https://github.com/meteor-useraccounts/unstyled/tree/master/lib). 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:
+
+```html
+
+
+
+```
+
+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:
+
+```html
+
+
+
+```
+
+Then, use the `replaces` function on the template to override the existing template from `useraccounts`:
+
+```js
+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:
+
+```js
+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:
+
+```js
+// 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.](#email-flows)
+
+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 [`ostrio:flow-router-extra`](https://atmospherejs.com/ostrio/flow-router-extra/) package provides a `pathFor` helper for just this purpose. Once installed, the following is possible in a template:
+
+```html
+
+```
+
+You can find a complete list of different available routes in the [documentation the `useraccounts:flow-routing`](https://github.com/meteor-useraccounts/flow-routing#routes).
+
+
Further customization
+
+`useraccounts` offers many other customization options beyond templates and routing. Read the [`useraccounts` guide](https://github.com/meteor-useraccounts/core/blob/master/Guide.md) to learn about all of the other options.
+
+
Password login
+
+Meteor comes with a secure and fully-featured password login system out of the box. To use it, add the package:
+
+```sh
+meteor add accounts-password
+```
+
+To see what options are available to you, read the complete description of the [`accounts-password` API in the Meteor docs](http://docs.meteor.com/#/full/accounts_passwords).
+
+
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:
+
+```js
+// 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](http://docs.meteor.com/api/passwords.html#Accounts-addEmail), [removing](http://docs.meteor.com/api/passwords.html#Accounts-removeEmail), and [verifying](http://docs.meteor.com/api/passwords.html#Accounts-verifyEmail) 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.
+
+
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 `AdaLovelace@example.com`, and then tried to log in with `adalovelace@example.com`, 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?
+
+Follow one rule: don't query the database by `username` or `email` directly. Instead, use the [`Accounts.findUserByUsername`](http://docs.meteor.com/api/passwords.html#Accounts-findUserByUsername) and [`Accounts.findUserByEmail`](http://docs.meteor.com/api/passwords.html#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 `accounts-password` 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.
+1. **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.
+1. **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 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.
+
+
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`](http://docs.meteor.com/#/full/accounts_sendresetpasswordemail)
+2. [`Accounts.sendEnrollmentEmail`](http://docs.meteor.com/#/full/accounts_sendenrollmentemail)
+3. [`Accounts.sendVerificationEmail`](http://docs.meteor.com/#/full/accounts_sendverificationemail)
+
+The email is generated using the email templates from [Accounts.emailTemplates](http://docs.meteor.com/#/full/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`](http://docs.meteor.com/#/full/Accounts-onResetPasswordLink)
+2. [`Accounts.onEnrollmentLink`](http://docs.meteor.com/#/full/Accounts-onEnrollmentLink)
+3. [`Accounts.onEmailVerificationLink`](http://docs.meteor.com/#/full/Accounts-onEmailVerificationLink)
+
+Here's how you would use one of these functions:
+
+```js
+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:
+
+```js
+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`](http://docs.meteor.com/#/full/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`](http://docs.meteor.com/#/full/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
+
+You will probably want to customize the emails `accounts-password` will send on your behalf. This can be done through the [`Accounts.emailTemplates` API](http://docs.meteor.com/#/full/accounts_emailtemplates). Below is some example code from the Todos app:
+
+```js
+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](https://github.com/leemunroe/responsive-html-email-template) or [framework](https://get.foundation/emails), 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.](http://blog.mailgun.com/transactional-html-email-templates/) 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
+
+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](https://en.wikipedia.org/wiki/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`](http://docs.meteor.com/#/full/meteor_loginwithexternalservice) function. It looks like this:
+
+```js
+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](security.html#api-keys-oauth).
+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 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](https://developers.facebook.com/docs/facebook-login/permissions). 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`](http://docs.meteor.com/#/full/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](#oauth-configuration) 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:
+
+```js
+// 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](http://docs.meteor.com/#/full/http) 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](https://www.npmjs.com/package/fbgraph) npm package. Read more about how to use npm with your app in the [Build System article](build-tool.html#npm).
+
+
Loading and displaying user data
+
+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](ui-ux.html#global-stores).
+
+
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.
+
+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.
+
+```js
+// 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
+ });
+});
+```
+
+```js
+// 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`:
+
+```js
+{
+ "_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": "ada@lovelace.com",
+ "verified": false
+ }
+ ]
+}
+```
+
+Here's what the same user would look like if they instead logged in with Facebook:
+
+```js
+{
+ "_id": "Ap85ac4r6Xe3paeAh",
+ "createdAt": "2015-12-10T22:29:46.854Z",
+ "services": {
+ "facebook": {
+ "accessToken": "XXX",
+ "expiresAt": 1454970581716,
+ "id": "XXX",
+ "email": "ada@lovelace.com",
+ "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](#publish-custom-data), 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](#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 about the [`profile` field on users](#dont-use-profile).
+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](#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 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:
+
+```js
+// 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 system](http://docs.meteor.com/api/accounts.html#Meteor-users).
+
+
Adding fields on user registration
+
+The code above is 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`](http://docs.meteor.com/#/full/accounts_oncreateuser):
+
+```js
+// 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();
+
+ // We still want the default hook's 'profile' behavior.
+ if (options.profile) {
+ user.profile = options.profile;
+ }
+
+ // 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:
+
+```js
+// 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 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 ignore its existence entirely. You can safely do that as long as you deny all writes from the client:
+
+```js
+// 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](collections.html#schema-design), 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 follow the advice in the [Data Loading](data-loading.html#publications) and [Security](security.html#publications) 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](http://guide.meteor.com/security.html#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 added one custom field, you should write a publication with that one field. Let's look at an example of how we might publish the `initials` field from above:
+
+```js
+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);
+});
+```
+
+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.
+
+
Preventing unnecessary data retrieval
+
+Take care storing lots of custom data on the user document, particularly data which grows indefinitely, because by default the entire user document is fetched from the database whenever a user tries to log in or out. Plus any calls to (e.g.) `Meteor.user().profile.name` on the server will fetch the entire user document from the database even though may you only need their name. If you have stored lots of custom data on the user documents this could significantly waste server resources (RAM and CPU).
+
+On the client, creating a reactive property based on (e.g.) `Meteor.user().profile.name` will cause any dependent DOM to update whenever **any** user data changes, not just their name, because the entire user document is being fetched from minimongo and becomes a reactive dependency for that property.
+
+Meteor 1.10 introduced a solution to these problems. A new `options` parameter was added to some methods which retrieves a user document. This parameter can include a [mongo field specifier](https://docs.meteor.com/api/collections.html#fieldspecifiers) to include or omit specific fields from the query. The methods which have this new parameter, and some examples of their usage are:
+
+```js
+// fetch only the user's name from the database:
+const name = Meteor.user({fields: {"profile.name": 1}}).profile.name;
+
+// check if an email exists without fetching their entire document from the database:
+const userExists = !!Accounts.findUserByEmail(email, {fields: {_id: 1}});
+
+// get the user id from a userName:
+const userId = Accounts.findUserByUsername(userName, {fields: {_id: 1}})?._id;
+```
+
+However, you may not have control over 3rd party package code or Meteor-core code which makes use of these functions. Nor does Meteor know which user fields are needed by callbacks registered with `Accounts.onLogin()`, `Accounts.onLogout()`, `Accounts.onLoginFailure()` and `Accounts.validateLoginAttempt()`. To solve this problem Meteor 1.10 also introduced a new [`Accounts.config({defaultFieldSelector: {...})`](https://docs.meteor.com/api/accounts-multi.html#AccountsCommon-config) option to include or omit specific user fields by default.
+
+You could use this to include (white-list) the standard fields as used by [the Accounts system](http://docs.meteor.com/api/accounts.html#Meteor-users):
+
+```js
+Accounts.config({
+ defaultFieldSelector: {
+ username: 1,
+ emails: 1
+ createdAt: 1,
+ profile: 1,
+ services: 1
+ }
+});
+```
+However, this may introduce bugs into any 3rd party or your own callbacks which expect non-standard fields to be present. Alternatively you could omit (black-list) any of your own fields which include large amounts of data, e.g.:
+```js
+Accounts.config({ defaultFieldSelector: { myBigArray: 0 }})
+```
+
+To ensure backwards compatibility, if you don't define `defaultFieldSelector` then the entire user document will be fetched as with earlier versions of Meteor.
+
+If you define a `defaultFieldSelector`, then you can override it by passing an `options` parameter, e.g. `Meteor.user({fields: {myBigArray: 1}})`. If you want to fetch the entire user document you can use an empty field specifier: `Meteor.user({fields: {}})`.
+
+The `defaultFieldSelector` is not used within direct `Meteor.users` collection operations - e.g. `Meteor.users.findOne(Meteor.userId())` will still fetch the entire user document.
+
+
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`](https://atmospherejs.com/alanning/roles). For example, here is how you would make a user into an administrator, or a moderator:
+
+```js
+// 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:
+
+```js
+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](https://atmospherejs.com/alanning/roles).
+
+
Per-document permissions
+
+Sometimes, it doesn't make sense to abstract permissions into "groups" - you want documents to have owners and that's it. In this case, you can use a simpler strategy using collection helpers.
+
+```js
+Lists.helpers({
+ // ...
+ editableBy(userId) {
+ if (!this.userId) {
+ return false;
+ }
+
+ return this.userId === userId;
+ },
+ // ...
+});
+```
+
+Now, we can call this simple function to determine if a particular user is allowed to edit this list:
+
+```js
+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](collections.html#collection-helpers).
diff --git a/guide/content/angular.md b/guide/content/angular.md
new file mode 100644
index 0000000000..db2d299c8d
--- /dev/null
+++ b/guide/content/angular.md
@@ -0,0 +1,10 @@
+---
+title: Angular
+description: The correct place to find details about using Angular with Meteor
+---
+
+Angular is a frontend rendering library that is officially supported by Meteor.
+
+The best place to read about how to use Angular in Meteor is the [Angular-Meteor](http://www.angular-meteor.com) site.
+
+You can also check the [repository](https://github.com/urigo/angular-meteor/).
diff --git a/guide/content/apollo.md b/guide/content/apollo.md
new file mode 100644
index 0000000000..5bdbfde4c8
--- /dev/null
+++ b/guide/content/apollo.md
@@ -0,0 +1,111 @@
+---
+title: Apollo
+order: 15
+description: The Apollo data stack for Reactive GraphQL
+discourseTopicId: TODO
+---
+
+
Introduction
+
+Apollo is a GraphQL client/server for transporting data. While it doesn't yet have all the features that Meteor's pub/sub system has, it provides a way to get data from any database – not just MongoDB.
+
+- [Apollo docs](https://www.apollographql.com/docs/)
+
+You can get started with Apollo and Meteor by creating a new Meteor application with the Apollo skeleton:
+```shell
+meteor create apollo-app --apollo
+```
+
+
+
+Instead of calling `Meteor.subscribe`, you will use [queries](https://www.apollographql.com/docs/react/data/queries/) to get data.
+
+The main difference with subscriptions is that queries get called only once (by default) and don't get updated data like a subscription would. This is great for data that doesn't change often and where you don't need reactivity.
+
+
Changing data
+
+Instead of calling a Meteor method with `Meteor.call`, you use a function called [`mutate`](https://www.apollographql.com/docs/react/data/mutations/) to run a *mutator*, which is GraphQL's equivalent to a method.
+
+Mutators are only run on the server, but they can return an object which then can update the local cache without the need to call a query again.
+
+
Apollo Server
+
+[Apollo server docs](https://www.apollographql.com/docs/apollo-server/)
+
+
Getting data
+
+Instead of using `Meteor.publish` to define publications, you write [resolve functions](https://www.apollographql.com/docs/apollo-server/data/resolvers/) – called *resolvers* – that fetch different types of data in the query.
+
+
Changing data
+
+Instead of using `Meteor.methods` to define methods, you write [mutators](https://www.apollographql.com/docs/tutorial/mutation-resolvers/) – functions that *mutate* (change) data.
+
+These are part of the resolver functions under `Mutation` key.
+
+
GraphQL
+
+GraphQL is a query language for apps to get the data they want. Instead of the server deciding what's in a publication, the client uses GraphQL to say exactly which fields of which objects it wants.
+
+- [About GraphQL](https://graphql.org/)
+- [Intro to GraphQL](https://medium.com/apollo-stack/the-basics-of-graphql-in-5-links-9e1dc4cac055)
+- [GraphQL coming from REST](https://medium.com/apollo-stack/how-do-i-graphql-2fcabfc94a01#.pfdj5bxxj)
+
+
+
+Meteor publications are blocking by default, whereas multiple GraphQL queries are executed in parallel. Publications stream data to the client as it arrives, whereas all the resolvers in a GraphQL query have to return before the data is sent to the client. (Although GraphQL is discussing adding the ability to stream results to the client as they come in.)
+
+
Meteor specific
+
+Meteor has a specific Apollo package which includes user object into the context of a query.
+
+```shell
+meteor add apollo
+```
+
+On server you import `getUser` function and include it into the context option when setting up Apollo server:
+
+```javascript
+import { ApolloServer } from 'apollo-server-express';
+import { getUser } from 'meteor/apollo';
+import typeDefs from '/imports/apollo/schema.graphql';
+import { resolvers } from '/server/resolvers';
+
+const server = new ApolloServer({
+ typeDefs,
+ resolvers,
+ context: async ({ req }) => ({
+ user: await getUser(req.headers.authorization)
+ })
+});
+```
+
+This will make user data available (if user is logged in) as the option in the query:
+```javascript
+{
+ Query: {
+ userUniverses: async (obj, { hideOrgs }, { user }) => {
+ if (!user) return null
+ const selector = { userId: user._id, }
+ if (hideOrgs) selector.organizationId = { $exists: false }
+ return UniversesCollection.find(selector).fetch()
+ }
+ }
+}
+```
+
+There are many other community packages that provide additional features or makes the initial setup easier, here is an incomplete list of some of them:
+
+* [quave:graphql](https://atmospherejs.com/quave/graphql) - Utility package to create GraphQL setup in a standard way.
+* [cultofcoders:apollo](https://atmospherejs.com/cultofcoders/apollo) - Meteor & Apollo integration.
+* [cultofcoders:graphql-loader](https://atmospherejs.com/cultofcoders/graphql-loader) - Easily load your GraphQL schema in your Meteor app!
+* [cultofcoders:apollo-accounts](https://atmospherejs.com/cultofcoders/apollo-accounts) - Meteor accounts in GraphQL
+* [swydo:blaze-apollo](https://atmospherejs.com/swydo/blaze-apollo) - Blaze integration for the Apollo Client
+* [swydo:ddp-apollo](https://atmospherejs.com/swydo/ddp-apollo) - DDP link and server for Apollo.
diff --git a/guide/content/atmosphere-vs-npm.md b/guide/content/atmosphere-vs-npm.md
new file mode 100644
index 0000000000..c1a998163c
--- /dev/null
+++ b/guide/content/atmosphere-vs-npm.md
@@ -0,0 +1,31 @@
+---
+title: Atmosphere vs. npm
+discourseTopicId: 20193
+---
+
+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](https://www.npmjs.com) and [Atmosphere](https://atmospherejs.com). 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](build-tool.html) 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](using-atmosphere-packages.html#package-namespacing) and package global exports without having to explicitly use ES2015 `import`
+- Enforce exact version dependencies between packages using Meteor's [constraint resolver](writing-atmosphere-packages.html#version-constraints)
+- Include [build plugins](build-tool.html#compiles-with-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](build-tool.html), 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.
+
+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 possible to [use npm packages in Meteor applications](using-npm-packages.html#using-npm), and possible to [use npm packages within Atmosphere packages](writing-atmosphere-packages.html#npm-dependencies), 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.
diff --git a/guide/content/blaze.md b/guide/content/blaze.md
new file mode 100644
index 0000000000..7115edc4b2
--- /dev/null
+++ b/guide/content/blaze.md
@@ -0,0 +1,7 @@
+---
+title: Blaze
+description: How to use Blaze, Meteor's frontend rendering system, to build usable and maintainable user interfaces.
+discourseTopicId: 19666
+---
+
+This content has moved to the [Blaze Community Site](http://blazejs.org/guide/introduction.html).
diff --git a/guide/content/build-tool.md b/guide/content/build-tool.md
new file mode 100644
index 0000000000..e2beef2cb0
--- /dev/null
+++ b/guide/content/build-tool.md
@@ -0,0 +1,322 @@
+---
+title: Build System
+description: How to use Meteor's build system to compile your app.
+discourseTopicId: 19669
+---
+
+The Meteor build system is the actual command line tool that you get when you install Meteor. You run it by typing the `meteor` command in your terminal, possibly followed by a set of arguments. Read the [docs about the command line tool](https://docs.meteor.com/commandline.html) or type `meteor help` in your terminal to learn about all of the commands.
+
+
What does it do?
+
+The Meteor build tool is what compiles, runs, deploys, and publishes all of your Meteor apps and packages. It's Meteor's built-in solution to the problems also solved by tools like Grunt, Gulp, Webpack, Browserify, Nodemon, and many others, and uses many popular Node.js tools like Babel and UglifyJS internally to enable a seamless experience.
+
+
Reloads app on file change
+
+After executing the `meteor` command to start the build tool you should leave it running while further developing your app. The build tool automatically detects any relevant file changes using a file watching system and recompiles the necessary changes, restarting your client or server environment as needed. [Hot module replacement](#hot-module-replacement) can optionally be used so you can view and test your changes even quicker.
+
+
Compiles files with build plugins
+
+The main function of the Meteor build tool is to run "build plugins". These plugins define different parts of your app build process. Meteor puts heavy emphasis on reducing or removing build configuration files, so you won't see any large build process config files like you would in Gulp or Webpack. The Meteor build process is configured almost entirely through adding and removing packages to your app and putting files in specially named directories. For example, to get all of the newest stable ES2015 JavaScript features in your app, you add the [`ecmascript` package](http://docs.meteor.com/#/full/ecmascript). This package provides support for ES2015 modules, which gives you even more fine grained control over file load order using ES2015 `import` and `export`. As new Meteor releases add new features to this package you get them for free.
+
+
Controlling which files to build
+
+By default Meteor will build certain files as controlled by your application [file structure](structure.html#javascript-structure) and Meteor's [default file load order](structure.html#load-order) rules. However, you may override the default behavior using `.meteorignore` files, which cause the build system to ignore certain files and directories using the same pattern syntax as `.gitignore` files. These files may appear in any directory of your app or package, specifying rules for the directory tree below them. These `.meteorignore` files are also fully integrated with Meteor's file watching system, so they can be added, removed, or modified during development.
+
+
Combines and minifies code
+
+Another important feature of the Meteor build tool is that it automatically concatenates your application asset files, and in production minifies these bundles. This lets you add all of the comments and whitespace you want to your source code and split your code into as many files as necessary, all without worrying about app performance and load times. This is enabled by the [`standard-minifier-js`](https://atmospherejs.com/meteor/standard-minifiers-js) and [`standard-minifier-css`](https://atmospherejs.com/meteor/standard-minifiers-css) packages, which are included in all Meteor apps by default. If you need different minification behavior, you can replace these packages. See adding [PostCSS to your build process](#postcss) as an example.
+
+
Development vs. production
+
+Running an app in development is all about fast iteration time. All kinds of different parts of your app are handled differently and instrumented to enable better reloads and debugging. In production, the app is reduced to the necessary code and functions just like any standard Node.js app. Therefore, you shouldn't run your app in production by executing the `meteor run` command. Instead, follow the directions in [Deploying Meteor Applications](deployment.html#deploying). If you find an error in production that you suspect is related to minification, you can run the minified version of your app locally for testing with `meteor --production`.
+
+
JavaScript transpilation
+
+These days, the landscape of JavaScript tools and frameworks is constantly shifting, and the language itself is evolving just as rapidly. It's no longer reasonable to wait for web browsers to implement the language features you want to use. Most JavaScript development workflows rely on compiling code to work on the lowest common denominator of environments, while letting you use the newest features in development. Meteor has support for some of the most popular tools out of the box.
+
+
ES2015+ (recommended)
+
+The `ecmascript` package (which is installed into all new apps and packages by default, but can be removed), allows support for many ES2015 features. We recommend using it. You can read more about it in the [Code Style](code-style.html#ecmascript) article.
+
+
Babel
+
+Babeljs is a configurable transpiler, which allows you write code in the latest version of JavaScript even when your supported environments don't support certain features natively. Babel will compile those features down to a supported version.
+
+ Meteor provides a set appropriate core plugins for each environment (Node 8, modern browsers, and legacy browsers) and React to support most modern Javascript code practices. In addition, Meteor (as of 1.3.3) supports custom .babelrc files which allows developers to further customise their Babel configuration to suit there needs (e.g. Stage 0 proposals).
+
+ Developers are encouraged to avoid adding large presets (such as babel-preset-env & babel-preset-react) and adding specific plugins as needed (even though it seems to work). You will avoid unnecessary Babel compilation and you'll be less likely to experience plugin ordering issues.
+
+
CoffeeScript
+
+While we recommend using ES2015 with the `ecmascript` package as the best development experience for Meteor, everything in the platform is 100% compatible with [CoffeeScript](http://coffeescript.org/) and many people in the Meteor community prefer it.
+
+All you need to do to use CoffeeScript is add the right Meteor package:
+
+```sh
+meteor add coffeescript
+```
+
+All code written in CoffeeScript compiles to JavaScript under the hood, and is completely compatible with any code in other packages that is written in JS or ES2015.
+
+
TypeScript
+
+[TypeScript](https://www.typescriptlang.org/) is modern JavaScript with optional types and more.
+
+Adding types will make your code more readable and less prone to runtime errors.
+
+TypeScript can be installed with:
+
+```sh
+meteor add typescript
+```
+
+It is necessary to configure the TypeScript compiler with a `tsconfig.json` file. Here's the one generated by `meteor create --typescript`:
+
+```
+{
+ "compilerOptions": {
+ /* Basic Options */
+ "target": "es2018",
+ "module": "esNext",
+ "lib": ["esnext", "dom"],
+ "allowJs": true,
+ "checkJs": false,
+ "jsx": "preserve",
+ "incremental": true,
+ "noEmit": true,
+
+ /* Strict Type-Checking Options */
+ "strict": true,
+ "noImplicitAny": true,
+ "strictNullChecks": true,
+
+ /* Additional Checks */
+ "noUnusedLocals": true,
+ "noUnusedParameters": true,
+ "noImplicitReturns": false,
+ "noFallthroughCasesInSwitch": false,
+
+ /* Module Resolution Options */
+ "baseUrl": ".",
+ "paths": {
+ /* Support absolute /imports/* with a leading '/' */
+ "/*": ["*"]
+ },
+ "moduleResolution": "node",
+ "resolveJsonModule": true,
+ "types": ["node", "mocha"],
+ "esModuleInterop": true,
+ "preserveSymlinks": true
+ },
+ "exclude": [
+ "./.meteor/**",
+ "./packages/**"
+ ]
+}
+```
+
+If you want to add TypeScript from the point of project creation, as of Meteor 1.8.2, you can run the create command with the --typescript flag:
+
+```
+meteor create --typescript name-of-my-new-typescript-app
+```
+
+
Conditional imports
+
+TypeScript does not support nested `import` statements, therefore conditionally importing modules requires you to use the `require` statement (see [Using `require`](https://guide.meteor.com/structure.html#using-require)).
+
+To maintain type safety, you can take advantage of TypeScript's import elision and reference the types using the `typeof` keyword. See the [TypeScript handbook article](https://www.typescriptlang.org/docs/handbook/modules.html#optional-module-loading-and-other-advanced-loading-scenarios) for details or [this blog post](http://ideasintosoftware.com/typescript-conditional-imports/) for a concrete Meteor example.
+
+
Templates and HTML
+
+Since Meteor uses client-side rendering for your app's UI, all of your HTML code, UI components, and templates need to be compiled to JavaScript. There are a few options at your disposal to write your UI code.
+
+
Blaze HTML templates
+
+The aptly named `blaze-html-templates` package that comes with every new Meteor app by default compiles your `.html` files written using [Spacebars](http://blazejs.org/api/spacebars.html) into Blaze-compatible JavaScript code. You can also add `blaze-html-templates` to any of your packages to compile template files located in the package.
+
+[Read about how to use Blaze and Spacebars in the Blaze article.](http://blazejs.org/guide/spacebars.html)
+
+
Blaze Jade templates
+
+If you don't like the Spacebars syntax Meteor uses by default and want something more concise, you can give Jade a try by using [`pacreach:jade`](https://atmospherejs.com/pacreach/jade). This package will compile all files in your app with the `.jade` extension into Blaze-compatible code, and can be used side-by-side with `blaze-html-templates` if you want to have some of your code in Spacebars and some in Jade.
+
+
JSX for React
+
+If you're building your app's UI with React, currently the most popular way to write your UI components involves JSX, an extension to JavaScript that allows you to type HTML tags that are converted to React DOM elements. JSX code is handled automatically by the `ecmascript` package.
+
+
Other options for React
+
+If you want to use React but don't want to deal with JSX and prefer a more HTML-like syntax, there are a few community options available. One that stands out in particular is [Blaze-React](https://github.com/timbrandin/blaze-react), which simulates the entire Blaze API using React as a rendering engine.
+
+
CSS processing
+
+All your CSS style files will be processed using Meteor's default file load order rules along with any import statements and concatenated into a single stylesheet, `merged-stylesheets.css`. In a production build this file is also minified. By default this single stylesheet is injected at the beginning of the HTML `
` section of your application.
+
+However, this can potentially be an issue for some applications that use a third party UI framework, such as Bootstrap, which is loaded from a CDN. This could cause Bootstrap's CSS to come after your CSS and override your user-defined styles.
+
+To get around this problem Meteor supports the use of a pseudo tag `` that if placed anywhere in the `
` section your app will be replaced by a link to this concatenated CSS file. If this pseudo tag isn't used, the CSS file will be placed at the beginning of the section as before.
+
+
CSS pre-processors
+
+It's no secret that writing plain CSS can often be a hassle as there's no way to share common CSS code between different selectors or have a consistent color scheme between different elements. CSS compilers, or pre-processors, solve these issues by adding extra features on top of the CSS language like variables, mixins, math, and more, and in some cases also significantly change the syntax of CSS to be easier to read and write.
+
+Here are three example CSS pre-processors supported by Meteor:
+
+1. [Sass](http://sass-lang.com/)
+2. [Less.js](http://lesscss.org/)
+3. [Stylus](https://learnboost.github.io/stylus/)
+
+They all have their pros and cons, and different people have different preferences, just like with JavaScript transpiled languages. Sass with the SCSS syntax is quite popular as CSS frameworks like Bootstrap 4 have switched to Sass, and the C++ LibSass implementation appears to be faster than some of the other compilers available.
+
+CSS framework compatibility should be a primary concern when picking a pre-processor, because a framework written with Less won't be compatible with one written in Sass.
+
+
Source vs. import files
+
+An important feature shared by all of the available CSS pre-processors is the ability to import files. This lets you split your CSS into smaller pieces, and provides a lot of the same benefits that you get from JavaScript modules:
+
+1. You can control the load order of files by encoding dependencies through imports, since the load order of CSS matters.
+2. You can create reusable CSS "modules" that only have variables and mixins and don't actually generate any CSS.
+
+In Meteor, each of your `.scss`, `.less`, or `.styl` source files will be one of two types: "source" or "import".
+
+A "source" file is evaluated eagerly and adds its compiled form to the CSS of the app immediately.
+
+An "import" file is evaluated only if imported from some other file and can be used to share common mixins and variables between different CSS files in your app.
+
+Read the documentation for each package listed below to see how to indicate which files are source files vs. imports.
+
+
Importing styles
+
+In all three Meteor supported CSS pre-processors you can import other style files from both relative and absolute paths in your app and from both npm and Meteor Atmosphere packages.
+
+```less
+@import '../stylesheets/colors.less'; // a relative path
+@import '{}/imports/ui/stylesheets/button.less'; // absolute path with `{}` syntax
+```
+
+You can also import CSS from a JavaScript file if you have the `ecmascript` package installed:
+
+```js
+import '../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.
+
+Importing styles from an Atmosphere package using the `{}` package name syntax:
+
+```less
+@import '{my-package:pretty-buttons}/buttons/styles.import.less';
+```
+
+> CSS files in an Atmosphere package are declared with [`api.addFiles`](http://docs.meteor.com/#/full/pack_addFiles), and therefore will be eagerly evaluated, and automatically bundled with all the other CSS in your app.
+
+Importing styles from an npm package using the `{}` syntax:
+
+```less
+@import '{}/node_modules/npm-package-name/button.less';
+```
+```js
+import 'npm-package-name/stylesheets/styles.css';
+```
+
+For more examples and details on importing styles and using `@imports` with packages see the [Using Packages](using-packages.html#npm-styles) article.
+
+
Sass
+
+The best Sass build plugin for Meteor is [`fourseven:scss`](https://atmospherejs.com/fourseven/scss).
+
+
Less
+
+Less is maintained as a [Meteor core package called `less`](https://atmospherejs.com/meteor/less).
+
+
Stylus
+
+The best Stylus build plugin for Meteor is [coagmano:stylus](https://atmospherejs.com/coagmano/stylus)
+
+
PostCSS and Autoprefixer
+
+In addition to CSS pre-processors like Sass, Less, and Stylus, there is now an ecosystem of CSS post-processors. Regardless of which CSS pre-processor you use, a post-processor can give you additional benefits like cross-browser compatibility.
+
+The most popular CSS post-processor right now is [PostCSS](https://github.com/postcss/postcss), which supports a variety of plugins. [Autoprefixer](https://github.com/postcss/autoprefixer) is perhaps the most useful plugin, since it enables you to stop worrying about browser prefixes and compatibility and write standards-compliant CSS. No more copying 5 different statements every time you want a CSS gradient - you can write a standard gradient without any prefixes and Autoprefixer handles it for you.
+
+Currently, Meteor doesn't have a separate build step for post-processing CSS, so the only way to integrate it is to build it into the minifier. Thankfully, there is a community package that has integrated PostCSS with plugin support into a replacement for Meteor's standard minification package.
+
+
juliancwirko:postcss
+
+>Note: This package is no longer actively maintained, therefore compatibility with newer versions of Meteor is not guaranteed. If you encouter problems with this, please let us know by [opening an issue on the Guide](https://github.com/meteor/guide/issues).
+
+Use the package [juliancwirko:postcss](https://atmospherejs.com/juliancwirko/postcss) to your app to enable PostCSS for your Meteor app. To do so, we remove the standard CSS minifier and replace it with the postcss package:
+
+```
+meteor remove standard-minifier-css
+meteor add juliancwirko:postcss
+```
+
+As well as installing the postcss NPM package:
+
+```
+meteor npm install postcss@^6.0.22 --save-dev
+meteor npm install postcss-load-config@^1.2.0 --save-dev
+```
+
+Then we can install any npm CSS processing packages that we'd like to use and reference them from a `postcss` section of our `package.json`. In the Todos example app, we use `autoprefixer` package to increase browser support:
+
+```
+{
+ "devDependencies": {
+ "autoprefixer": "^6.3.1"
+ },
+ "postcss": {
+ "plugins": {
+ "autoprefixer": {"browsers": ["last 2 versions"]}
+ }
+ }
+}
+```
+
+After doing the above, you'll need to ensure you `npm install` and restart the `meteor` process running your app to make sure the PostCSS system has had a chance to set itself up.
+
+
Hot Module Replacement
+
+In Meteor apps, javascript, typescript, css files that are dynamically imported, and many other types of files are converted into javascript modules during the build process. Instead of reloading the client after a rebuild, Meteor is able to update the javascript modules within the running application that were modified. This reduces the feedback cycle while developing by allowing you to view and test your changes quicker.
+
+Hot module replacement (HMR) can be enabled by adding the [hot-module-replacement](https://docs.meteor.com/packages/hot-module-replacement.html) package to your app:
+
+```
+meteor add hot-module-replacement
+```
+
+Many types of javascript modules can not be updated with HMR, so HMR has to be configured to know which modules can be replaced and how to replace them. Most apps never need to do this manually. Instead, you can use integrations that configure HMR for you:
+
+- React components are automatically updated using [React Fast Refresh](https://atmospherejs.com/meteor/react-fast-refresh). This integration is enabled for all Meteor apps that use HMR and a supported react version.
+- An integration for Blaze templates is in [beta](https://github.com/meteor/blaze/pull/313).
+- Svelte files can be automatically updated with HMR by using the [zodern:melte](https://atmospherejs.com/zodern/melte) compiler package.
+- [akryum:vue-component](https://atmospherejs.com/akryum/vue-component) uses its own implementation of HMR to update vue components.
+- Some packages are able to help automatically dispose old versions of modules. For example, [zodern:pure-admin](https://atmospherejs.com/zodern/pure-admin) removes menu items and pages added in the old version of the module so you don't end up with duplicate or outdated items when the new version of the module is ran.
+
+To further control how HMR applies updates in your app, you can use the [hot API](https://docs.meteor.com/packages/hot-module-replacement.html). This can be used to accept updates for additional types of files, help dispose a module so the old version no longer affects the app (such as stopping Tracker.autorun computations), or creating your own integrations with other view layers or libraries.
+
+If a change was made to the app that can not be applied with HMR, it reloads the page with hot code push, as is done when HMR is not enabled. It currently only supports app code in the modern client architecture. Future versions of Meteor will add support for packages and other architectures.
+
+
Build plugins
+
+The most powerful feature of Meteor's build system is the ability to define custom build plugins. If you find yourself writing scripts that mangle one type of file into another, merge multiple files, or something else, it's likely that these scripts would be better implemented as a build plugin. The `ecmascript`, `templating`, and `coffeescript` packages are all implemented as build plugins, so you can replace them with your own versions if you want to!
+
+[Read the documentation about build plugins.](https://docs.meteor.com/api/packagejs.html#build-plugin-api)
+
+
Types of build plugins
+
+There are three types of build plugins supported by Meteor today:
+
+1. Compiler plugin - compiles source files (LESS, CoffeeScript) into built output (JS, CSS, asset files, and HTML). Only one compiler plugin can handle a single file extension.
+2. Minifier plugin - compiles lots of built CSS or JS files into one or more minified files, for example `standard-minifiers`. Only one minifier can handle each of `js` and `css`.
+3. Linter plugin - processes any number of files, and can print lint errors. Multiple linters can process the same files.
+
+
Writing your own build plugin
+
+Writing a build plugin is a very advanced task that only the most advanced Meteor users should get into. The best place to start is to copy a different plugin that is the most similar to what you are trying to do. For example, if you wanted to make a new CSS compiler plugin, you could fork the `less` package; if you wanted to make your own JS transpiler, you could fork `ecmascript`. A good example of a linter is the `jshint` package, and for a minifier you can look at `standard-minifiers-js` and `standard-minifiers-css`.
+
+
Caching
+
+The best way to make your build plugin fast is to use caching anywhere you can - the best way to save time is to do less work! Check out the [documentation about CachingCompiler](https://docs.meteor.com/api/packagejs.html#build-plugin-caching) to learn more. It's used in all of the above examples, so you can see how to use it by looking at them.
diff --git a/guide/content/code-style.md b/guide/content/code-style.md
new file mode 100644
index 0000000000..148000fbcd
--- /dev/null
+++ b/guide/content/code-style.md
@@ -0,0 +1,271 @@
+---
+title: Code Style
+description: Suggested style guidelines for your code.
+discourseTopicId: 20189
+---
+
+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.
+
+```js
+// This code is misleading because it looks like both statements
+// are inside the conditional.
+if (condition)
+ firstStatement();
+ secondStatement();
+```
+
+```js
+// 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 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.
+
+
+
+> 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](https://babeljs.io/). 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](https://docs.meteor.com/packages/ecmascript.html#Supported-ES2015-Features).
+
+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](http://info.meteor.com/blog/es2015-get-started)
+- [Set up Sublime Text for ES2015](http://info.meteor.com/blog/set-up-sublime-text-for-meteor-es6-es2015-and-jsx-syntax-and-linting)
+- [How much does ES2015 cost?](http://info.meteor.com/blog/how-much-does-es2015-cost)
+
+
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](https://github.com/airbnb/javascript) 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](https://github.com/airbnb/javascript/tree/master/packages/eslint-config-airbnb) 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 an automated way to identify typos and small errors.
+
+
Installing and running ESLint
+
+To setup ESLint in your application, you can install the following [npm](https://docs.npmjs.com/getting-started/what-is-npm) packages:
+
+```
+meteor npm install --save-dev babel-eslint eslint-config-airbnb eslint-plugin-import eslint-plugin-meteor eslint-plugin-react eslint-plugin-jsx-a11y eslint-import-resolver-meteor eslint @meteorjs/eslint-config-meteor
+```
+
+> 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](https://github.com/dferber90/eslint-plugin-meteor). You can also setup any extra rules you want to change, as well as adding a lint npm command:
+
+```
+{
+ ...
+ "scripts": {
+ "lint": "eslint .",
+ "pretest": "npm run lint --silent"
+ },
+ "eslintConfig": {
+ "extends": "@meteorjs/eslint-config-meteor"
+ }
+}
+```
+
+To run the linter, you can now type:
+
+```bash
+meteor npm run lint
+```
+
+For more details, read the [Getting Started](http://eslint.org/docs/user-guide/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 write well-formatted 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:
+
+* Babel (for syntax highlighting – [full instructions](https://github.com/babel/babel-sublime#installation))
+* SublimeLinter ([full instructions](http://sublimelinter.readthedocs.org/en/latest/installation.html))
+* SublimeLinter-contrib-eslint ([full instructions](https://github.com/roadhump/SublimeLinter-eslint#plugin-installation))
+
+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](https://github.com/babel/babel-sublime) 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](https://github.com/sergeche/emmet-sublime/issues/548).
+
+
Atom
+
+Install these three packages to use ESLint with Atom:
+
+```bash
+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](https://www.jetbrains.com/webstorm/help/eslint.html). After you install the ESLint Node packages and set up your `package.json`, 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.
+
+
+
+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](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-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 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](https://en.wikipedia.org/wiki/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.
+
+```js
+// Defining a collection
+Lists = new Mongo.Collection('lists');
+```
+
+Fields in the database should be camelCased just like your JavaScript variable names.
+
+```js
+// 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:
+
+```js
+// 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](methods.html#validated-method). 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:
+
+```js
+// 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 help you navigate to 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 is OK to make an exception, for example if you have a UI component with a small sub-component 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:
+
+```js
+export default class ClickCounter { ... }
+```
+
+This class should be defined inside a file called `ClickCounter.js`. When you import it, it'll look like this:
+
+```js
+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](using-packages.html), 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:
+
+```js
+// 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 type the name of the template as one symbol in JavaScript.
+
+```html
+
+ ...
+
+```
+
+If this template is a "smart" component that loads server data and accesses the router, append `_page` to the name:
+
+```html
+
+ ...
+
+```
+
+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](structure.html#javascript-structure).
+
+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.
diff --git a/guide/content/collections.md b/guide/content/collections.md
new file mode 100644
index 0000000000..f3aa7d0dad
--- /dev/null
+++ b/guide/content/collections.md
@@ -0,0 +1,526 @@
+---
+title: Collections and Schemas
+description: How to define, use, and maintain MongoDB collections in Meteor.
+discourseTopicId: 19660
+---
+
+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](http://docs.meteor.com/api/collections.html#Mongo-Collection), 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:
+
+```js
+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:
+
+```js
+// 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);
+```
+
+
Client-side collections
+
+On the client, when you write the same line:
+
+```js
+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](https://github.com/meteor/meteor/blob/master/packages/minimongo/README.md) library---an in-memory, all JS, implementation of the MongoDB API.
+
+```js
+// 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](data-loading.html). 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](methods.html).
+
+
Local collections
+
+There is a third way to use a collection in Meteor. On the client or server, if you create a collection in one of these two ways:
+
+```js
+SelectedTodos = new Mongo.Collection(null);
+SelectedTodos = new Mongo.Collection('selectedtodos', {connection: null});
+```
+
+This creates a *local collection*. This is a Minimongo collection that has no database connection (ordinarily a 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 in-memory 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* 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 the npm [simpl-schema](https://www.npmjs.com/package/simpl-schema) package. It's an expressive, MongoDB based schema that's used to insert and update documents. Another alternative is [jagi:astronomy](https://atmospherejs.com/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 `simpl-schema`, you can create a new instance of the `SimpleSchema` class and attach it to the `Lists` object:
+
+```js
+import SimpleSchema from 'simpl-schema';
+
+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:
+
+2. We specify that the `name` field of a list is required and must be a string.
+3. We specify the `incompleteCount` is a number, which on insertion is set to `0` if not otherwise specified.
+4. 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](methods.html). In the [next section](#schemas-on-write) 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](https://www.npmjs.com/package/simpl-schema).
+
+
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:
+
+```js
+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:
+
+```js
+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`](https://github.com/meteor/validation-error/)? It's a special error that is used in Meteor to indicate a user-input 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](methods.html#validation-error), 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.
+
+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 a 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:
+
+```js
+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`". It can only "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 sub-documents. 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](#abstracting-denormalizers) below.
+
+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`](https://atmospherejs.com/aldeed/collection2) package to run every mutator (`insert/update/upsert` call) through the schema.
+
+To do so, we use `attachSchema()`:
+
+```js
+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
+
+One thing that Collection2 does is ["clean" the data](https://www.npmjs.com/package/simpl-schema#cleaning-objects) 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:
+
+```js
+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't 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:
+
+```js
+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 use the mutator as a point to call out to that module in a sensible way. We'll see an example of that [below](#abstracting-denormalizers).
+
+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:
+
+```js
+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 been 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:
+
+```js
+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, 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 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`](https://atmospherejs.com/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`):
+
+```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});
+ }
+});
+```
+
+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](https://atmospherejs.com/percolate/migrations).
+
+
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](https://docs.mongodb.org/v3.0/core/bulk-write-operations/).
+
+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 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 service! 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()`](http://docs.meteor.com/api/collections.html#Mongo-Collection-rawCollection):
+
+```js
+Migrations.add({
+ version: 1,
+ up() {
+ // This is how to get access to the raw MongoDB node collection that the Meteor server 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 expects
+ 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](https://docs.mongodb.org/v3.4/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:
+
+```js
+// 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 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 make 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](#bulk-data-changes) 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
+```js
+// 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.
+
+
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 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.
+
+To make things even easier, we can use the [`cultofcoders:grapher`](https://atmospherejs.com/cultofcoders/grapher) package to associate collections and fetch their relations. For example:
+
+```js
+// Configure how collections relate to each other
+Todos.addLinks({
+ list: {
+ type: 'one',
+ field: 'listId',
+ collection: Lists
+ }
+});
+
+Lists.addLinks({
+ todos: {
+ collection: Todos,
+ inversedBy: 'list' // This represents the name of the link we defined in Todos
+ }
+});
+```
+
+This allows us to properly fetch a list along with its todos:
+
+```js
+// With Grapher you must always specify the fields you want
+const listsAndTodos = Lists.createQuery({
+ name: 1,
+ todos: {
+ text: 1
+ }
+}).fetch();
+```
+
+`listsAndTodos` will look like this:
+
+```
+[
+ {
+ name: 'My List',
+ todos: [
+ {text: 'Do something'}
+ ],
+ }
+]
+```
+
+Grapher supports isomorphic queries (reactive and non-reactive), has built-in security features, works with many types of relationships, and more. Refer to the [Grapher documentation](https://github.com/cult-of-coders/grapher/blob/master/docs/index.md) for more details.
+
+
Collection helpers
+
+We can use the [`dburles:collection-helpers`](https://atmospherejs.com/dburles/collection-helpers) package to easily attach such methods (or "helpers") to documents. For instance:
+
+```js
+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:
+
+```js
+const list = Lists.findOne();
+if (list.isPrivate()) {
+ console.log('The first list is private!');
+}
+```
+
+
Association helpers
+
+Now we can attach helpers to documents, we can define a helper that fetches related documents
+
+```js
+Lists.helpers({
+ todos() {
+ return Todos.find({listId: this._id}, {sort: {createdAt: -1}});
+ }
+});
+```
+
+Now we can find all the todos for a list:
+
+```js
+const list = Lists.findOne();
+console.log(`The first list has ${list.todos().count()} todos`);
+```
diff --git a/guide/content/cordova.md b/guide/content/cordova.md
new file mode 100644
index 0000000000..ae0dc45020
--- /dev/null
+++ b/guide/content/cordova.md
@@ -0,0 +1,676 @@
+---
+title: Cordova
+description: How to build mobile apps using Meteor's Cordova integration.
+discourseTopicId: 20195
+---
+
+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
+1. How to set up your local machine for mobile development
+1. How to run and debug your app on a mobile device or simulator/emulator
+1. 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
+1. How to use Cordova plugins to take advantage of native device features
+1. How to access local files and remote resources from your app
+1. What you can do to create a good mobile user experience for your app
+1. How to configure your app to use your own app icon, launch screen, and set other preferences
+1. How to build your project and submit your mobile app to the store
+
+
Meteor Cordova integration
+
+Meteor integrates with [Cordova](https://cordova.apache.org), 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 commands.
+
+A Cordova app is a web app written using HTML, CSS, and JavaScript as usual, but it runs in a [web view](#what-environment) 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](#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](#cordova-plugins). 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.
+
+>
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`](http://docs.meteor.com/api/mobile-config.html) 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](#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](https://www.chromium.org/Home/chromium-security/prefer-secure-origins-for-powerful-new-features) and won't block any sensitive features (which they increasingly do for `file://` URLs).
+
+The port mentioned above will be generated based on your app ID stored in the `.meteor/.id` file in your application. If you need to run multiple apps on the same device using the same source code, you should specify a different port for each running app, by using the `--cordova-server-port ` option when running the Cordova `run` and `build` commands. Otherwise you will not be able to run multiple apps simultaneously on iOS. One common symptom of this problem is the error `Failed binding IPv4 listening socket: Address already in use (48)` in the XCode console.
+
+>
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](http://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).
+
+> 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
+
+Android 5.0 and above come with a web view based on Chromium known as the [Android System Web View](https://play.google.com/store/apps/details?id=com.google.android.webview&hl=en), which can be automatically updated through the Play Store. This means updates to the web view can happen regularly and are independent of OS updates.
+
+
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.
+
+If your local machine does not (yet) fulfill the [prerequisites](#installing-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 [Apple Xcode](https://developer.apple.com/xcode/) developer tools installed. We recommend installing the latest version, but you should also check the [Meteor history](https://github.com/meteor/meteor/blob/devel/History.md) for any specific version dependencies. NOTE: To build with Xcode 10.2+, your webapp package must be v1.7.4 or higher.
+
+
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](https://www.apple.com/legal/sla/docs/xcode.pdf)).
+
+> As of [Cordova iOS 4.3.0](https://cordova.apache.org/announcements/2016/10/24/ios-release.html) you may also need to `sudo gem install cocoapods` to resolve a dependency with [PhoneGap Push Plugin](https://github.com/phonegap/phonegap-plugin-push/blob/master/docs/INSTALLATION.md).
+
+
Enabling Xcode command line tools
+
+After installing Xcode from the Mac App Store, it is still necesssary to enable those tools in the terminal environment. This can be accompilshed by running the following from the command prompt:
+```
+ sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
+```
+
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
+- If Gradle cannot be found: try using a package manager such as [Homebrew](https://brew.sh/), `apt-get`, or `yum` to install a system-wide, standalone version of `gradle`:
+ ```sh
+ # On Mac OSX:
+ brew install gradle
+
+ # On Debian/Ubuntu:
+ sudo apt-get install gradle
+ ```
+ More information about installing Gradle can be found [here](https://gradle.org/install/#install).
+
+
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](#ubuntu-make) to install Android Studio and all dependencies at the same time.
+
+1. Open the [Oracle Java website](http://www.oracle.com/technetwork/java/javase/downloads/index.html), and select the Java Platform (JDK)
+1. Check the box to accept the license agreement, and select the correct download for your platform
+1. 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](http://developer.android.com/sdk/index.html), 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](http://developer.android.com/sdk/installing/index.html?pkg=studio) 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](http://developer.android.com/sdk/index.html#Other) and download the required [additional packages](http://developer.android.com/sdk/installing/adding-packages.html) yourself using the [Android SDK Manager](http://developer.android.com/tools/help/sdk-manager.html).
+
+Make sure to select the correct version of the [Android Studio SDK Tools](https://developer.android.com/studio/releases/sdk-tools.html):
+
+ * Meteor 1.4.3.1 or later: Android SDK Tools v.25.**2**.x ([mac](https://dl.google.com/android/repository/tools_r25.2.3-macosx.zip), [linux](https://dl.google.com/android/repository/tools_r25.2.3-linux.zip), [windows](https://dl.google.com/android/repository/tools_r25.2.3-windows.zip)) or v.26.0.0 or later
+ * v.25.**3.0** **will not work** due to [extensive changes](https://developer.android.com/studio/releases/sdk-tools.html). See [issue #8464](https://github.com/meteor/meteor/issues/8464) for more information.
+ * Meteor 1.4.2.x or before: Android SDK Tools v.23 ([mac](https://dl.google.com/android/repository/tools_r23.0.1-macosx.zip), [linux](https://dl.google.com/android/repository/tools_r23.0.1-linux.zip), [windows](https://dl.google.com/android/repository/tools_r23.0.1-windows.zip))
+
+To install an older version of SDK tools:
+
+* Download the version that you need from the above links
+* Replace the `tools/` folder in `~/Library/Android/sdk/`
+
+> Note: If you're using older version of Meteor, you may also need to install an older version of Android SDK, for example with the Android SDK Manager that comes with Android Studio.
+
+
Using Ubuntu Make
+
+If you're running Ubuntu, one way to install both a Java Development Kit and Android Studio is by using [Ubuntu Make](https://wiki.ubuntu.com/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`
+
+
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](http://developer.android.com/tools/devices/managing-avds.html). Make sure to configure an AVD with an API level that is supported by the version of [Cordova Android](https://github.com/apache/cordova-android/blob/master/RELEASENOTES.md) you are using.
+
+
Developing on a device
+
+During development, the Meteor [build tool](build-tool.html) 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
+> This will run your app on a default simulated iOS device. You can open Xcode to install and select another simulated device.
+- `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](https://www.genymotion.com).
+- `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](#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](https://developer.apple.com/library/mac/documentation/IDEs/Conceptual/AppDistributionGuide/LaunchingYourApponDevices/LaunchingYourApponDevices.html#//apple_ref/doc/uid/TP40012582-CH27-SW4) for more information. You will also need to join the [Apple Developer Program](https://developer.apple.com/programs/) to deploy your app on the Apple iOS App Store.
+
+1. Make sure the device is connected to your computer via a USB cable.
+1. Connect the device to a WiFi network that allows for communication with the server.
+1. Run `meteor run ios-device` to open your project in Xcode.
+1. In the project navigator, choose your device from the Scheme toolbar menu:
+
+1. Click the Run button:
+
+1. 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.
+1. Connect the device to a WiFi network that allows for communication with the server.
+1. Make sure your device is set up for development [as explained here](http://developer.android.com/tools/device.html#setting-up).
+1. You may also need to click 'Allow' on the `Allow USB debugging?` prompt on the device.
+1. 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](#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](https://developer.apple.com/library/tvos/documentation/DeveloperTools/Conceptual/debugging_with_xcode/chapters/debugging_tools.html). You can add [cordova-plugin-console](https://github.com/apache/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
+
+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:
+
+
+1. You'll also need to enable the Web Inspector on your iOS device. Go to *Settings > Safari > Advanced* and enable 'Web Inspector':
+
+
+1. Launch the app on your device and open remote debugger by choosing *Develop > <Your device> > <Your app>/localhost*.
+
+1. 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](https://developer.apple.com/library/safari/documentation/AppleApplications/Conceptual/Safari_Developer_Guide/).
+
+
Debugging on Android with Chrome
+
+See [this article](https://developers.google.com/web/tools/chrome-devtools/debug/remote-debugging/remote-debugging#remote-debugging-on-android-with-chrome-devtools) 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.
+
+- An .apk built by `meteor build` cannot be remotely debugged unless you make a debug build via `meteor build --debug`.
+
+
Hot code push on mobile
+
+During development, the Meteor [build tool](build-tool.html) 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
+1. 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.
+
+If Hot Code Push is not working reliably in your app, and this section doesn't help, see our [guide on diagnosing Hot Code Push issues](/hot-code-push).
+
+
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.
+
+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](#building-and-submitting).
+
+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 hash 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.
+
+
Controlling compatibility version
+
+The compatibility version can be found in the `cordovaCompatibilityVersions` attribute of the JSON file served at `ROOT_URL/__cordova/manifest.json` during `meteor run [ios/android]`.
+
+
+
+You may want to override the compatibility version if you want hot code push to reach older apps that don't have the latest version of your native code from the app store. Let's say you're developing an iOS app, you have the plugin `cordova-plugin-camera@2.4.0`, and your app has the compatibility version pictured above, `3ed5b9318b2916b595f7721759ead4d708dfbd46`. If you were to update to version `2.4.1` of `cordova-plugin-camera`, your server would generate a new compatibility version and your users' apps would stop receiving hot code pushes. However, you can tell your server to use the old compatilibity version:
+
+```sh
+METEOR_CORDOVA_COMPAT_VERSION_IOS=3ed5b9318b2916b595f7721759ead4d708dfbd46 meteor run ios-device
+# or
+METEOR_CORDOVA_COMPAT_VERSION_IOS=3ed5b9318b2916b595f7721759ead4d708dfbd46 meteor build ../build --server=127.0.0.1:3000
+```
+
+Now your users' apps will continue receiving hot code pushes. However, they won't get the new version of the Cordova plugin until they update from the app store. In this case, that's okay, because we only updated a patch version, so the `cordova-plugin-camera` API didn't change. But if you had added a new plugin, like `cordova-plugin-gyroscope`, and changed your Javascript to call `navigator.gyroscope.getCurrent()`, then when the old apps get the new JS code, they will throw the error: `Uncaught TypeError: Cannot read property 'getCurrent' of undefined`.
+
+Another option is using the `METEOR_CORDOVA_COMPAT_VERSION_EXCLUDE` environment variable. If you were to do this:
+
+```sh
+meteor add cordova:cordova-plugin-camera@4.1.0
+meteor add cordova:cordova-plugin-gyroscope@0.1.4
+METEOR_CORDOVA_COMPAT_VERSION_EXCLUDE='cordova-plugin-camera,cordova-plugin-gyroscope' meteor run ios-device
+```
+
+your compatibility version would not change.
+
+The `METEOR_CORDOVA_COMPAT_VERSION_*` env vars must be present __while building__ your app through `run`, `build` or `deploy`.
+
+
Access compatibility versions inside your app
+
+The `version` attribute of `manifest.json`, which reflects the version of only your JS bundle, is accessible from JS at `__meteor_runtime_config__.autoupdateVersionCordova`.
+
+The `cordovaCompatibilityVersions.*` attributes can be read from the manifest file with `cordova-plugin-file`.
+
+
Configuring your server
+
+As mentioned before, mobile apps need to be able to [connect to a server](#connecting-to-the-server) to support hot code push. In production, you will need to specify which server to connect to [when building the app](#building-for-production) 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 new 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 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`](http://docs.meteor.com/api/mobile-config.html#App-setPreference) to set `WebAppStartupTimeout` to another value.
+
+```js
+// The timeout is specified in milliseconds!
+App.setPreference('WebAppStartupTimeout', 30000);
+```
+
+
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](https://cordova.apache.org/docs/en/dev/guide/support/index.html#core-plugin-apis) 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](https://cordova.apache.org/plugins/) or directly on [npm](https://www.npmjs.com/search?q=ecosystem%3Acordova).
+
+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](#plugin-compatibility).
+
+
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 third-party 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:
+
+```sh
+meteor add cordova:cordova-plugin-camera@1.2.0
+```
+
+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)](#plugin-compatibility) 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`:
+
+```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.
+
+>
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](http://docs.meteor.com/api/mobile-config.html).
+
+
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 `#`):
+
+```sh
+meteor add cordova:com.phonegap.plugins.facebookconnect@https://github.com/Wizcorp/phonegap-facebook-plugin.git#5dbb1583168558b4447a13235283803151cb04ec
+```
+
+Meteor packages can also depend on plugins downloaded from Git:
+
+```js
+Cordova.depends({
+ 'com.phonegap.plugins.facebookconnect': 'https://github.com/Wizcorp/phonegap-facebook-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:
+
+```sh
+meteor add cordova:cordova-plugin-underdevelopment@file://../plugins/cordova-plugin-underdevelopment
+```
+
+Meteor packages can also depend on plugins installed from the local file system, although this probably only makes sense for local packages:
+
+```js
+Cordova.depends({
+ 'cordova-plugin-underdevelopment': 'file://../plugins/cordova-plugin-underdevelopment'
+});
+```
+
+
Removing directly installed plugins
+
+You can remove a previously added plugin using `meteor remove`:
+
+```sh
+meteor remove cordova:cordova-plugin-camera
+meteor remove cordova:com.phonegap.plugins.facebookconnect
+meteor remove cordova:cordova-plugin-underdevelopment
+```
+
+
Using plugins
+
+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:
+
+```js
+// 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.
+
+```js
+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 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](https://developer.mozilla.org/en-US/docs/Web/Security/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 `cordova-plugin-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`](https://github.com/apache/cordova-plugin-whitelist) in the version of Cordova we bundle.
+
+In Meteor, you use [`App.accessRule`](http://docs.meteor.com/api/mobile-config.html#App-accessRule) in [`mobile-config.js`](http://docs.meteor.com/api/mobile-config.html) to set additional rules. (These correspond to ``, `` and `` tags in the generated `config.xml`.)
+
+> On iOS, these settings also control [Application Transport Security (ATS)](https://developer.apple.com/library/prerelease/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/uid/TP40009251-SW33), 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:
+> ```js
+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).
+
+> 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:
+> ```js
+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)](https://developer.mozilla.org/en-US/docs/Web/Security/CSP). For now, Meteor adds a permissive `Cross-Origin Resource Sharing (CORS)
+
+What is often confusing to people is that setting `App.accessRule` is not enough to allow access to remote resources. While domain whitelisting allows the client to control which domains it can connect to, additional restrictions based on the [same-origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) also apply. By default, web views will not allow cross-origin HTTP requests initiated from JavaScript for instance, so you will likely run into this when using [`XMLHttpRequest`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest).
+
+To get around these restrictions, you'll have to use what is known as [Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS). In contrast to the whitelisting mechanism configured on the client, CORS relies on headers set by the server. In other words, in order to allow access to a remote resource, you may have to make configuration changes on the server, such as setting a `Access-Control-Allow-Origin` header.
+
+
System Permissions
+Since the release of iOS 8.0 and Android 6.0 (Android Marshmallow), certain system features (e.g. camera, microphone, location, photos, etc.) typically require additional permissions in order to access them, and for iOS 10+ you must also provide a customized privacy usage notification prompt. These values for Android are specified in your app's `AndroidManifest.xml` file and are **also requested at runtime**. For iOS they are specified in your apps `Info.plist` file.
+
+To request them at runtime, consider using the [`cordova.plugins.diagnostic`](https://github.com/dpa99c/cordova-diagnostic-plugin) plugin.
+
+For example, here we prepare our Android and iOS hardware permissions for a WebRTC session.
+
+```sh
+meteor add cordova:cordova.plugins.diagnostic@3.0.2
+```
+
+```js
+if (Meteor.isCordova) {
+ cordova.plugins.diagnostic.isCameraAuthorized(
+ authorized => {
+ if (!authorized) {
+ cordova.plugins.diagnostic.requestCameraAuthorization(
+ granted => {
+ console.log( "Authorization request for camera use was " +
+ (granted ? "granted" : "denied"));
+ },
+ error => { console.error(error); }
+ );
+ }
+ },
+ error => { console.error(error); }
+ );
+}
+```
+
+Alternatively for iOS you can specify the required privacy usage notification prompts in your `mobile-config.js` by using [`App.appendToConfig`](https://docs.meteor.com/api/mobile-config.html#App-appendToConfig) along with the correct [Cocoa Keys](https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html).
+
+Here is an example to access iOS geolocation data:
+```
+App.appendToConfig(`
+
+ My app needs access to your location for navigation purposes
+
+`);
+```
+
+
Configuring your app
+
+Meteor reads a [`mobile-config.js`](http://docs.meteor.com/api/mobile-config.html) file in the root of your app directory during build and uses the settings specified there to generate Cordova's [`config.xml`](https://cordova.apache.org/docs/en/dev/config_ref/index.html) file.
+
+
+
+```
+App.setPreference('BackgroundColor', '0xff0000ff');
+App.setPreference('Orientation', 'default');
+App.setPreference('Orientation', 'all', 'ios');
+```
+
+Refer to [Meteor's Mobile Configuration](http://docs.meteor.com/api/mobile-config.html) documentation and the [preferences section](https://cordova.apache.org/docs/en/dev/config_ref/index.html#preference) of the Cordova documentation for more information on Meteor's Cordova configuration API and the supported options.
+
+
App icons and launch screens
+
+Although Meteor includes a standard set of app icons and launch screens, you will want to configure your own images to match your app's branding in your `mobile-config.js` file.
+
+You can configure the icon and splash screen image sizes using the specific supported settings in [`App.icons`](http://docs.meteor.com/api/mobile-config.html#App-icons) and [`App.launchScreens`](http://docs.meteor.com/api/mobile-config.html#App-launchScreens).
+
+In addition, Cordova on iOS supports using [launch story board images](https://cordova.apache.org/docs/en/latest/reference/cordova-plugin-splashscreen/#launch-storyboard-images), which is now Apple's recommended approach for providing launch screens. This has the benefit of not requiring you to provide an image for every possible device screen size. Remove all the iOS `App.launchScreens` directives from your `mobile-config.js` and use [`App.appendToConfig`](http://docs.meteor.com/api/mobile-config.html#App-appendToConfig) to add the paths to your universal images.
+
+```
+App.appendToConfig(`
+
+
+`);
+```
+
+See the [iOS Human Interface Guidelines for icon and image sizes](https://developer.apple.com/ios/human-interface-guidelines/icons-and-images/image-size-and-resolution/) for more information.
+
+> On [iPhone X](https://developer.apple.com/ios/human-interface-guidelines/overview/iphone-x/) it is likely required that you use launch story board images if you want the launch image to cover the entire screen. There are also other app layout issues that need to be adresssed such as "safe areas" and "rounded corners", see [Apple's iOS app updates for iPhone X](https://developer.apple.com/ios/update-apps-for-iphone-x/).
+
+
Advanced build customization
+
+There is a special top-level directory named `cordova-build-override/` that allows you to override, in an ad-hoc way, parts of your Cordova project that Meteor generates for you in the `.meteor/local/cordova-build` directory. The entire file tree of this directory will be `cp -R` (copied overwriting existing files) to the Cordova project right before the build and compilation step.
+
+The problem with this mechanism is that it overrides complete files, so it is not a good solution for customizing `config.xml`. Replacing the generated version with your own file means you lose all configuration information set by the build process and by installed plugins, which will likely break your app.
+
+If you need to customize configuration files, a workaround is to create a dummy Cordova plugin. In its `plugin.xml`, you can specify a [`config-file` element](https://cordova.apache.org/docs/en/dev/plugin_ref/spec.html#config-file) to selectively change parts of configuration files, including `config.xml`.
+
+> We recommend using these approaches only if absolutely required and if your customizations can not be handled by standard configuration options.
+
+
Deploying to production
+
+
Building for production
+
+Use `meteor build --server=:` to build your app for production.
+
+The `` and `` should be the address of the server you want your app to connect to.
+
+This will generate a directory at ``, which includes a server bundle tarball and the project source for each targeted mobile platform in the `/ios` and `/android` directories.
+
+If you pass `--debug`, the bundles will be compiled in Cordova's debug mode instead of release mode. On Android, this produces a `/android/debug.apk` file that can be installed without signing.
+
+You can pass `--server-only` to only build the server bundle. This allows you to build your app without installing the mobile SDKs on the build machine. This is useful if you use an automated deployment setup for instance. (If you remove the mobile platforms before building instead, hot code push will be disabled because the assets for Cordova included in the server bundle will not be generated.)
+
+
iOS App Store
+
+In order to build your app for iOS, you will need to [configure your app](#configuring-your-app) with at least a version number, and the required set of app icons and launch screens.
+
+After running `meteor build` you can open the generated Xcode project in Xcode:
+```sh
+cd /ios/project
+open MyApp.xcodeproj
+```
+
+From this point on, the process for building the app archive and submitting it to the App Store is the same as it would be for any other iOS app. Please refer to [Apple's documentation](https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/AppDistributionGuide/SubmittingYourApp/SubmittingYourApp.html) for further details.
+
+
Android Play Store
+
+In order to build your app for Android, you will need to [configure your app](#configuring-your-app) with at least a version number, and the required set of app icons and launch screens.
+
+After running `meteor build` the generated APK will be copied from the `/android/project/build/outputs/apk/release` directory to `/android/release-unsigned.apk`.
+> If you have installed [Crosswalk](https://atmospherejs.com/meteor/crosswalk), you will need to manually copy the APK file `cp ~/build-output-directory/android/project/build/outputs/apk/android-armv7-release-unsigned.apk ~/build-output-directory/android/release-unsigned.apk`
+
+Before submitting the APK(s) to the Play Store, you will need to sign the APK and run [`zipalign`](http://developer.android.com/tools/help/zipalign.html) on it to optimize the archive.
+
+(See the [Android developer documentation](http://developer.android.com/tools/publishing/app-signing.html) for more details about the app signing procedure.)
+
+To sign your app, you'll need a private key. This key lets you publish and update your app. If you haven't made a key for this app yet, run:
+```sh
+keytool -genkey -alias your-app-name -keyalg RSA -keysize 2048 -validity 10000
+```
+Optionally, you can specify `--keystore` to use a different keystore. Don't forget to specify the same keystore when signing the APK.
+> Note: Ensure that you have secure backups of your keystore (`~/.keystore` is the default). If you publish an app to the Play Store and then lose the key with which you signed your app, you will not be able to publish any updates to your app, since you must always sign all versions of your app with the same key.
+
+Now, you can sign the APK:
+```sh
+cd ~/build-output-directory/android/
+jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 release-unsigned.apk your-app-name
+```
+Next, you can run zipalign on it to optimize the APK:
+```sh
+$ANDROID_HOME/build-tools//zipalign 4 release-unsigned.apk .apk
+```
+
+From this point on, the process for submitting the app to the Play Store is the same as it would be for any other Android app. `.apk` is the APK to upload to the store. Learn more by visiting https://play.google.com/apps/publish.
+
+
Submitting an app using Crosswalk to to Play Store
+
+Because Crosswalk bundles native code for Chromium, you will end up with APKs for both ARM and x86. You can find the generated APKs in the `/android/project/build/outputs/apk` directory.
+
+You will have to sign and `zipalign` both APKs. You will also have to submit both to the Play Store, see [submitting multiple APKs](http://developer.android.com/google/play/publishing/multiple-apks.html) for more information.
diff --git a/guide/content/data-loading.md b/guide/content/data-loading.md
new file mode 100644
index 0000000000..27ed645cd4
--- /dev/null
+++ b/guide/content/data-loading.md
@@ -0,0 +1,712 @@
+---
+title: Publications and Data Loading
+description: How and where to load data in your Meteor app using publications and subscriptions.
+discourseTopicId: 19661
+---
+
+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.
+8. 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](/collections.html#server-collections), and the [client side Minimongo cache](collections.html#client-collections) 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:
+
+```js
+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 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](security.html#fields).
+
+What that means is that the publication will 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](data-loading.html#patterns).
+
+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.
+
+```js
+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.
+
+```js
+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:
+
+```js
+Meteor.subscribe('todos.inList', list._id);
+```
+
+
Organizing publications
+
+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).
+
+```js
+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
+
+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:
+
+```js
+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](http://blazejs.org/api/templates.html#Blaze-TemplateInstance-subscribe), and about tracking loading state inside UI components in the [UI article](ui-ux.html#subscription-readiness).
+
+
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 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 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](#publication-behavior-with-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](ui-ux.html#components).
+
+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 over-complicated 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](accounts.html)) 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](ui-ux.html).
+
+
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 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()`:
+
+```js
+const handle = Meteor.subscribe('lists.public');
+Tracker.autorun(() => {
+ const isReady = handle.ready();
+ console.log(`Handle is ${isReady ? 'ready' : 'not ready'}`);
+});
+```
+
+If you're subscribing to multiple publications, you can create an array of handles and use [`every`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every) to determine if all are ready:
+
+```js
+const handles = [
+ Meteor.subscribe('lists.public'),
+ Meteor.subscribe('todos.inList'),
+];
+
+Tracker.autorun(() => {
+ const areReady = handles.every(handle => handle.ready());
+ console.log(`Handles are ${areReady ? '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.
+
+```js
+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 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 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).
+
+In this section, we'll consider a publication/subscription technique for the second, infinite-scroll 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-from-publication`](https://atmospherejs.com/percolate/find-from-publication) package to keep track of which records have come from your publication.
+
+In an infinite scroll publication, we 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:
+
+```js
+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:
+
+```js
+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 when they scroll to the bottom of the page).
+
+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`](https://atmospherejs.com/tmeasday/publish-counts) package can be useful to publish this. We could add a `Lists.todoCount` publication like so
+
+```js
+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
+
+```js
+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`](https://atmospherejs.com/meteor/reactive-var) package). A `ReactiveVar` has two properties, `get()` and `set()`:
+
+```js
+DocumentHidden = new ReactiveVar(document.hidden);
+$(window).on('visibilitychange', (event) => {
+ DocumentHidden.set(document.hidden);
+});
+```
+
+If the store is multi-dimensional, you may want to use a `ReactiveDict` (from the [`reactive-dict`](https://atmospherejs.com/meteor/reactive-dict) package):
+
+```js
+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](collections.html#local-collections)).
+
+
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](methods.html).
+
+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:
+
+```js
+WindowSize.simulateMobile = (device) => {
+ if (device === 'iphone6s') {
+ this.set({width: 750, height: 1334});
+ }
+}
+```
+
+
Advanced publications
+
+Sometimes, the 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:
+
+```js
+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.
+
+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`](https://atmospherejs.com/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.
+
+```js
+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 });
+ }
+ }]
+ };
+});
+```
+
+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:
+
+```js
+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:
+
+```js
+Meteor.publishComposite('Todos.admin.inList', function(listId) {
+ new SimpleSchema({
+ listId: {type: String}
+ }).validate({ listId });
+
+ const userId = this.userId;
+ return {
+ find() {
+ return Meteor.users.find({_id: userId, admin: true}, {fields: {admin: 1}});
+ },
+ children: [{
+ find(user) {
+ // We don't need to worry about the list.userId changing this time
+ return Lists.find(listId);
+ }
+ },
+ {
+ find(user) {
+ return Todos.find({listId});
+ }
+ }]
+ };
+});
+```
+
+Note that we explicitly set the `Meteor.users` query fields, as `publish-composite` publishes all of the returned cursors to the client and re-runs the child computations whenever the cursor changes.
+
+Limiting the results serves a double purpose: it both prevents sensitive fields from being disclosed to the client and limits recomputation to the relevant fields only (namely, the `admin` field).
+
+
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:
+
+```js
+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 been 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 "pseudo-collection" 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 publication of the following form:
+
+```js
+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:
+
+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](https://github.com/meteor/meteor/wiki/Oplog-Observe-Driver) 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](#stopping-subscriptions) 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.
+
+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](#custom-publication), 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 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:
+
+```js
+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 field
+ 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](https://atmospherejs.com/simple/rest) package to do this.
+
+In the Todos example app, we have done this, and you can now access our publications over HTTP:
+
+```bash
+$ 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 `user@example.com`, with the password `password`, and created a private list. Then we can access it as follows:
+
+```bash
+# 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": "user@example.com", "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 6PN4EIlwxuVua9PFoaImEP9qzysY64zM6AfpBJCE6bs"
+{
+ "Lists": [
+ {
+ "_id": "92XAn3rWhjmPEga4P",
+ "name": "My Private List",
+ "incompleteCount": 5,
+ "userId": "wq5oLMLi2KMHy5rR6"
+ }
+ ]
+}
+```
+
+
Scaling updates
+
+As previously mentioned, Meteor uses MongoDB's Oplog to identify which changes to apply to which publication. Each change to the database is processed by every Meteor server, so frequent changes can result in high CPU usage across the board. At the same time, your database will come under higher load as all your servers keep fetching data from the oplog.
+
+To solve this issue, you can use the [`cultofcoders:redis-oplog`](https://github.com/cult-of-coders/redis-oplog) package, which opts out completely from using MongoDB's Oplog and shifts the communication to Redis' Pub/Sub system.
+
+The caveats:
+1. You may not need it, if your application is smaller or your data doesn't change a lot.
+2. You'll have to maintain another database [Redis](https://redis.io/).
+3. Changes that happen outside Meteor instance, must be [manually submitted to Redis](https://github.com/cult-of-coders/redis-oplog/blob/master/docs/outside_mutations.md).
+
+The benefits:
+1. Lower load on server CPU and MongoDB.
+2. Backwards compatible (no changes required to your publication/subscription code).
+3. [Better control](https://github.com/cult-of-coders/redis-oplog/blob/master/docs/finetuning.md) over which updates should trigger reactivity.
+4. You can work with a MongoDB database that does not have oplog enabled.
+5. Full control over reactivity using [Vent](https://github.com/cult-of-coders/redis-oplog/blob/master/docs/vent.md).
+
+```
+meteor add cultofcoders:redis-oplog
+meteor add disable-oplog
+```
+
+In your `settings.json` file:
+
+```
+{
+ "redisOplog": {}
+}
+```
+
+```
+# Start Redis, then run Meteor
+meteor run --settings settings.json
+```
+
+Read more about `redis-oplog` here: https://github.com/cult-of-coders/redis-oplog
diff --git a/guide/content/deployment.md b/guide/content/deployment.md
new file mode 100644
index 0000000000..e699d3f4c2
--- /dev/null
+++ b/guide/content/deployment.md
@@ -0,0 +1,365 @@
+---
+title: Deployment and Monitoring
+description: How to deploy, run, and monitor your Meteor app in production.
+discourseTopicId: 19668
+---
+
+After reading this guide, you'll know:
+
+1. What to consider before you deploy a Meteor application.
+2. How to deploy to some common Meteor hosting environments.
+3. How to design a deployment process to make sure your application's quality is maintained.
+4. How to monitor user behavior with analytics tools.
+5. How to monitor your application.
+6. How to make sure your site is discoverable by search engines.
+
+
Deploying Meteor Applications
+
+Once you've built and tested your Meteor application, you need to put it online to show it to the world. Deploying a Meteor application is similar to deploying any other websocket-based Node.js app, but is different in some of the specifics.
+
+Deploying a web application is fundamentally different to releasing most other kinds of software, in that you can deploy as often as you'd like to. You don't need to wait for users to do something to get the new version of your software because the server will push it right at them.
+
+However, it's still important to test your changes throughly with a good process of Quality Assurance (QA). Although it's easy to push out fixes to bugs, those bugs can still cause major problems to users and even potentially data corruption!
+
+>
Never use `--production` flag to deploy!
+>
+> `--production` flag is purely meant to simulate production minification, but does almost nothing else. This still watches source code files, exchanges data with package server and does a lot more than just running the app, leading to unnecessary computing resource wasting and security issues. Please don't use `--production` flag to deploy!
+
+
Deployment environments
+
+In web application deployment it's common to refer to three runtime environments:
+
+1. **Development.** This refers to your machine where you develop new features and run local tests.
+2. **Staging.** An intermediate environment that is similar to production, but not visible to users of the application. Can be used for testing and QA.
+3. **Production.** The real deployment of your app that your customers are currently using.
+
+The idea of the staging environment is to provide a non-user-visible test environment that is as close as possible to production in terms of infrastructure. It's common for issues to appear with new code on the production infrastructure that don't happen in a development environment. A very simple example is issues that involve latency between the client and server---connecting to a local development server with tiny latencies, you just may never see such an issue.
+
+For this reason, developers tend to try and get staging as close as possible to production. This means that all the steps we outline below about production deployment, should, if possible, also be followed for your staging server.
+
+
Environment variables and settings
+
+There are two main ways to configure your application outside of the code of the app itself:
+
+1. **Environment variables.** This is the set of `ENV_VARS` that are set on the running process.
+2. **Settings.** These are in a JSON object set via either the `--settings` Meteor command-line flag or stringified into the `METEOR_SETTINGS` environment variable.
+
+Settings should be used to set environment (i.e. staging vs production) specific things, like the access token and secret used to connect to Google. These settings will not change between any given process running your application in the given environment.
+
+Environment variables are used to set process-specific things, which could conceivably change for different instances of your application's processes. A list of environment variables can be found [here](https://docs.meteor.com/environment-variables.html).
+
+A final note on storing these settings: It's not a good idea to store settings the same repository where you keep your app code. Read about good places to put your settings in the [Security article](security.html#api-keys).
+
+
Other considerations
+
+There are some other considerations that you should make before you deploy your application to a production host. Remember that you should if possible do these steps for both your production *and* staging environments.
+
+
Domain name
+
+What URL will users use to access your site? You'll probably need to register a domain name with a domain registrar, and setup DNS entries to point to the site (this will depend on how you deploy, see below). If you deploy to Galaxy, you can use a `x.meteorapp.com` or `x.eu.meteorapp.com` domain while you are testing the app. [Learn more about Galaxy domains »](http://galaxy-guide.meteor.com/custom-domains.html#meteorapp-subdomain)
+
+
SSL Certificate
+
+It's always a good idea to use SSL for Meteor applications (see the [Security Article](security.html#ssl) to find out why). Once you have a registered domain name, you'll need to generate an SSL certificate with a certificate authority for your domain. If you deploy to Galaxy, you can [generate a free SSL certificate with a single click](http://galaxy-guide.meteor.com/encryption.html#lets-encrypt) (courtesy of Let's Encrypt!).
+
+
CDN
+
+It's not strictly required, but often a good idea to set up a Content Delivery Network (CDN) for your site. A CDN is a network of servers that hosts the static assets of your site (such as JavaScript, CSS, and images) in numerous locations around the world and uses the server closest to your user to provide those files in order to speed up their delivery. For example, if the actual web server for your application is on the east coast of the USA and your user is in Australia, a CDN could host a copy of the JavaScript of the site within Australia or even in the city the user is in. This has huge benefits for the initial loading time of your site.
+
+The basic way to use a CDN is to upload your files to the CDN and change your URLs to point at the CDN (for instance if your Meteor app is at `http://myapp.com`, changing your image URL from `` to ``). However, this would be hard to do with Meteor, since the largest file – your Javascript bundle – changes every time you edit your app.
+
+For Meteor, we recommend using a CDN with "origin" support (like [CloudFront](http://joshowens.me/using-a-cdn-with-your-production-meteor-app/)), which means that instead of uploading your files in advance, the CDN automatically fetches them from your server. You put your files in `public/` (in this case `public/cats.gif`), and when your Australian user asks the CDN for `http://mycdn.com/cats.gif`, the CDN, behind the scenes, fetches `http://myapp.com/cats.gif` and then delivers it to the user. While this is slightly slower than getting `http://myapp.com/cats.gif` directly, it only happens one time, because the CDN saves the file, and all subsequent Australians who ask for the file get it quickly.
+
+To get Meteor to use the CDN for your Javascript and CSS bundles, call `WebAppInternals.setBundledJsCssPrefix("http://mycdn.com")` on the server. This will also take care of relative image URLs inside your CSS files. If you need to use a dynamic prefix, you can return the prefix from a function passed to `WebAppInternals.setBundledJsCssUrlRewriteHook()`.
+
+For all your files in `public/`, change their URLs to point at the CDN. You can use a helper like `assetUrl`.
+
+Before:
+
+```html
+
+```
+
+After:
+
+```js
+Template.registerHelper("assetUrl", (asset) => {
+ return "http://mycdn.com/" + asset
+});
+```
+
+```html
+
+```
+
+
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 in Meteor by adding a handler (you'll need to ensure your CDN is passing the header through):
+
+```js
+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"
+- 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 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](https://www.meteor.com/galaxy/signup), and separately provision a MongoDB database (see below).
+
+Once you've done that, it's easy to [deploy to Galaxy](http://galaxy-guide.meteor.com/deploy-guide.html). You need to [add some environment variables to your settings file](http://galaxy-guide.meteor.com/environment-variables.html) to point it at your MongoDB, and you can deploy with:
+
+```bash
+DEPLOY_HOSTNAME=galaxy.meteor.com meteor deploy your-app.com --settings production-settings.json
+```
+
+To deploy to the EU region, set DEPLOY_HOSTNAME to eu-west-1.galaxy.meteor.com.
+
+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](http://galaxy-guide.meteor.com/dns.html). 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.
+
+
+
+If you are following [our advice](security.html#ssl), you'll probably want to [set up SSL](http://galaxy-guide.meteor.com/encryption.html) on your Galaxy application with the certificate and key for your domain. You should also read the [Security](security.html#ssl) section of this guide for information on how to forcibly redirect HTTP to HTTPS.
+
+Once you are setup with Galaxy, deployment is simple (just re-run the `meteor deploy` command above), as is scaling --- log into galaxy.meteor.com, and scale instantly from there.
+
+
+
+
Meteor Up
+
+[Meteor Up](https://meteor-up.com), often referred to as "mup", is a third-party, open-source tool that can be used to deploy Meteor applications to any online server over SSH. It's essentially a way to automate the manual steps of using `meteor build` and putting that bundle on your server. It also handles setting up the servers, including installing any dependencies, and setting up load balancing and SSL. Although it takes care of many of the details, it can be more work than using a hosting provider.
+
+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 get started with the [tutorial](https://meteor-up.com/getting-started.html).
+
+One of its plugins, [mup-aws-beanstalk](https://github.com/zodern/mup-aws-beanstalk/) deploys Meteor Apps to [AWS Elastic Beanstalk](https://aws.amazon.com/elasticbeanstalk/) instead of a server. It supports autoscaling, load balancing, and zero downtime deploys while taking care of many of the challenges with using Meteor and Elastic Beanstalk.
+
+
Docker
+
+To orchestrate your own container-based deployment there are existing base images to consider before rolling your own:
+
+ - [tozd/docker-meteor](https://github.com/tozd/docker-meteor) with Mongo and Nginx images
+ - [jshimko/meteor-launchpad](https://github.com/jshimko/meteor-launchpad)
+ - [disney/meteor-base](https://github.com/disney/meteor-base)
+
+_The recommendation above is primarily based on current state of maintenance to address upstream security vulnerabilities. Review the Dockerfiles and build scripts to make your own assessment._
+
+
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`:
+
+```bash
+# 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. To find out which version of `node` you should use, run `meteor node -v` in the development environment, or check the `.node_version.txt` file within the bundle generated by `meteor build`. For example, if you are using Meteor 1.6, the version of `node` you should use is 8.8.1.
+
+> 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.
+
+```bash
+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](https://docs.mongodb.com/manual/reference/connection-string/) 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](#galaxy) handles a lot of the specifics like routing clients to the right containers and handling coordinated version updates for you.
+
+
MongoDB options
+
+When you deploy your Meteor server, you need a `MONGO_URL` that points to your MongoDB database. You can either use a hosted MongoDB service or set up and run your own MongoDB server. We recommend using a hosted service, as the time saved and peace of mind are usually worth the higher monthly cost. In either case, the database should be hosted in the same region as the Meteor server (for lower latency). For example if your app is hosted on Galaxy in `us-east-1` (on AWS), then you could create a database on [Compose](https://www.compose.io) in `AWS us-east-1` or on [Amazon Lightsail](https://amazonlightsail.com/) in `us-east-1`.
+
+
Hosted service (recommended)
+
+There are a variety of services out there, and we recommend that you select one of the below services depending on your requirements:
+
+* [Compose](https://www.compose.io)
+* [MongoDB Atlas](https://www.mongodb.com/cloud/atlas)
+
+When selecting a hosted MongoDB service for production it is important to assess the features that the service provides. Below is a nonexhaustive list of features to consider when selecting a service:
+
+* Supports the MongoDB version you wish to run
+* Storage Engine Support (MMAPv1 or WiredTiger) – Since Meteor 1.4 WiredTiger is the default storage engine
+* Support for Replica Sets & Oplog tailing
+* Monitoring & Automated alerting
+* Continuous backups & Automated snapshots
+* Access Control, IP whitelisting, and AWS VPC Peering
+* Encryption of data in-flight and at-rest
+* Cost and pricing granularity
+* Instance size & options
+* Instance configurability – Independently configure your CPU, memory, storage and disk I/O speed.
+
+You can read this [detailed guide](https://www.okgrow.com/posts/mongodb-atlas-setup) by OK GROW! for step-by-step instructions to deploying a production ready MongoDB database on MongoDB Atlas.
+
+
Own server
+
+You can install MongoDB on your own server—one you own, rent, or a VPS (recommended) like [DigitalOcean](https://www.digitalocean.com/) or [Lightsail](https://amazonlightsail.com/). As you can see from the above section, there are many aspects of database setup and maintenance that you have to take care of. For example, to get the best performance, you should choose a server with an [SSD](https://docs.mongodb.com/manual/administration/production-notes/#use-solid-state-disks-ssds) large enough to fit your data and with enough RAM to fit the working set (indexes + active documents) in memory.
+
+
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](https://guide.meteor.com/testing.html) 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](https://medium.com/@natestrauser/migrating-meteor-apps-from-modulus-to-galaxy-with-continuous-deployment-from-codeship-aed2044cabd9#.lvio4sh4a).
+
+
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](collections.html#migrations)).
+
+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](collections.html#migrations).
+
+
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 setup that will get you URL tracking using Google Analytics. We'll be using the [`okgrow:analytics`](https://atmospherejs.com/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](https://atmospherejs.com/okgrow/analytics)). Pass it in as part of [_Meteor settings_](#environment):
+
+```js
+{
+ "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](routing.html) 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:
+
+```js
+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 wrapper for `Meteor.subscribe()`.
+
+
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](https://www.pingdom.com) 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](#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):
+
+
+
+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:
+
+
+
+
APM
+
+If you really want to understand the ins and outs of running your Meteor application, you should use an Application Performance Monitoring (APM) service. There are multiple services designed for Meteor apps:
+
+- [Meteor APM](https://www.meteor.com/cloud)
+- [Monti APM](https://montiapm.com/)
+- [Meteor Elastic APM](https://github.com/Meteor-Community-Packages/meteor-elastic-apm)
+
+These APM's operate 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 APM, you can view current and past behavior of your application over various useful metrics. The APM's have documentation on how to fully use the data to improve your app, but we'll discuss a few key areas here. The screenshots are similar to what you would see in Meteor APM or Monti APM.
+
+
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*. APM's include tools to help you discover which of your methods and publications are slow and resource intensive.
+
+
+
+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:
+
+
+
+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:
+
+
+
+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.
+
+If you’re using [Galaxy to host your meteor apps](https://www.meteor.com/galaxy/signup), you can take advantage of built-in automatic [Prerender.io](https://prerender.io) integration. Add [`mdg:seo`](https://atmospherejs.com/mdg/seo) to your app and Galaxy will take care of the rest: loading the code and configuring it with Galaxy-provided credentials.
+
+If you're not using Galaxy, you can still use `mdg:seo`. You will need to sign up for your own Prerender.io account and provide your token to the `mdg:seo` package in `Meteor.settings`. You can also do this if you use Galaxy but would prefer to use your own Prerender.io account with more frequent cache changes. You can also use the [`prerender-node` NPM package](https://www.npmjs.com/package/prerender-node) directly, mimicing the small amount of [client](https://github.com/meteor/galaxy-seo-package/blob/master/client/prerender.html) and [server](https://github.com/meteor/galaxy-seo-package/blob/master/server/prerender.js) code in the Atmosphere package; do this if you need to use a newer version of the NPM package than the one in `mdg:seo`.
+
+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`](https://atmospherejs.com/kadira/dochead) package. The sensible place to call out to `DocHead` is from the `onCreated` callbacks of your page-level components.
diff --git a/guide/content/hot-code-push.md b/guide/content/hot-code-push.md
new file mode 100644
index 0000000000..e2c2c2a11f
--- /dev/null
+++ b/guide/content/hot-code-push.md
@@ -0,0 +1,237 @@
+---
+title: Hot Code Push
+description: How to diagnose issues with Hot Code Push in a Meteor Cordova app
+---
+
+Is your Meteor Cordova app not getting the updates you’re deploying?
+
+After reading this article, you'll know:
+
+1. The prerequisites to using Hot Code Push
+2. Some techniques to diagnose and solve common issues
+3. How to dig deeper if that doesn't solve your issue
+
+This article builds on the [Cordova](/cordova.html) article. We recommend reading that first, though we've tried to link back to its relevant sections.
+
+
Prerequisites
+
+Make sure that you have:
+
+- an Android and/or iOS mobile app based on Meteor's [Cordova integration](/cordova.html#cordova-integration-in-meteor)
+- the package `hot-code-push` listed in your `.meteor/versions` file
+- locally: make sure your test device and development device are [on the same network](/cordova.html#connecting-to-the-server)
+- in production: make sure the `--server` flag of your `meteor build` command points to the same place as your `ROOT_URL` environment variable (or, on Galaxy, the *site* in `meteor deploy site`). [See details](/cordova.html#configuring-server-for-hot-code-push)
+
+
Known issues
+
+
Override compatability versions
+
+Did the app suddenly stop getting new code after you updated meteor, or you changed plugins?
+
+The client probably logs: `Skipping downloading new version because the Cordova platform version or plugin versions have changed and are potentially incompatible`
+
+Meteor, Cordova and plugins cannot be updated through Hot Code Push. So Meteor by default disables Hot Code Push to app versions that have different versions than the server. This avoids crashing a user’s app, for example, when new JS calls a plugin that his app version doesn’t yet have.
+
+You can [override this behavior](/cordova.html#controlling-compatibility-version). Just make sure you deal with potentially incompatible versions in your JS instead.
+
+
Update your AUTOUPDATE_VERSION
+
+`AUTOUPDATE_VERSION` is an environment variable you can add to your `run` and `deploy` [commands](https://docs.meteor.com/commandline.html):
+
+```sh
+$ AUTOUPDATE_VERSION=abc meteor deploy example.com
+```
+
+If your app has an `AUTOUPDATE_VERSION` set, make sure you change its value when you want a deploy to update your clients.
+
+
Cordova doesn’t hot reload CSS separately
+
+Are you seeing your web app incorporate changes without reload, yet your cordova app reloads each time?
+
+For CSS-only changes, this is the expected behaviour. Browsers update the layout without reload, but in cordova, [any change reloads the whole app](https://docs.meteor.com/packages/autoupdate.html#Cordova-Client).
+
+In case you want to implement soft CSS update for Cordova, see below [how to edit the source](#how-to-edit-the-source).
+
+
Outdated custom reload code and packages
+
+There are [several reload packages](https://atmospherejs.com/?q=reload), and maybe your app includes some custom reload code. Of course, these may have bugs or be outdated.
+
+In particular, when you push an update, does the app reload but use the old code anyways? Probably, the code hasn't been updated to work with Meteor 1.8.1 or later. As mentioned in the [changelog](https://docs.meteor.com/changelog.html#v18120190403), we recommend you call `WebAppLocalServer.switchToPendingVersion` before forcing a browser reload.
+
+Alternatively, use the built-in behavior to reload. Instead of, say, `window.location.reload()`, call the `retry` function passed to the `Reload._onMigrate()` callback. For example:
+
+```js
+Reload._onMigrate((retry) => {
+ if (/* not ready */) {
+ window.setTimeout(retry, 5 * 1000); // Check again in 5 seconds
+ return [false];
+ }
+ // ready
+ return [true];
+});
+```
+
+If you use a package that is no longer compatible, consider forking it or opening a PR with the above changes. Alternatively, you can switch to a compatible one such as [`quave:reloader`](https://github.com/quavedev/reloader)
+
+
Avoid hash fragments
+
+Cordova doesn’t show the URL bar, but the user is still on some URL or other, which may have a hash (`#`). HCP [works better if it doesn't](https://github.com/meteor/meteor/blob/devel/packages/reload/reload.js#L224).
+
+If you can, remove the hash fragment before the reload.
+
+
Avoid making it download big files
+
+In the [client side logs](/cordova.html#logging-and-remote-debugging), you may see HCP fail with errors like:
+
+```
+Error: Error downloading asset: /
+ at http://localhost:12472/plugins/cordova-plugin-meteor-webapp/www/webapp-local-server.js:51:21
+ at Object.callbackFromNative (http://localhost:12472/cordova.js:287:58)
+ at :1:9
+```
+
+This error from [cordova-plugin-meteor-webapp](https://github.com/meteor/cordova-plugin-meteor-webapp) may be caused by big files, often in the `public` folder. Downloading these can fail depending on connection speed, and available space on the device.
+
+You could run `$ du -a public | sort -n -r | head -n 20` to find the 20 biggest files and their sizes. Consider serving them from an external storage service or CDN instead. Then they are only downloaded when really needed, and can fail downloading without blocking HCP.
+
+
If it is only broken locally
+
+If you notice HCP works in production but not when you test locally, you may need to enable clear text or set a correct `--mobile-server`. Both are [explained in the docs](https://docs.meteor.com/packages/autoupdate.html#Cordova-Client).
+
+
Still having issues?
+
+If none of that solved your issues and you’d like to dive deeper, here’s some tips to get you started.
+
+If you end up finding a bug in one of Meteor's packages or plugins, don't hesitate to open an [issue](https://github.com/meteor/meteor/issues) and/or a [pull request](https://github.com/meteor/meteor/pulls).
+
+
Where does hot code push live?
+
+Hot code push is included in `meteor-base` through a web of [official meteor packages](https://github.com/meteor/meteor/tree/devel/packages), most importantly [`reload`](https://github.com/meteor/meteor/tree/devel/packages/reload) and [`autoupdate`](https://github.com/meteor/meteor/tree/devel/packages/autoupdate).
+
+In the case of cordova, a lot of the heavy lifting is done by [`cordova-plugin-meteor-webapp`](https://github.com/meteor/cordova-plugin-meteor-webapp).
+
+To oversimplify, `autoupdate` decides *when* to refresh the client, the plugin then downloads the new client code and assets, and `reload` then refreshes the page to start using them.
+
+
What are the steps it takes?
+
+We can break it down a bit more:
+
+- whenever the server thinks the client side may have changed, it calculates a hash of your entire client bundle
+- it [publishes](https://docs.meteor.com/api/pubsub.html) this hash to all clients
+- the clients subscribe to this publish
+- when a new hash arrives, each client compares it to its own hash
+- if it’s different, it starts to download the new client bundle
+- when it’s done, the client saves any data and announces that it will reload
+- the app and packages get a chance to [save their data or to deny the reload](https://forums.meteor.com/t/is-there-an-official-documentation-of-reload--onmigrate/16974/2)
+- if/when allowed, it reloads
+
+
How to spy on it?
+
+To figure out where the issue is, we can log the various steps HCP takes.
+
+First, make sure you can [see client-side logs](/cordova.html#logging-and-remote-debugging) (or print them on some screen of your app).
+
+A few more useful values to print, and events to listen to, might be:
+
+- The version hashes: `__meteor_runtime_config__.autoupdate.versions['web.cordova']`
+
+- The reactive [`Autoupdate.newClientAvailable()`](https://github.com/meteor/meteor/blob/devel/packages/autoupdate/QA.md#autoupdatenewclientavailable): if this turns into `true` and then doesn’t refresh, you know the client does receive the new version but something goes wrong trying to download or apply it.
+
+```js
+Tracker.autorun(() => {
+ console.log(‘new client available:’, Autoupdate.newClientAvailable());
+});
+```
+
+- To check the client’s subscription to the new versions, check `Meteor.default_connection._subscriptions`. For example, to log whether the subscription is `ready` and `inactive` (using lodash):
+
+```js
+const { ready, inactive } = _.chain(Meteor)
+ .get('default_connection._subscriptions', {})
+ .toPairs()
+ .map(1)
+ .find({ name: 'meteor_autoupdate_clientVersions' })
+ .pick(['inactive', 'ready']) // comment this to see all options
+ .value();
+console.log(‘ready:’, ready);
+console.log(‘inactive:’, inactive);
+```
+Or, to log the value of `ready` each time the subscription changes:
+
+```js
+const hcpSub = _.chain(Meteor)
+ .get('default_connection._subscriptions', {})
+ .toPairs()
+ .map(1)
+ .find({ name: 'meteor_autoupdate_clientVersions' })
+ .value(); // no .pick() this time; return whole subscription object
+
+Tracker.autorun(() => {
+ hcpSub.readyDeps.depend(); // Rerun when something changes in the subscription
+ console.log('hcpSub.ready', hcpSub.ready);
+});
+```
+Should print `false` and then `true` less than a second later.
+
+- To see if we finish downloading and preparing the new version, listen to `WebAppLocalServer.onNewVersionReady`;
+
+```js
+WebAppLocalServer.onNewVersionReady(() => {
+ console.log('new version is ready!');
+ // Copied from original in autoupdate/autoupdate_cordova.js because we overwrite it
+ if (Package.reload) {
+ Package.reload.Reload._reload();
+ }
+});
+```
+
+- To see if permission to reload is being requested, listen to `Reload._onMigrate()`. Be sure to return `[true]` or the reload may not happen. (I believe that if this is run in your app code, it means all packages allowed the reload. But I didn’t find my source on this.)
+
+```js
+Reload._onMigrate(() => {
+ console.log('going to reload now');
+ return [true];
+});
+```
+
+- To know if a run of `Meteor.startup` was the result of a HCP reload or not, we can take advantage of the fact that `Session`s (like `ReactiveDict`s) are preserved.
+
+```js
+Meteor.startup(() => {
+ console.log('Was HCP:', Session.get('wasHCP'));
+ Session.set('wasHCP', false);
+
+ Reload._onMigrate(() => {
+ Session.set('wasHCP', true);
+ return [true];
+ });
+});
+```
+
+
How to edit the source
+
+Finally, if you want to change some of the package and plugin code locally, you can.
+
+
Editing the packages
+
+Say we want to edit the `autoupdate` package.
+
+In the root of your project, create a folder named `packages`, then add a folder `autoupdate`. Here we put the code from the original package (found in `~/.meteor/packages`), then we edit it.
+
+Meteor will now use the local version instead of the official one.
+
+
Editing the plugin
+
+To install a modified version of a plugin,
+
+- from another folder, download the original code e.g. `git clone https://github.com/meteor/cordova-plugin-meteor-webapp.git`
+- install it into your meteor project with [`meteor add cordova:cordova-plugin-meteor-webapp@file://path/to/cordova-plugin-meteor-webapp`](https://stackoverflow.com/a/35941588/5786714)
+- modify it as you like
+
+Meteor will start using the local version instead of the official one. But note you will have to rerun `meteor build` or `meteor run` every time you change the plugin.
+
+
Found a bug?
+
+If you found a bug in one of the packages or plugins, don't hesitate to open an [issue](https://github.com/meteor/meteor/issues) and/or [pull request](https://github.com/meteor/meteor/pulls).
+
+
diff --git a/guide/content/images/accounts-ui.png b/guide/content/images/accounts-ui.png
new file mode 100644
index 0000000000..2911fd1e83
Binary files /dev/null and b/guide/content/images/accounts-ui.png differ
diff --git a/guide/content/images/atom-configuration.png b/guide/content/images/atom-configuration.png
new file mode 100644
index 0000000000..9b808898d5
Binary files /dev/null and b/guide/content/images/atom-configuration.png differ
diff --git a/guide/content/images/ben-es2015-demo.gif b/guide/content/images/ben-es2015-demo.gif
new file mode 100644
index 0000000000..8dbea7780a
Binary files /dev/null and b/guide/content/images/ben-es2015-demo.gif differ
diff --git a/guide/content/images/chromatic-how-it-works.png b/guide/content/images/chromatic-how-it-works.png
new file mode 100644
index 0000000000..c0f1804c7c
Binary files /dev/null and b/guide/content/images/chromatic-how-it-works.png differ
diff --git a/guide/content/images/galaxy-deploying.png b/guide/content/images/galaxy-deploying.png
new file mode 100644
index 0000000000..e43e370d29
Binary files /dev/null and b/guide/content/images/galaxy-deploying.png differ
diff --git a/guide/content/images/galaxy-flash-notification.png b/guide/content/images/galaxy-flash-notification.png
new file mode 100644
index 0000000000..c9c49cd579
Binary files /dev/null and b/guide/content/images/galaxy-flash-notification.png differ
diff --git a/guide/content/images/galaxy-logs.png b/guide/content/images/galaxy-logs.png
new file mode 100644
index 0000000000..c18f8a6651
Binary files /dev/null and b/guide/content/images/galaxy-logs.png differ
diff --git a/guide/content/images/galaxy-metrics.png b/guide/content/images/galaxy-metrics.png
new file mode 100644
index 0000000000..af19cefe01
Binary files /dev/null and b/guide/content/images/galaxy-metrics.png differ
diff --git a/guide/content/images/galaxy-org-dashboard.png b/guide/content/images/galaxy-org-dashboard.png
new file mode 100644
index 0000000000..0db43dc4c8
Binary files /dev/null and b/guide/content/images/galaxy-org-dashboard.png differ
diff --git a/guide/content/images/galaxy-placeholders.png b/guide/content/images/galaxy-placeholders.png
new file mode 100644
index 0000000000..2822db223f
Binary files /dev/null and b/guide/content/images/galaxy-placeholders.png differ
diff --git a/guide/content/images/galaxy-scaling.png b/guide/content/images/galaxy-scaling.png
new file mode 100644
index 0000000000..ebd539676d
Binary files /dev/null and b/guide/content/images/galaxy-scaling.png differ
diff --git a/guide/content/images/galaxy-styleguide-list.png b/guide/content/images/galaxy-styleguide-list.png
new file mode 100644
index 0000000000..12820d392c
Binary files /dev/null and b/guide/content/images/galaxy-styleguide-list.png differ
diff --git a/guide/content/images/galaxy-styleguide.png b/guide/content/images/galaxy-styleguide.png
new file mode 100644
index 0000000000..0a29d7b222
Binary files /dev/null and b/guide/content/images/galaxy-styleguide.png differ
diff --git a/guide/content/images/kadira-method-latency.png b/guide/content/images/kadira-method-latency.png
new file mode 100644
index 0000000000..7c56dd58ff
Binary files /dev/null and b/guide/content/images/kadira-method-latency.png differ
diff --git a/guide/content/images/kadira-method-trace.png b/guide/content/images/kadira-method-trace.png
new file mode 100644
index 0000000000..4f14094b52
Binary files /dev/null and b/guide/content/images/kadira-method-trace.png differ
diff --git a/guide/content/images/kadira-observer-usage.png b/guide/content/images/kadira-observer-usage.png
new file mode 100644
index 0000000000..11d89e07d1
Binary files /dev/null and b/guide/content/images/kadira-observer-usage.png differ
diff --git a/guide/content/images/mobile/ios-safari-settings-web-inspector.png b/guide/content/images/mobile/ios-safari-settings-web-inspector.png
new file mode 100644
index 0000000000..da430553fd
Binary files /dev/null and b/guide/content/images/mobile/ios-safari-settings-web-inspector.png differ
diff --git a/guide/content/images/mobile/mac-safari-preferences-show-develop-menu.png b/guide/content/images/mobile/mac-safari-preferences-show-develop-menu.png
new file mode 100644
index 0000000000..7cc9f40c44
Binary files /dev/null and b/guide/content/images/mobile/mac-safari-preferences-show-develop-menu.png differ
diff --git a/guide/content/images/mobile/xcode-run-scheme.png b/guide/content/images/mobile/xcode-run-scheme.png
new file mode 100644
index 0000000000..763ed86fd2
Binary files /dev/null and b/guide/content/images/mobile/xcode-run-scheme.png differ
diff --git a/guide/content/images/mobile/xcode-select-device.png b/guide/content/images/mobile/xcode-select-device.png
new file mode 100644
index 0000000000..1ff5c277eb
Binary files /dev/null and b/guide/content/images/mobile/xcode-select-device.png differ
diff --git a/guide/content/images/mocha-test-results.png b/guide/content/images/mocha-test-results.png
new file mode 100644
index 0000000000..7102f5e8a6
Binary files /dev/null and b/guide/content/images/mocha-test-results.png differ
diff --git a/guide/content/images/throttle-vs-debounce.png b/guide/content/images/throttle-vs-debounce.png
new file mode 100644
index 0000000000..d476b00b79
Binary files /dev/null and b/guide/content/images/throttle-vs-debounce.png differ
diff --git a/guide/content/images/todos-loading.png b/guide/content/images/todos-loading.png
new file mode 100644
index 0000000000..de23404a74
Binary files /dev/null and b/guide/content/images/todos-loading.png differ
diff --git a/guide/content/images/webstorm-configuration.png b/guide/content/images/webstorm-configuration.png
new file mode 100644
index 0000000000..d6c97038f6
Binary files /dev/null and b/guide/content/images/webstorm-configuration.png differ
diff --git a/guide/content/index.md b/guide/content/index.md
new file mode 100644
index 0000000000..189b0ca778
--- /dev/null
+++ b/guide/content/index.md
@@ -0,0 +1,82 @@
+---
+title: Introduction
+description: This is the guide for using Meteor, a full-stack JavaScript platform for developing modern web and mobile applications.
+---
+
+
+
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
+
+Install the latest official Meteor release [following the steps in our docs](https://docs.meteor.com/install.html).
+
+Once you've installed Meteor, open a new terminal window and create a project:
+
+```bash
+meteor create myapp
+```
+
+Run it locally:
+
+```bash
+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 [tutorials page](https://www.meteor.com/developers/tutorials).
+
+1. [Meteor Examples](https://github.com/meteor/examples) is a list of examples using Meteor. You can also include your example with Meteor.
+
+1. Once you are familiar with the basics, the [Meteor Guide](http://guide.meteor.com) covers intermediate material on how to use Meteor in a larger scale app.
+
+1. Visit the [Meteor discussion forums](https://forums.meteor.com) to announce projects, get help, talk about the community, or discuss changes to core.
+
+1. [Meteor Slack Community](https://join.slack.com/t/meteor-community/shared_invite/enQtODA0NTU2Nzk5MTA3LWY5NGMxMWRjZDgzYWMyMTEyYTQ3MTcwZmU2YjM5MTY3MjJkZjQ0NWRjOGZlYmIxZjFlYTA5Mjg4OTk3ODRiOTc) is the best place to ask (and answer!) technical questions and also meet Meteor developers.
+
+1. [Atmosphere](https://atmospherejs.com) is the repository of community packages designed especially for Meteor.
+
+
What is the Meteor Guide?
+
+This is a set of articles outlining opinions on best-practice application development using the [Meteor](https://meteor.com) 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](https://docs.meteor.com), and you can browse community packages on [atmosphere](https://atmospherejs.com).
+
+
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 [tutorials](https://www.meteor.com/developers/tutorials).
+
+
Example apps
+
+If you want to see some examples, we have a repository dedicated with several examples provided by the community showing many concepts that can be used when implementing your application with Meteor. To know more you can [here](https://github.com/meteor/examples).
+
+
Guide development
+
+
Contributing
+
+Ongoing Meteor Guide development takes place **in the open** [on GitHub](https://github.com/meteor/guide). We encourage pull requests and issues to discuss problems with any 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.
diff --git a/guide/content/methods.md b/guide/content/methods.md
new file mode 100644
index 0000000000..0aa2bc07b8
--- /dev/null
+++ b/guide/content/methods.md
@@ -0,0 +1,500 @@
+---
+title: "Methods"
+description: How to use Methods, Meteor's remote procedure call system, to write to the database.
+discourseTopicId: 19662
+---
+
+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](http://info.meteor.com/blog/optimistic-ui-with-meteor-latency-compensation)—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 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](http://docs.meteor.com/#/full/meteor_methods) 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](security.html#secret-code) for how to hide it from the client.
+
+This example uses the [simpl-schema](https://www.npmjs.com/package/simpl-schema) npm package, which is recommended in several other articles, to validate the Method arguments.
+
+```js
+import SimpleSchema from 'simpl-schema';
+
+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`](http://docs.meteor.com/#/full/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:
+
+```js
+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.
+
+
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. Override the Method for testing.
+3. Call the Method with a custom user ID, especially in tests (as recommended by the [Discover Meteor two-tiered methods pattern](https://www.discovermeteor.com/blog/meteor-pattern-two-tiered-methods/)).
+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
+
+```js
+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:
+
+```js
+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 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:
+
+```js
+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`](http://docs.meteor.com/#/full/meteor_error) and [`ValidationError`](https://atmospherejs.com/mdg/validation-error). These and the regular JavaScript `Error` type should be used in different situations:
+
+
Regular `Error` for internal server errors
+
+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 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 possible to display nice error messages next to particular fields in the form.
+
+When you use `mdg:validated-method` with `simpl-schema` as demonstrated above, this type of error is thrown for you.
+
+Read more about the error format in the [`mdg:validation-error` docs](https://atmospherejs.com/mdg/validation-error).
+
+
Handling errors
+
+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:
+
+```js
+// 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:
+
+```js
+if (!this.isSimulation) {
+ // Logic that depends on server environment here
+}
+```
+
+
Calling a Method from a form
+
+The main thing enabled by the `ValidationError` convention is 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:
+
+```js
+// 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 an HTML form:
+
+```html
+
+
+
+```
+
+Now, let's write some JavaScript to handle this form nicely:
+
+```js
+import { insert } from '../api/invoices/methods.js';
+
+Template.Invoices_newInvoice.onCreated(function() {
+ this.errors = new ReactiveDict();
+});
+
+Template.Invoices_newInvoice.helpers({
+ errors(fieldName) {
+ return Template.instance().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 abstracted by an off-the-shelf form framework or an application-specific wrapper of your own design.
+
+
Loading data with 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. Another disadvantage is that database queries are not shared between clients like publication cursors often are—the Method (and any queries it contains) will run once for each client that calls it.
+
+
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](http://guide.meteor.com/collections.html#local-collections).
+
+```js
+// 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:
+
+```js
+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);
+ });
+ });
+}
+```
+
+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 use Methods in an 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.
+
+
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`](http://docs.meteor.com/#/full/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.
+
+
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](https://github.com/laverdet/node-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()`](http://docs.meteor.com/#/full/method_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
+
+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.
+
+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`](http://docs.meteor.com/#/full/allow) and [`deny`](http://docs.meteor.com/#/full/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](security.html#allow-deny).
+
+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 by defining your Method code on the client and the server, as described in the Method lifecycle section above.
diff --git a/guide/content/mobile.md b/guide/content/mobile.md
new file mode 100644
index 0000000000..c3c3508f87
--- /dev/null
+++ b/guide/content/mobile.md
@@ -0,0 +1,7 @@
+---
+title: Mobile
+description: How to build mobile apps using Meteor's Cordova integration.
+discourseTopicId: 20195
+---
+
+Moved to [Cordova](/cordova)
diff --git a/guide/content/react-native.md b/guide/content/react-native.md
new file mode 100644
index 0000000000..288f32d3c2
--- /dev/null
+++ b/guide/content/react-native.md
@@ -0,0 +1,139 @@
+---
+title: React Native
+description: How to integrate your React Native apps with Meteor
+---
+
+React Native has grown to be one of the most popular platforms for building native apps, being used by [companies like Tesla, Instagram, and Facebook](https://reactnative.dev/showcase) in production. React Native allows you to write apps in JavaScript that are rendered with native code. It has many of the features that you value when working with Meteor, like instant refresh on save.
+
+You can easily integrate your React Native app with Meteor, using the same methods you would on a Meteor + React Web app. The integration supports most Meteor features, including Methods, Pub/Sub, and Password Accounts, and has the same usage as `react-meteor-data`.
+
+
Getting started with React Native
+
+React Native projects are coded using the same React principles, but have a completely separate codebase from your Meteor project.
+
+A collection of NPM packages are being developed to make it easy for you to integrate React Native with Meteor. In order to use React Native with Meteor, you create a React Native app and use the `@meteorrn/core` package to connect your app to your Meteor server. The `@meteorrn/core` package contains Meteor, MongoDB, `withTracker`, Accounts, and more.
+
+For most projects, since your native app will display the same data and call the same methods as your Meteor web app, creating a React Native app that connects to your Meteor server does not require any changes to your Meteor codebase.
+
+The only time you will need to make changes to your Meteor codebase is to enable certain features that are unique to your native app. For example, if you want to add push notifications to your native app, you will need to create a method on your Meteor app to store the native push tokens for a user.
+
+There are two routes for getting started with React Native. You can use "Vanilla" React Native, or you can use [Expo](https://expo.io/). Expo is a set of tools built around React Native. You can even try out React Native from your web browser using [Expo Snack](https://snack.expo.io/). You don't even need to install XCode or Android Studio to start using Expo.
+
+Here are the downsides to using Expo:
+- You cannot add Native Modules that use Native Code (Java, Swift, etc)
+- You cannot use packages that require linking (these are npm modules that include native code, and allow you to acess native features like the camera, push notifications, fingerprint authentication, etc). \
+- Apps that use Expo are much larger then pure React Native apps
+
+Expo does provide some native features ([click here for the full list](https://docs.expo.io/versions/latest/)), but if there is a feature missing that you need, you'll likely need to use an npm package or your own custom native code.
+
+You can "eject" your app from Expo to take advantage of Vanilla React Native features, but ejection cannot be undone easily.
+
+The React Native documentation lets you choose between the Expo ("Expo CLI") and Vanilla React Native ("React Native CLI") setup instructions. You can read through the installation instructions and decide which option makes more sense for you.
+
+Here is the link to the React Native getting started documentation: https://reactnative.dev/docs/environment-setup
+
+Once you have your environment setup and have your app running on your device or in the emulator, you can proceed to the next step of the guide: "Meteor React Native Installation"
+
+
Meteor React Native Installation
+
+To install the `@meteorrn/core` package, run the following command in your React Native project:
+
+````
+npm install --save @meteorrn/core
+````
+
+You also need to confirm you have the package's peer dependencies installed:
+- Confirm you have `@react-native-community/netinfo` installed
+- Confirm you have `@react-native-async-storage/async-storage@>=1.8.1` installed. If you are using Expo, or otherwise cannot use `@react-native-async-storage/async-storage`, please see [these instructions](https://github.com/TheRealNate/meteor-react-native#custom-storage-adapter).
+
+The `@meteorrn/core` package enables your React Native app to establish a DDP connection with your Meteor server so it can receive data from publications and call server methods. It also provides access to core Meteor client methods like `Accounts.createUser` and `Meteor.loginWithPasword`, and allows you to display data in your app with the `withTracker` method.
+
+**Note: If your React Native app uses version 0.59 or lower, the @meteorrn/core package contains breaking changes. Use [react-native-meteor](https://www.npmjs.com/package/react-native-meteor) instead.**
+
+
Setup
+
+
+First, import `Meteor`, `withTracker`, and `Mongo`:
+
+````
+import Meteor, { Mongo, withTracker } from '@meteorrn/core';
+````
+
+Next, you need to connect to your Meteor server. This should typically be at the start of your App.jsx.
+
+````
+Meteor.connect("wss://myapp.meteor.com/websocket");
+````
+
+Define your collections:
+
+````
+const Todos = new Mongo.Collection("todos");
+````
+
+And now you're ready to start coding.
+
+
Coding with Meteor React Native
+
+If you've used React before, coding with React Native is pretty straightforward. However, instead of components like `div` and `span`, we have `View` and `Text`. You can learn the fundamentals of React Native [here](https://reactnative.dev/docs/intro-react).
+
+Meteor React Native's usage is designed to be as close to `meteor/react-meteor-data` and the Meteor core as possible. It provides a `withTracker` method. The package also has full support for accounts, including `Meteor.loginWithPassword`, `Meteor.user`, `Accounts.createUser`, `Meteor.loggingIn`, `Accounts.forgotPassword`, etc.
+
+````
+const MyAppContainer = withTracker(() => {
+
+ const myTodoTasks = Todos.find({completed:false}).fetch();
+ const handle = Meteor.subscribe("myTodos");
+
+ return {
+ myTodoTasks,
+ loading:!handle.ready()
+ };
+
+})(MyApp);
+````
+
+When rendering small amounts of data, you can use the array map method:
+
+````
+import { View, ScrollView, Text } from 'react-native';
+
+class MyApp extends React.Component {
+ render() {
+ const { loading, myTodoTasks } = this.props;
+
+ if(loading) {
+ return Loading your tasks...
+ }
+
+ return (
+
+ {!myTodoTasks.length ?
+ You don't have any tasks
+ :
+ myTodoTasks.map(task => (
+ {task.text}
+ ))
+ }
+
+ );
+ }
+}
+
+````
+
+If you are rendering a large amounts of data, you should use the [FlatList](https://reactnative.dev/docs/flatlist) component.
+
+
Conclusion
+
+**Here are some useful links for futher reading:**
+
+You can see a list of example components built with `MeteorRN` [here](https://github.com/TheRealNate/meteor-react-native/tree/master/examples).
+
+You can view the full API docs for `MeteorRN` on the [meteor-react-native repo](https://github.com/TheRealNate/meteor-react-native/blob/master/docs/api.md)
+
+You can see the official React Native API docs [here](https://reactnative.dev/docs/components-and-apis)
+
+["How to setup your first app" from HackerNoon](https://hackernoon.com/react-native-how-to-setup-your-first-app-a36c450a8a2f)
+
+["The Full React Native Layout Cheat Sheet" from WixEngineering](https://medium.com/wix-engineering/the-full-react-native-layout-cheat-sheet-a4147802405c)
diff --git a/guide/content/react.md b/guide/content/react.md
new file mode 100644
index 0000000000..61b5fecdea
--- /dev/null
+++ b/guide/content/react.md
@@ -0,0 +1,184 @@
+---
+title: React
+description: How to use React with Meteor.
+discourseTopicId: 20192
+---
+
+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](https://reactjs.org/) is a JavaScript library for building reactive user interfaces developed and distributed by the Facebook team.
+
+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](https://reactjs.org/docs/getting-started.html).
+
+To get started with React in Meteor, you can follow along the [React tutorial](https://react-tutorial.meteor.com).
+
+
Installing and using React
+
+To install React in Meteor should add it as a npm dependency:
+
+```sh
+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'`.
+
+```jsx
+import React from 'react';
+
+export const HelloWorld = () =>
Hello World
;
+```
+
+You can render a component hierarchy to the DOM using the `react-dom` package:
+
+```jsx
+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.
+
+By default Meteor already uses React when you create a new app using
+`meteor create my-app` then this basic set up will be already ready for you.
+
+
Using 3rd party packages
+
+Meteor does not require any different configuration as Meteor is 100% compatible with NPM, so you can use any React component library.
+
+
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 offers in the core packages [publications](data-loading.html) and [methods](methods.html), used to subscribe to and modify the data in your application.
+
+To integrate the two systems, we've developed a [`react-meteor-data`](https://atmospherejs.com/meteor/react-meteor-data) package which allows React components to respond to data changes via Meteor's [Tracker](https://www.meteor.com/tracker) reactivity system.
+
+
Using `useTracker`
+
+> The `useTracker` function follows latest best practices of React. Choosing hooks instead of HOCs.
+
+To use data from a Meteor collection inside a React component, install [`react-meteor-data`](https://atmospherejs.com/meteor/react-meteor-data):
+
+```sh
+meteor add react-meteor-data
+```
+
+Once installed, you'll be able to import the `useTracker` function and others.
+
+You can learn more about them [here](https://github.com/meteor/react-packages/tree/master/packages/react-meteor-data#usetrackerreactivefn-deps-hook)
+
+
Routing
+
+Although there are many solutions for routing with Meteor and React, [react-router](https://reactrouter.com/) is the most popular package right now.
+
+As always Meteor does not require anything different when using React Router so you can follow their [quick-start guide](https://reactrouter.com/web/guides/quick-start) to set up React Router in your Meteor project.
+
+
Meteor Packages and Blaze
+
+
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`](https://atmospherejs.com/tmeasday/check-npm-versions) package to check dependency versions at runtime.
+
+
+
React Components in Blaze
+
+If you are not using Blaze with React you can skip this.
+
+If you'd like to use React within a larger app built with [Blaze](#blaze.html) (which is a good strategy if you'd like to incrementally migrate an app from Blaze to React), you can use the [`react-template-helper`](https://atmospherejs.com/meteor/react-template-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:
+
+```html
+
+
Hello, {{username}}
+
{{> React component=UserAvatar userId=_id}}
+
+```
+
+You will need to pass in the component class with a helper:
+
+```js
+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:
+
+- React components must be the only thing in the wrapper element. Due to a limitation of React (see facebook/react [#1970](https://github.com/facebook/react/issues/1970), [#2484](https://github.com/facebook/react/issues/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, make a [template helper that returns a function](http://blazejs.org/guide/reusable-components.html#Pass-callbacks), and pass it in as a prop, like so:
+
+```js
+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:
+
+```html
+
+
+
+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 way to do this is with the [`gadicc:blaze-react-component`](https://atmospherejs.com/gadicc/blaze-react-component) package. First run `meteor add gadicc:blaze-react-component`, then import and use it in your components as follows:
+
+```jsx
+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](https://github.com/gadicc/meteor-blaze-react-component).
diff --git a/guide/content/routing.md b/guide/content/routing.md
new file mode 100644
index 0000000000..cdc2a5e738
--- /dev/null
+++ b/guide/content/routing.md
@@ -0,0 +1,509 @@
+---
+title: "URLs and Routing"
+description: How to drive your Meteor app's UI using URLs with FlowRouter.
+discourseTopicId: 19663
+---
+
+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 dynamically load application modules depending on the URL.
+5. 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 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 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 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
+
+To add routing to your app, install the [`ostrio:flow-router-extra`](https://atmospherejs.com/ostrio/flow-router-extra) package:
+
+```
+meteor add ostrio:flow-router-extra
+```
+
+Flow Router is a community routing package for Meteor.
+
+
Using Flow Router Extra
+
+Flow Router Extra is carefully extended `flow-router` package by `kadira` with waitOn and template context. Flow Router Extra shares original "Flow Router" API including flavoring for extra features like `waitOn`, template context and build in `.render()`. Note: `arillo:flow-router-helpers` and `zimme:active-route` already build into Flow Router Extra and updated to support latest Meteor release.
+
+To add routing to your app, install the [`ostrio:flow-router-extra`](https://github.com/VeliovGroup/flow-router) package:
+
+```
+meteor add ostrio:flow-router-extra
+```
+
+
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:
+
+```js
+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:
+
+```js
+'/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.
+
+Additionally, the URL could contain an HTTP [*query string*](https://en.wikipedia.org/wiki/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](data-loading.html#stores) 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](ui-ux.html#components).
+
+
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 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).
+
+In the Todos example app, we link to each list the user knows about in the `App_body` template:
+
+```html
+{{#each list in lists}}
+
+ ...
+
+ {{list.name}}
+
+{{/each}}
+```
+
+We can determine if the user is currently viewing the list with the `activeListClass` helper:
+
+```js
+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.
+
+*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:
+
+```bash
+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`:
+
+```html
+
+ ...
+ {{> 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:
+
+```js
+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.
+
+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](ui-ux.html) 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:
+
+```html
+
+ {{#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](ui-ux.html#animating-page-changes)).
+
+```js
+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 dependency 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:
+
+```html
+
+ {{#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 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](http://blazejs.org/guide/spacebars.html#Block-Helpers)). Here's how we could write an authorization template:
+
+```html
+
+ {{#if currentUser}}
+ {{> Template.contentBlock}}
+ {{else}}
+ Please log in see this page.
+ {{/if}}
+
+```
+
+Once that template exists, we can wrap our `Lists_show_page`:
+
+```html
+
+ {{#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.
+
+