-
{{#each tasks}}
{{> task}}
{{/each}}
Rate Limiting
By default, there are rules added to the [`DDPRateLimiter`](./DDPRateLimiter.md) that rate limit logins, new user registration and password reset calls to a limit of 5 requests per 10 seconds per session. These are a basic solution to dictionary attacks where a malicious user attempts to guess the passwords of legitimate users by attempting all possible passwords. These rate limiting rules can be removed by calling `Accounts.removeDefaultRateLimit()`. Please see the [`DDPRateLimiter`](./DDPRateLimiter.md) docs for more information.Enable 2FA for this package
You can add 2FA to your login flow by using the package [accounts-2fa](../packages/accounts-2fa.md). You can find an example showing how this would look like [here](../packages/accounts-2fa.md#working-with-accounts-password). --- --- url: /packages/accounts-2fa.md --- # accounts-2fa This package allows you to provide a way for your users to enable 2FA on their accounts, using an authenticator app such as Google Authenticator, or 1Password. When the user is logged in on your app, they will be able to generate a new QR code and read this code on the app they prefer. After that, they'll start receiving their codes. Then, they can finish enabling 2FA on your app, and every time they try to log in to your app, you can redirect them to a place where they can provide a code they received from the authenticator. To provide codes that are exactly compatible with all other Authenticator apps and services that implements TOTP, this package uses [node-2fa](https://www.npmjs.com/package/node-2fa) which works on top of [notp](https://github.com/guyht/notp), **that** implements TOTP ([RFC 6238](https://www.ietf.org/rfc/rfc6238.txt)) (the Authenticator standard), which is based on HOTP ([RFC 4226](https://www.ietf.org/rfc/rfc4226.txt)). > This package is meant to be used with [`accounts-password`](../api/accounts.md#passwords) or [`accounts-passwordless`](./accounts-passwordless.md), so if you don't have either of those in your project, you'll need to add one of them. In the future, we want to enable the use of this package with other login methods, our oauth methods (Google, GitHub, etc...). ## 2FA Activation Flow {#activating-2fa} The first step, in order to enable 2FA, is to generate a QR code so that the user can scan it in an authenticator app and start receiving codes.
```
If you'd prefer not to move your files, you can use the file names
themselves as the URL prefix:
```js
Meteor.AppCache.config({
onlineOnly: [
'/bigimage.jpg',
'/largedata.json'
]
});
```
though keep in mind that since the exclusion is by prefix (this is a
limitation of the application cache manifest), excluding
`/largedata.json` will also exclude such URLs as
`/largedata.json.orig` and `/largedata.json/file1`.
For more information about how Meteor interacts with the application
cache, see the
[AppCache page](https://github.com/meteor/meteor/wiki/AppCache)
in the Meteor wiki.
---
---
url: /tutorials/security/security.md
---
# Application Security for Production
After reading this tutorial, you'll know:
1. The security surface area of a Meteor app.
2. How to secure Meteor Methods, publications, and source code.
3. Where to store secret keys in development and production.
4. How to follow a security checklist when auditing your app.
5. How App Protection works in Galaxy Hosting.
[[toc]]
## Introduction
Securing a web application is all about understanding security domains and understanding the attack surface between these domains. In a Meteor app, things are pretty simple:
1. Code that runs on the server can be trusted.
2. Everything else: code that runs on the client, data sent through Method and publication arguments, etc, can't be trusted.
In practice, this means that you should do most of your security and validation on the boundary between these two domains. In simple terms:
1. Validate and check all inputs that come from the client.
2. Don't leak any secret information to the client.
### Concept: Attack surface
Since Meteor apps are often written in a style that puts client and server code together, it's extra important to be aware what is running on the client, what is running on the server, and what the boundaries are. Here's a complete list of places security checks need to be done in a Meteor app:
1. **Methods**: Any data that comes in through Method arguments needs to be validated, and Methods should not return data the user shouldn't have access to.
2. **Publications**: Any data that comes in through publication arguments needs to be validated, and publications should not return data the user shouldn't have access to.
3. **Served files**: You should make sure none of the source code or configuration files served to the client have secret data.
Each of these points will have their own section below.
#### Avoid allow/deny
In this guide, we're going to take a strong position that using [allow](/api/collections.html#Mongo-Collection-allow) or [deny](/api/collections.html#Mongo-Collection-deny) to run MongoDB queries directly from the client is not a good idea. The main reason is that it is hard to follow the principles outlined above. It's extremely difficult to validate the complete space of possible MongoDB operators, which could potentially grow over time with new versions of MongoDB.
There have been several articles about the potential pitfalls of accepting MongoDB update operators from the client, in particular the [Allow & Deny Security Challenge](https://web.archive.org/web/20220705130732/https://www.discovermeteor.com/blog/allow-deny-security-challenge/) and its [results](https://web.archive.org/web/20220819163744/https://www.discovermeteor.com/blog/allow-deny-challenge-results/), both on the Discover Meteor blog.
Given the points above, we recommend that all Meteor apps should use Methods to accept data input from the client, and restrict the arguments accepted by each Method as tightly as possible.
Here's a code snippet to add to your server code which disables client-side updates on a collection. This will make sure no other part of your app can use `allow` with the collection `Lists`:
```js
// Deny all client-side updates on the Lists collection
Lists.deny({
insert() { return true; },
update() { return true; },
remove() { return true; },
});
```
## Methods
Methods are the way your Meteor server accepts inputs and data from the outside world, so it's natural that they are the most important topic for security. If you don't properly secure your Methods, users can end up modifying your database in unexpected ways - editing other people's documents, deleting data, or messing up your database schema causing the app to crash.
### Validate all arguments
It's much easier to write clean code if you can assume your inputs are correct, so it's valuable to validate all Method arguments before running any actual business logic. You don't want someone to pass a data type you aren't expecting and cause unexpected behavior.
Consider that if you are writing unit tests for your Methods, you would need to test all possible kinds of input to the Method; validating the arguments restricts the space of inputs you need to unit test, reducing the amount of code you need to write overall. It also has the extra bonus of being self-documenting; someone else can come along and read the code to find out what kinds of parameters a Method is looking for.
Just as an example, here's a situation where not checking arguments can be disastrous:
```js
Meteor.methods({
removeWidget(id) {
if (!this.userId) {
throw new Meteor.Error('removeWidget.unauthorized');
}
Widgets.remove(id);
}
});
```
If someone comes along and passes a non-ID selector like `{}`, they will end up deleting the entire collection.
### jam:method
To help you write good Methods that exhaustively validate their arguments, you can use a community package for Methods that enforces argument validation. Read more about how to use it in the [documentation for jam:method](/community-packages/jam-method.html). The rest of the code samples in this article will assume that you are using this package. If you aren't, you can still apply the same principles but the code will look a little different.
### Never pass userId from the client
The `this` context inside every Meteor Method has some useful information about the current connection, and the most useful is [`this.userId`](/api/meteor.html#methods-userId). This property is managed by the DDP login system, and is guaranteed by the framework itself to be secure following widely-used best practices.
Given that the user ID of the current user is available through this context, you should never pass the ID of the current user as an argument to a Method. This would allow any client of your app to pass any user ID they want. Let's look at an example:
```js
// #1: Bad! The client could pass any user ID and set someone else's name
async run({ userId, newName }) {
await Meteor.users.updateAsync(userId, {
$set: { name: newName }
});
}
// #2: Good, the client can only set the name on the currently logged in user
async run({ newName }) {
await Meteor.users.updateAsync(this.userId, {
$set: { name: newName }
});
}
```
The _only_ times you should be passing any user ID as an argument are the following:
1. This is a Method only accessible by admin users, who are allowed to edit other users. See the section about [user roles](/packages/roles) to learn how to define roles and check that a user is in a certain role.
2. This Method doesn't modify the other user, but uses it as a target; for example, it could be a Method for sending a private message, or adding a user as a friend.
### One Method per action
The best way to make your app secure is to understand all of the possible inputs that could come from an untrusted source, and make sure that they are all handled correctly. The easiest way to understand what inputs can come from the client is to restrict them to as small of a space as possible. This means your Methods should all be specific actions, and shouldn't take a multitude of options that change the behavior in significant ways. The end goal is that you can look at each Method in your app and validate or test that it is secure. Here's a secure example Method from the Todos example app:
```js
export const makePrivate = createMethod({
name: 'lists.makePrivate',
schema: new SimpleSchema({
listId: { type: String }
}),
async run({ listId }) {
if (!this.userId) {
throw new Meteor.Error('lists.makePrivate.notLoggedIn',
'Must be logged in to make private lists.');
}
const list = await Lists.findOneAsync(listId);
if (list.isLastPublicList()) {
throw new Meteor.Error('lists.makePrivate.lastPublicList',
'Cannot make the last public list private.');
}
await Lists.updateAsync(listId, {
$set: { userId: this.userId }
});
Lists.userIdDenormalizer.set(listId, this.userId);
}
});
```
You can see that this Method does a _very specific thing_ - it makes a single list private. An alternative would have been to have a Method called `setPrivacy`, which could set the list to private or public, but it turns out that in this particular app the security considerations for the two related operations - `makePrivate` and `makePublic` - are very different. By splitting our operations into different Methods, we make each one much clearer. It's obvious from the above Method definition which arguments we accept, what security checks we perform, and what operations we do on the database.
However, this doesn't mean you can't have any flexibility in your Methods. Let's look at an example:
```js
Meteor.users.methods.setUserData = createMethod({
name: 'Meteor.users.methods.setUserData',
schema: new SimpleSchema({
fullName: { type: String, optional: true },
dateOfBirth: { type: Date, optional: true },
}),
async run(fieldsToSet) {
return (await Meteor.users.updateAsync(this.userId, {
$set: fieldsToSet
}));
}
});
```
The above Method is great because you can have the flexibility of having some optional fields and only passing the ones you want to change. In particular, what makes it possible for this Method is that the security considerations of setting one's full name and date of birth are the same - we don't have to do different security checks for different fields being set. Note that it's very important that the `$set` query on MongoDB is generated on the server - we should never take MongoDB operators as-is from the client, since they are hard to validate and could result in unexpected side effects.
#### Refactoring to reuse security rules
You might run into a situation where many Methods in your app have the same security checks. This can be simplified by factoring out the security into a separate module, wrapping the Method body, or extending the `Mongo.Collection` class to do security inside the `insert`, `update`, and `remove` implementations on the server. However, implementing your client-server communication via specific Methods is still a good idea rather than sending arbitrary `update` operators from the client, since a malicious client can't send an `update` operator that you didn't test for.
### Rate limiting
Like REST endpoints, Meteor Methods can be called from anywhere - a malicious program, script in the browser console, etc. It is easy to fire many Method calls in a very short amount of time. This means it can be easy for an attacker to test lots of different inputs to find one that works. Meteor has built-in rate limiting for password login to stop password brute-forcing, but it's up to you to define rate limits for your other Methods.
In the Todos example app, we use the following code to set a basic rate limit on all Methods:
```js
// Get list of all method names on Lists
const LISTS_METHODS = _.pluck([
insert,
makePublic,
makePrivate,
updateName,
remove,
], 'name');
// Only allow 5 list operations per connection per second
if (Meteor.isServer) {
DDPRateLimiter.addRule({
name(name) {
return _.contains(LISTS_METHODS, name);
},
// Rate limit per connection ID
connectionId() { return true; }
}, 5, 1000);
}
```
This will make every Method only callable 5 times per second per connection. This is a rate limit that shouldn't be noticeable by the user at all, but will prevent a malicious script from totally flooding the server with requests. You will need to tune the limit parameters to match your app's needs.
If you're using `jam:method`, it comes with built-in [rate-limiting](https://github.com/jamauro/method#rate-limiting).
## Publications
Publications are the primary way a Meteor server can make data available to a client. While with Methods the primary concern was making sure users can't modify the database in unexpected ways, with publications the main issue is filtering the data being returned so that a malicious user can't get access to data they aren't supposed to see.
### You can't do security at the rendering layer
In a server-side-rendered framework like Ruby on Rails, it's sufficient to not display sensitive data in the returned HTML response. In Meteor, since the rendering is done on the client, an `if` statement in your HTML template is not secure; you need to do security at the data level to make sure that data is never sent in the first place.
### Rules about Methods still apply
All of the points above about Methods apply to publications as well:
1. Validate all arguments using `check` or npm `simpl-schema`.
1. Never pass the current user ID as an argument.
1. Don't take generic arguments; make sure you know exactly what your publication is getting from the client.
1. Use rate limiting to stop people from spamming you with subscriptions.
### Always restrict fields
[`Mongo.Collection#find` has an option called `projection`](/api/collections.html#Mongo-Collection-find) which lets you filter the fields on the fetched documents. You should always use this in publications to make sure you don't accidentally publish secret fields.
For example, you could write a publication, then later add a secret field to the published collection. Now, the publication would be sending that secret to the client. If you filter the fields on every publication when you first write it, then adding another field won't automatically publish it.
```js
// #1: Bad! If we add a secret field to Lists later, the client
// will see it
Meteor.publish('lists.public', function () {
return Lists.find({userId: {$exists: false}});
});
// #2: Good, if we add a secret field to Lists later, the client
// will only publish it if we add it to the list of fields
Meteor.publish('lists.public', function () {
return Lists.find({userId: {$exists: false}}, {
projection: {
name: 1,
incompleteCount: 1,
userId: 1
}
});
});
```
If you find yourself repeating the fields often, it makes sense to factor out a dictionary of public fields that you can always filter by, like so:
```js
// In the file where Lists is defined
Lists.publicFields = {
name: 1,
incompleteCount: 1,
userId: 1
};
```
Now your code becomes a bit simpler:
```js
Meteor.publish('lists.public', function () {
return Lists.find({userId: {$exists: false}}, {
projection: Lists.publicFields
});
});
```
### Publications and userId
The data returned from publications will often be dependent on the currently logged in user, and perhaps some properties about that user - whether they are an admin, whether they own a certain document, etc.
Publications are not reactive, and they only re-run when the currently logged in `userId` changes, which can be accessed through `this.userId`. Because of this, it's easy to accidentally write a publication that is secure when it first runs, but doesn't respond to changes in the app environment. Let's look at an example:
```js
// #1: Bad! If the owner of the list changes, the old owner will still see it
Meteor.publish('list', async function (listId) {
check(listId, String);
const list = await Lists.findOneAsync(listId);
if (list.userId !== this.userId) {
throw new Meteor.Error('list.unauthorized',
'This list doesn\'t belong to you.');
}
return Lists.find(listId, {
projection: {
name: 1,
incompleteCount: 1,
userId: 1
}
});
});
// #2: Good! When the owner of the list changes, the old owner won't see it anymore
Meteor.publish('list', function (listId) {
check(listId, String);
return Lists.find({
_id: listId,
userId: this.userId
}, {
projection: {
name: 1,
incompleteCount: 1,
userId: 1
}
});
});
```
In the first example, if the `userId` property on the selected list changes, the query in the publication will still return the data, since the security check in the beginning will not re-run. In the second example, we have fixed this by putting the security check in the returned query itself.
Unfortunately, not all publications are as simple to secure as the example above. For more tips on how to use `reywood:publish-composite` to handle reactive changes in publications, see the [data loading article](https://guide.meteor.com/data-loading#complex-auth).
### Passing options
For certain applications, for example pagination, you'll want to pass options into the publication to control things like how many documents should be sent to the client. There are some extra considerations to keep in mind for this particular case.
1. **Passing a limit**: In the case where you are passing the `limit` option of the query from the client, make sure to set a maximum limit. Otherwise, a malicious client could request too many documents at once, which could raise performance issues.
2. **Passing in a filter**: If you want to pass fields to filter on because you don't want all of the data, for example in the case of a search query, make sure to use MongoDB `$and` to intersect the filter coming from the client with the documents that client should be allowed to see. Also, you should whitelist the keys that the client can use to filter - if the client can filter on secret data, it can run a search to find out what that data is.
3. **Passing in fields**: If you want the client to be able to decide which fields of the collection should be fetched, make sure to intersect that with the fields that client is allowed to see, so that you don't accidentally send secret data to the client.
In summary, you should make sure that any options passed from the client to a publication can only restrict the data being requested, rather than extending it.
## Served files
Publications are not the only place the client gets data from the server. The set of source code files and static assets that are served by your application server could also potentially contain sensitive data:
1. Business logic an attacker could analyze to find weak points.
1. Secret algorithms that a competitor could steal.
1. Secret API keys.
### Secret server code
While the client-side code of your application is necessarily accessible by the browser, every application will have some secret code on the server that you don't want to share with the world.
Secret business logic in your app should be located in code that is only loaded on the server. This means it is in a `server/` directory of your app, in a package that is only included on the server, or in a file inside a package that was loaded only on the server.
If you have a Meteor Method in your app that has secret business logic, you might want to split the Method into two functions - the optimistic UI part that will run on the client, and the secret part that runs on the server. Most of the time, putting the entire Method on the server doesn't result in the best user experience. Let's look at an example, where you have a secret algorithm for calculating someone's MMR (ranking) in a game:
```js
// In a server-only file, for example /imports/server/mmr.js
export const MMR = {
updateWithSecretAlgorithm(userId) {
// your secret code here
}
}
```
```js
// In a file loaded on client and server
Meteor.users.methods.updateMMR = new createMethod({
name: 'Meteor.users.methods.updateMMR',
validate: null,
run() {
if (this.isSimulation) {
// Simulation code for the client (optional)
} else {
const { MMR } = require('/imports/server/mmr.js');
MMR.updateWithSecretAlgorithm(this.userId);
}
}
});
```
::: warning
Note that while the Method is defined on the client, the actual secret logic is only accessible from the server and the code will **not** be included in the client bundle. Keep in mind that code inside `if (Meteor.isServer)` and `if (!this.isSimulation)` blocks is still sent to the client, it is just not executed. So don't put any secret code in there.
:::
Secret API keys should never be stored in your source code at all, the next section will talk about how to handle them.
## Securing API keys
Every app will have some secret API keys or passwords:
1. Your database password.
1. API keys for external APIs.
These should never be stored as part of your app's source code in version control, because developers might copy code around to unexpected places and forget that it contains secret keys. You can keep your keys separately in [Dropbox](https://www.dropbox.com/), [LastPass](https://lastpass.com), or another service, and then reference them when you need to deploy the app.
You can pass settings to your app through a _settings file_ or an _environment variable_. Most of your app settings should be in JSON files that you pass in when starting your app. You can start your app with a settings file by passing the `--settings` flag:
```sh
# Pass development settings when running your app locally
meteor --settings development.json
# Pass production settings when deploying your app to Galaxy
meteor deploy myapp.com --settings production.json
```
Here's what a settings file with some API keys might look like:
```js
{
"facebook": {
"appId": "12345",
"secret": "1234567"
}
}
```
In your app's JavaScript code, these settings can be accessed from the variable `Meteor.settings`.
[Read more about managing keys and settings in the Deployment article.](https://guide.meteor.com/deployment)
### Settings on the client
In most normal situations, API keys from your settings file will only be used by the server, and by default the data passed in through `--settings` is only available on the server. However, if you put data under a special key called `public`, it will be available on the client. You might want to do this if, for example, you need to make an API call from the client and are OK with users knowing that key. Public settings will be available on the client under `Meteor.settings.public`.
### Never store valuable information in public property in settings file
It's ok if you want to make some properties of your settings file accessible to the client but never put any valuable information inside the `public` property. Either explicity store it under `private` property or in its own `property`. Any property that's not under `public` is treated as private by default in Meteor.
```javascript
{
"public": {"publicKey": "xxxxx"},
"private": {"privateKey": "xxxxx"}
}
```
or
```javascript
{
"public": {"publicKey": "xxxxx"},
"privateKey": "xxxxx"
}
```
#### Example: API keys for OAuth
For the `accounts-facebook` package to pick up these keys, you need to add them to the service configuration collection in the database. Here's how you do that:
First, add the `service-configuration` package:
```sh
meteor add service-configuration
```
Then, upsert into the `ServiceConfiguration` collection using private settings:
```js
ServiceConfiguration.configurations.upsert({
service: "facebook"
}, {
$set: {
appId: Meteor.settings.private.facebook.appId,
loginStyle: "popup",
secret: Meteor.settings.private.facebook.secret
}
});
```
Now, `accounts-facebook` will be able to find that API key and Facebook login will work properly.
## SSL
This is a very short section, but it deserves its own place in the table of contents.
**Every production Meteor app that handles user data should run with SSL.**
Yes, Meteor does hash your password or login token on the client before sending it over the wire, but that only prevents an attacker from figuring out your password - it doesn't prevent them from logging in as you, since they could send the hashed password to the server to log in! No matter how you slice it, logging in requires the client to send sensitive data to the server, and the only way to secure that transfer is by using SSL. Note that the same issue is present when using cookies for authentication in a normal HTTP web application, so any app that needs to reliably identify users should be running on SSL.
#### Setting up SSL
* On [Galaxy](https://guide.meteor.com/deployment#galaxy), configuration of SSL is automatic. [See the help article about SSL on Galaxy](https://help.galaxycloud.app/en/article/encryption-pt8wbl/).
* If you are running on your own [infrastructure](https://guide.meteor.com/deployment#custom-deployment), there are a few options for setting up SSL, mostly through configuring a proxy web server. See the articles: [Josh Owens on SSL and Meteor](http://joshowens.me/ssl-and-meteor-js/), [SSL on Meteorpedia](http://www.meteorpedia.com/read/SSL), and [Digital Ocean tutorial with an Nginx config](https://www.digitalocean.com/community/tutorials/how-to-deploy-a-meteor-js-application-on-ubuntu-14-04-with-nginx).
#### Forcing SSL
Generally speaking, all production HTTP requests should go over HTTPS, and all WebSocket data should be sent over WSS.
It's best to handle the redirection from HTTP to HTTPS on the platform which handles the SSL certificates and termination.
* On [Galaxy](https://guide.meteor.com/deployment#galaxy), enable the "Force HTTPS" setting on a specific domain in the "Domains & Encryption" section of the application's "Settings" tab.
* Other deployments *may* have control panel options or may need to be manually configured on the proxy server (e.g. HAProxy, nginx, etc.). The articles linked above provide some assistance on this.
In the event that a platform does not offer the ability to configure this, the `force-ssl` package can be added to the project and Meteor will attempt to intelligently redirect based on the presence of the `x-forwarded-for` header.
## HTTP Headers
HTTP headers can be used to improve the security of apps, although these are not a silver bullet, they will assist users in mitigating more common attacks.
### Recommended: Helmet
Although there are many great open source solutions for setting HTTP headers, Meteor recommends [Helmet](https://helmetjs.github.io/). Helmet is a collection of 12 smaller middleware functions that set HTTP headers.
First, install helmet.
```js
meteor npm install helmet --save
```
By default, Helmet can be used to set various HTTP headers (see link above). These are a good starting point for mitigating common attacks. To use the default headers, users should use the following code anywhere in their server side meteor startup code.
> Note: Meteor has not extensively tested each header for compatibility with Meteor. Only headers listed below have been tested.
```js
// With other import statements
import helmet from "helmet";
// Within server side Meter.startup()
WebApp.handlers.use(helmet())
```
At a minimum, Meteor recommends users to set the following headers. Note that code examples shown below are specific to Helmet.
### Content Security Policy
> Note: Content Security Policy is not configured using Helmet's default header configuration.
From MDN, Content Security Policy (CSP) is an added layer of security that helps to detect and mitigate certain types of attacks, including Cross Site Scripting (XSS) and data injection attacks. These attacks are used for everything from data theft to site defacement or distribution of malware.
It is recommended that users use CSP to protect their apps from access by third parties. CSP assists to control how resources are loaded into your application.
By default, Meteor recommends unsafe inline scripts and styles are allowed, since many apps typically use them for analytics, etc. Unsafe eval is disallowed, and the only allowable content source is same origin or data, except for connect which allows anything (since meteor apps make websocket connections to a lot of different origins). Browsers will also be told not to sniff content types away from declared content types.
```js
// With other import statements
import helmet from "helmet";
// Within server side Meter.startup()
WebApp.handlers.use(
helmet.contentSecurityPolicy({
directives: {
defaultSrc: ["'self'"],
scriptSrc: ["'self'", "'unsafe-inline'"],
connectSrc: ["*"],
imgSrc: ["'self'"],
styleSrc: ["'self'", "'unsafe-inline'"],
}
})
);
```
Helmet supports a large number of directives, users should further customise their CSP based on their needs. For more detail please read the following guide: [Content Security Policy](https://helmetjs.github.io/docs/csp/). CSP can be complex, so in addition there are some excellent tools out there to help, including [Google's CSP Evaluator](https://csp-evaluator.withgoogle.com/), [Report-URI's CSP Builder](https://report-uri.com/home/generate), [CSP documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src) from Mozilla and [CSPValidator](https://cspvalidator.org/).
The following example presents a potential CSP and other Security Headers used in a Production Meteor Application.
This configuration may require customization, depending on your setup and use-cases.
```javascript
/* global __meteor_runtime_config__ */
import { Meteor } from 'meteor/meteor'
import { WebApp } from 'meteor/webapp'
import { Autoupdate } from 'meteor/autoupdate'
import { check } from 'meteor/check'
import crypto from 'crypto'
import helmet from 'helmet'
const self = '\'self\''
const data = 'data:'
const unsafeEval = '\'unsafe-eval\''
const unsafeInline = '\'unsafe-inline\''
const allowedOrigins = Meteor.settings.allowedOrigins
// create the default connect source for our current domain in
// a multi-protocol compatible way (http/ws or https/wss)
const url = Meteor.absoluteUrl()
const domain = url.replace(/http(s)*:\/\//, '').replace(/\/$/, '')
const s = url.match(/(?!=http)s(?=:\/\/)/) ? 's' : ''
const usesHttps = s.length > 0
const connectSrc = [
self,
`http${s}://${domain}`,
`ws${s}://${domain}`
]
// Prepare runtime config for generating the sha256 hash
// It is important, that the hash meets exactly the hash of the
// script in the client bundle.
// Otherwise the app would not be able to start, since the runtimeConfigScript
// is rejected __meteor_runtime_config__ is not available, causing
// a cascade of follow-up errors.
const runtimeConfig = Object.assign(__meteor_runtime_config__, Autoupdate, {
// the following lines may depend on, whether you called Accounts.config
// and whether your Meteor app is a "newer" version
accountsConfigCalled: true,
isModern: true
})
// add client versions to __meteor_runtime_config__
Object.keys(WebApp.clientPrograms).forEach(arch => {
__meteor_runtime_config__.versions[arch] = {
version: Autoupdate.autoupdateVersion || WebApp.clientPrograms[arch].version(),
versionRefreshable: Autoupdate.autoupdateVersion || WebApp.clientPrograms[arch].versionRefreshable(),
versionNonRefreshable: Autoupdate.autoupdateVersion || WebApp.clientPrograms[arch].versionNonRefreshable(),
// comment the following line if you use Meteor < 2.0
versionReplaceable: Autoupdate.autoupdateVersion || WebApp.clientPrograms[arch].versionReplaceable()
}
})
const runtimeConfigScript = `__meteor_runtime_config__ = JSON.parse(decodeURIComponent("${encodeURIComponent(JSON.stringify(runtimeConfig))}"))`
const runtimeConfigHash = crypto.createHash('sha256').update(runtimeConfigScript).digest('base64')
const helpmentOptions = {
contentSecurityPolicy: {
blockAllMixedContent: true,
directives: {
defaultSrc: [self],
scriptSrc: [
self,
// Remove / comment out unsafeEval if you do not use dynamic imports
// to tighten security. However, if you use dynamic imports this line
// must be kept in order to make them work.
unsafeEval,
`'sha256-${runtimeConfigHash}'`
],
childSrc: [self],
// If you have external apps, that should be allowed as sources for
// connections or images, your should add them here
// Call helmetOptions() without args if you have no external sources
// Note, that this is just an example and you may configure this to your needs
connectSrc: connectSrc.concat(allowedOrigins),
fontSrc: [self, data],
formAction: [self],
frameAncestors: [self],
frameSrc: ['*'],
// This is an example to show, that we can define to show images only
// from our self, browser data/blob and a defined set of hosts.
// Configure to your needs.
imgSrc: [self, data, 'blob:'].concat(allowedOrigins),
manifestSrc: [self],
mediaSrc: [self],
objectSrc: [self],
// these are just examples, configure to your needs, see
// https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/sandbox
sandbox: [
// allow-downloads-without-user-activation // experimental
'allow-forms',
'allow-modals',
// 'allow-orientation-lock',
// 'allow-pointer-lock',
// 'allow-popups',
// 'allow-popups-to-escape-sandbox',
// 'allow-presentation',
'allow-same-origin',
'allow-scripts',
// 'allow-storage-access-by-user-activation ', // experimental
// 'allow-top-navigation',
// 'allow-top-navigation-by-user-activation'
],
styleSrc: [self, unsafeInline],
workerSrc: [self, 'blob:']
}
},
// see the helmet documentation to get a better understanding of
// the following configurations and settings
strictTransportSecurity: {
maxAge: 15552000,
includeSubDomains: true,
preload: false
},
referrerPolicy: {
policy: 'no-referrer'
},
expectCt: {
enforce: true,
maxAge: 604800
},
frameguard: {
action: 'sameorigin'
},
dnsPrefetchControl: {
allow: false
},
permittedCrossDomainPolicies: {
permittedPolicies: 'none'
}
}
// We assume, that we are working on a localhost when there is no https
// connection available.
// Run your project with --production flag to simulate script-src hashing
if (!usesHttps && Meteor.isDevelopment) {
delete helpmentOptions.contentSecurityPolicy.blockAllMixedContent;
helpmentOptions.contentSecurityPolicy.directives.scriptSrc = [
self,
unsafeEval,
unsafeInline,
];
}
// finally pass the options to helmet to make them apply
helmet(helpmentOptions)
```
### X-Frame-Options
> Note: The X-Frame Options header is configured using Helmet's default header configuration.
From MDN, the X-Frame-Options HTTP response header can be used to indicate whether or not a browser should be allowed to render a page in a ``, `
## Contributing to this documentation
We welcome contributions to the documentation!
Since documentation is always evolving, your help is really valuable to ensure content is accurate and up-to-date.
### How to Contribute
#### Identify elements that need improvement
Are you new here? Please check our [documentation issues](https://github.com/meteor/meteor/issues?q=is%3Aissue%20state%3Aopen%20label%3AProject%3ADocs).
If in doubt about the best way to implement something, please create additional conversation on the issue.
Issues are not assigned, you don’t need to wait for approval before contributing. Jump right in and open a PR — this increases your chances of getting your work merged, since issues can be claimed fast.
#### Do the changes and share them
Documentation live in the `v3-docs/docs` directory of the [Meteor GitHub repository](https://github.com/meteor/meteor/tree/devel/v3-docs/docs)
For small changes, such as fixing typos or formatting, you can simply click the "Edit this page on GitHub" button in the footer to edit the file and submit a PR.
For larger changes, you need to fork meteor repo and start your work from the `devel` branch.
You must test your contribution locally before submitting a pull request. To do so, here are the steps:
1. `cd v3-docs/docs && npm run docs:dev` will run the docs locally at [http://localhost:5173/](http://localhost:5173/)
2. Make your changes and verify them in the browser.
3. run `npm run docs:build` to ensure the build works correctly.
4. Push your work and submit a documented pull request to the `devel` branch.
If you add a new page to the documentation, please make sure the configuration creates a link to access it (see [.vitepress/config.mts](https://github.com/meteor/meteor/blob/devel/v3-docs/docs/.vitepress/config.mts)).
---
---
url: /CONTRIBUTING.md
---
---
---
url: /api/index.md
---
Adding CSS
To include CSS files with your package you can use [`api.addFiles()`](https://docs.meteor.com/api/package.html#PackageAPI-addFiles): ```js Package.onUse(function(api) { api.addFiles('my-package.css', 'client'); }); ``` The CSS file will be automatically loaded into any app that uses your package. ### Adding Sass, Less, or Stylus mixins/variables Just like packages can export JavaScript code, they can export reusable bits of CSS pre-processor code. You can also have a package that doesn't actually include any CSS, but just exports different bits of reusable mixins and variables. To get more details see Meteor [build tool CSS pre-processors](https://guide.meteor.com/build-tool.html#css): ```js Package.onUse(function(api) { api.addFiles('my-package.scss', 'client'); }); ``` This Sass file will be eagerly evaluated and its compiled form will be added to the CSS of the app immediately. ```js Package.onUse(function(api) { api.addFiles([ 'stylesheets/_util.scss', 'stylesheets/_variables.scss' ], 'client', {isImport: true}); }); ``` These two Sass files will be lazily evaluated and only included in the CSS of the app if imported from some other file. ### Adding other assets You can include other assets, such as fonts, icons or images, to your package using [`api.addAssets`](https://docs.meteor.com/api/package.html#PackageAPI-addAssets): ```js Package.onUse(function(api) { api.addAssets([ 'font/OpenSans-Regular-webfont.eot', 'font/OpenSans-Regular-webfont.svg', 'font/OpenSans-Regular-webfont.ttf', 'font/OpenSans-Regular-webfont.woff', ], 'client'); }); ``` You can then access these files from the client from a URL `/packages/username_my-package/font/OpenSans-Regular-webfont.eot` or from the server using the [Assets API](https://docs.meteor.com/api/assets.html#Assets-getTextAsync). ### Exporting While some packages exist just to provide side effects to the app, most packages provide a reusable bit of code that can be used by the consumer with `import`. To export a symbol from your package, use the ES2015 `export` syntax in your `mainModule`: ```js // in my-package.js: export const myName = 'my-package'; ``` Now users of your package can import the symbol with: ```js import { myName } from 'meteor/username:my-package'; ``` ### Dependencies Chances are your package will want to make use of other packages. To ensure they are available, you can declare dependencies. Atmosphere packages can depend both on other Atmosphere packages, as well as packages from npm. #### Atmosphere dependencies To depend on another Atmosphere package, use [`api.use`](https://docs.meteor.com/api/package.html#PackageAPI-use): ```js Package.onUse(function(api) { // This package depends on 1.2.0 or above of validated-method api.use('mdg:validated-method@1.2.0'); }); ``` One important feature of the Atmosphere package system is that it is single-loading: no two packages in the same app can have dependencies on conflicting versions of a single package. Read more about that in the section about version constraints below. #### Depending on Meteor version Note that the Meteor release version number is mostly a marketing artifact - the core Meteor packages themselves typically don't share this version number. This means packages can only depend on specific versions of the packages inside a Meteor release, but can't depend on a specific release itself. We have a helpful shorthand api called [`api.versionsFrom`](https://docs.meteor.com/api/package.html#PackageAPI-versionsFrom) that handles this for you by automatically filling in package version numbers from a particular release: ```js // Use versions of core packages from Meteor 1.2.1 api.versionsFrom('1.2.1'); api.use([ // Don't need to specify version because of versionsFrom above 'ecmascript', 'check', // Still need to specify versions of non-core packages 'mdg:validated-method@1.2.0', 'mdg:validation-error@0.1.0' ]); ``` The above code snippet is equivalent to the code below, which specifies all of the version numbers individually: ```js api.use([ 'ecmascript@0.1.6', 'check@1.1.0', 'mdg:validated-method@1.2.0', 'mdg:validation-error@0.1.0' ]); ``` Additionally, you can call `api.versionsFrom(
{user ? (
) : (
..
```
:::
### 7.5: Login Form style
Ok, let's style the login form now:
Wrap your pairs of label and input in `div`s so it will easier to control it on CSS. Do the same to the button tag.
::: code-group
```jsx [imports/ui/LoginForm.jsx]
```
:::
And then update the CSS:
::: code-group
```css [client/main.css]
.login-form {
display: flex;
flex-direction: column;
height: 100%;
justify-content: center;
align-items: center;
}
.login-form > div {
margin: 8px;
}
.login-form > div > label {
font-weight: bold;
}
.login-form > div > input {
flex-grow: 1;
box-sizing: border-box;
padding: 10px 6px;
background: transparent;
border: 1px solid #aaa;
width: 100%;
font-size: 1em;
margin-right: 16px;
margin-top: 4px;
}
.login-form > div > input:focus {
outline: 0;
}
.login-form > div > button {
background-color: #62807e;
}
```
:::
Now your login form should be centralized and beautiful.
### 7.6: Server startup
Every task should have an owner from now on. So go to your database, as you learn before, and remove all the tasks from there:
`db.tasks.remove({});`
Change your `server/main.js` to add the seed tasks using your `meteorite` user as owner.
Make sure you restart the server after this change so `Meteor.startup` block will run again. This is probably going to happen automatically anyway as you are going to make changes in the server side code.
::: code-group
```js [server/main.js]
import { Meteor } from "meteor/meteor";
import { Accounts } from "meteor/accounts-base";
import { TasksCollection } from "/imports/api/TasksCollection";
const insertTask = (taskText, user) =>
TasksCollection.insertAsync({
text: taskText,
userId: user._id,
createdAt: new Date(),
});
const SEED_USERNAME = "meteorite";
const SEED_PASSWORD = "password";
Meteor.startup(async () => {
if (!(await Accounts.findUserByUsername(SEED_USERNAME))) {
await Accounts.createUser({
username: SEED_USERNAME,
password: SEED_PASSWORD,
});
}
const user = await Accounts.findUserByUsername(SEED_USERNAME);
if ((await TasksCollection.find().countAsync()) === 0) {
[
"First Task",
"Second Task",
"Third Task",
"Fourth Task",
"Fifth Task",
"Sixth Task",
"Seventh Task",
].forEach((taskText) => insertTask(taskText, user));
}
});
```
:::
See that we are using a new field called `userId` with our user `_id` field, we are also setting `createdAt` field.
### 7.7: Task owner
First, let's change our publication to publish the tasks only for the currently logged user. This is important for security, as you send only data that belongs to that user.
::: code-group
```js [/imports/api/TasksPublications.js]
Meteor.publish("tasks", function () {
const userId = this.userId;
if (!userId) {
return this.ready();
}
return TasksCollection.find({ userId });
});
```
:::
Now let's check if we have a `user` before trying to fetch any data:
::: code-group
```js [imports/ui/App.jsx]
..
const tasks = useTracker(() => {
if (!user) {
return [];
}
return TasksCollection.find(
hideCompleted ? hideCompletedFilter : {},
{
sort: { createdAt: -1 },
}
).fetch();
});
const pendingTasksCount = useTracker(() => {
if (!user) {
return 0;
}
..
});
..
```
:::
Also, update the `tasks.insert` method to include the field `userId` when creating a new task:
::: code-group
```js [imports/api/tasksMethods.js]
..
Meteor.methods({
"tasks.insert"(doc) {
return TasksCollection.insertAsync({
...doc,
userId: this.userId,
});
},
..
```
:::
### 7.8: Log out
We also can better organize our tasks by showing the username of the owner below our app bar. You can include a new `div` right after our `Fragment` start tag.
On this, you can add an `onClick` handler to logout the user as well. It is very straightforward, just call `Meteor.logout()` on it.
::: code-group
```js [imports/ui/App.jsx]
..
const logout = () => Meteor.logout();
return (
..
-
{tasks.map(task => (
{user.username} 🚪
..
```
:::
Remember to style your username as well.
::: code-group
```css [client/main.css]
.user {
display: flex;
align-self: flex-end;
margin: 8px 16px 0;
font-weight: bold;
cursor: pointer;
}
```
:::
Phew! You have done quite a lot in this step. Authenticated the user, set the user in the tasks, and provided a way for the user to log out.
Your app should look like this:
In the next step, we are going to learn how to deploy your app!
---
---
url: /tutorials/react/6.filter-tasks.md
---
## 6: Filter tasks
In this step, you will filter your tasks by status and show the number of pending tasks.
### 6.1: useState
First, you are going to add a button to show or hide the completed tasks from the list.
The `useState` function from React is the best way to keep the state of this button. It returns an array with two items, where the first element is the value of the state, and the second is a setter function that is how you are going to update your state. You can use _array destructuring_ to get these two back and already declare a variable for them.
Bear in mind that the names used for the constants do not belong to the React API, you can name them whatever you like.
Also, add a `button` below the task form that will display a different text based on the current state.
::: code-group
```js [imports/ui/App.jsx]
import React, { useState } from 'react';
..
export const App = () => {
const [hideCompleted, setHideCompleted] = useState(false);
..
You can also see all the messages that Meteor is sending and receiving from the server, this is useful for you to learn more about how Meteor works.
Install it in your Google Chrome browser using this [link](https://chrome.google.com/webstore/detail/meteor-devtools-evolved/ibniinmoafhgbifjojidlagmggecmpgf).
### 6.5: Pending tasks
Update the App component in order to show the number of pending tasks in the app bar.
You should avoid adding zero to your app bar when there are no pending tasks.
::: code-group
```js [imports/ui/App.jsx]
..
const pendingTasksCount = useTracker(() =>
TasksCollection.find(hideCompletedFilter).count()
);
const pendingTasksTitle = pendingTasksCount ? ` (${pendingTasksCount})` : '';
..
📝️ To Do List {pendingTasksTitle}
.. ``` ::: You could do both finds in the same `useTracker` and then return an object with both properties but to have a code that is easier to understand, we created two different trackers here. Your app should look like this:
In the next step we are going to include user access in your app.
---
---
url: /tutorials/react/5.styles.md
---
## 5: Styles
### 5.1: CSS
Our user interface up until this point has looked quite ugly. Let's add some basic styling which will serve as the foundation for a more professional looking app.
Replace the content of our `client/main.css` file with the one below, the idea is to have an app bar at the top, and a scrollable content including:
- form to add new tasks;
- list of tasks.
::: code-group
```css [client/main.css]
body {
font-family: sans-serif;
background-color: #315481;
background-image: linear-gradient(to bottom, #315481, #918e82 100%);
background-attachment: fixed;
position: absolute;
top: 0;
bottom: 0;
left: 0;
right: 0;
padding: 0;
margin: 0;
font-size: 14px;
}
button {
font-weight: bold;
font-size: 1em;
border: none;
color: white;
box-shadow: 0 3px 3px rgba(34, 25, 25, 0.4);
padding: 5px;
cursor: pointer;
}
button:focus {
outline: 0;
}
.app {
display: flex;
flex-direction: column;
height: 100vh;
}
.app-header {
flex-grow: 1;
white-space: nowrap;
overflow: hidden;
text-overflow: ellipsis;
}
.main {
display: flex;
flex-direction: column;
flex-grow: 1;
overflow: auto;
background: white;
}
.main::-webkit-scrollbar {
width: 0;
height: 0;
background: inherit;
}
header {
background: #d2edf4;
background-image: linear-gradient(to bottom, #d0edf5, #e1e5f0 100%);
padding: 20px 15px 15px 15px;
position: relative;
box-shadow: 0 3px 3px rgba(34, 25, 25, 0.4);
}
.app-bar {
display: flex;
justify-content: space-between;
}
.app-bar h1 {
font-size: 1.5em;
margin: 0;
display: inline-block;
margin-right: 1em;
}
.task-form {
display: flex;
margin: 16px;
}
.task-form > input {
flex-grow: 1;
box-sizing: border-box;
padding: 10px 6px;
background: transparent;
border: 1px solid #aaa;
width: 100%;
font-size: 1em;
margin-right: 16px;
}
.task-form > input:focus {
outline: 0;
}
.task-form > button {
min-width: 100px;
height: 95%;
background-color: #315481;
}
.tasks {
list-style-type: none;
padding-inline-start: 0;
padding-left: 16px;
padding-right: 16px;
margin-block-start: 0;
margin-block-end: 0;
}
.tasks > li {
display: flex;
padding: 16px;
border-bottom: #eee solid 1px;
align-items: center;
}
.tasks > li > span {
flex-grow: 1;
}
.tasks > li > button {
justify-self: flex-end;
background-color: #ff3046;
}
```
:::
> If you want to learn more about this stylesheet check this article about [Flexbox](https://css-tricks.com/snippets/css/a-guide-to-flexbox/), and also this free [video tutorial](https://flexbox.io/) about it from [Wes Bos](https://twitter.com/wesbos).
>
> Flexbox is an excellent tool to distribute and align elements in your UI.
### 5.2: Applying styles
Now you need to add some elements around your components. You are going to add a `className` to your main div in the `App`, also a `header` element with a few `divs` around your `h1`, and a main `div` around your form and list. Check below how it should be, pay attention to the name of the classes, they need to be the same as in the CSS file:
::: code-group
```js [imports/ui/App.jsx]
..
return (
Welcome to Meteor!
-
{tasks.map((task) => (
📝️ To Do List
.. ``` ::: Your app should look like this:
In the next step, we are going to make this task list more interactive, for example, providing a way to filter tasks.
---
---
url: /tutorials/react/4.update-and-remove.md
---
## 4: Update and Remove
Up until now, you have only inserted documents into our collection. Let's take a look at how you can update and remove them by interacting with the user interface.
### 4.1: Add Checkbox
First, you need to add a `checkbox` element to your `Task` component.
> Be sure to add the `readOnly` attribute since we are not using `onChange` to update the state.
>
> We also have to force our `checked` prop to a `boolean` since React understands that an `undefined` value as inexistent, therefore causing the component to switch from uncontrolled to a controlled one.
>
> You are also invited to experiment and see how the app behaves for learning purposes.
You also want to receive a callback, a function that will be called when the checkbox is clicked.
::: code-group
```js [imports/ui/Task.jsx]
import React from "react";
export const Task = ({ task, onCheckboxClick }) => {
return (
-
{ tasks.map(task =>
### 4.3: Remove tasks
You can remove tasks with just a few lines of code.
First, add a button after text in your `Task` component and receive a callback function.
::: code-group
```js [imports/ui/Task.jsx]
import React from 'react';
export const Task = ({ task, onCheckboxClick, onDeleteClick }) => {
return (
..
{task.text}
..
```
:::
Now add the removal logic in the `App`, you need to have a function to delete the task and provide this function in your callback property in the `Task` component.
For that, let's create a new method called `tasks.delete`:
::: code-group
```javascript [imports/api/tasksMethods.js]
import { Meteor } from "meteor/meteor";
import { TasksCollection } from "./TasksCollection";
Meteor.methods({
..
"tasks.delete"({ _id }) {
return TasksCollection.removeAsync(_id);
},
});
```
:::
Then, let's call this method inside a `handleDelete` function:
::: code-group
```js [imports/ui/App.jsx]
export const App = () => {
..
const handleDelete = ({ _id }) =>// [!code highlight]
Meteor.callAsync("tasks.delete", { _id });// [!code highlight]
..
-
{ tasks.map(task =>
In the next step, we are going to improve the look of your app using CSS with Flexbox.
---
---
url: /tutorials/react/3.forms-and-events.md
---
## 3: Forms and Events
All apps need to allow the user to perform some sort of interaction with the data that is stored. In our case, the first type of interaction is to insert new tasks. Without it, our To-Do app wouldn't be very helpful.
One of the main ways in which a user can insert or edit data on a website is through forms. In most cases, it is a good idea to use the `
);
};
```
:::
### 3.2: Update the App component
Then we can simply add this to our `App` component above your list of tasks:
::: code-group
```js [imports/ui/App.jsx]
import React from "react";
import { useTracker, useSubscribe } from "meteor/react-meteor-data";
import { TasksCollection } from "/imports/api/TasksCollection";
import { Task } from "./Task";
import { TaskForm } from "./TaskForm";
export const App = () => {
const isLoading = useSubscribe("tasks");
const tasks = useTracker(() => TasksCollection.find({}).fetch());
if (isLoading()) {
return Loading...
;
}
return (
Welcome to Meteor!
-
{tasks.map((task) => (
In the next step, we are going to update your tasks state and provide a way for users to remove tasks.
---
---
url: /tutorials/react/2.collections.md
---
## 2: Collections
Meteor already sets up MongoDB for you. In order to use our database, we need to create a _collection_, which is where we will store our _documents_, in our case our `tasks`.
> You can read more about collections [here](https://v3-docs.meteor.com/api/collections.html).
In this step, we will implement all the necessary code to have a basic collection for our tasks up and running using React hooks.
### 2.1: Create Tasks Collection {#create-tasks-collection}
We can create a new collection to store our tasks by creating a new file at `imports/api/TasksCollection.js` which instantiates a new Mongo collection and exports it.
::: code-group
```js [imports/api/TasksCollection.js]
import { Mongo } from "meteor/mongo";
export const TasksCollection = new Mongo.Collection("tasks");
```
:::
Notice that we stored the file in the `imports/api` directory, which is a place to store API-related code, like publications and methods. You can name this folder as you want, this is just a choice.
You can delete the `links.js` file in this folder as we are not going to use this collection.
> You can read more about app structure and imports/exports [here](http://guide.meteor.com/structure.html).
### 2.2: Initialize Tasks Collection {#initialize-tasks-collection}
For our collection to work, you need to import it in the server so it sets some plumbing up.
You can either use `import "/imports/api/TasksCollection"` or `import { TasksCollection } from "/imports/api/TasksCollection"` if you are going to use on the same file, but make sure it is imported.
Now it is easy to check if there is data or not in our collection, otherwise, we can insert some sample data easily as well.
You don't need to keep the old content of `server/main.js`.
::: code-group
```js [server/main.js]
import { Meteor } from "meteor/meteor";
import { TasksCollection } from "/imports/api/TasksCollection";
const insertTask = (taskText) =>
TasksCollection.insertAsync({ text: taskText });
Meteor.startup(async () => {
if ((await TasksCollection.find().countAsync()) === 0) {
[
"First Task",
"Second Task",
"Third Task",
"Fourth Task",
"Fifth Task",
"Sixth Task",
"Seventh Task",
].forEach(insertTask);
}
});
```
:::
So you are importing the `TasksCollection` and adding a few tasks to it iterating over an array of strings and for each string calling a function to insert this string as our `text` field in our `task` document.
### 2.3: Render Tasks Collection {#render-tasks-collection}
Now comes the fun part, you will render the tasks using a React Function Component and a Hook called `useTracker` from a package called [react-meteor-data](https://atmospherejs.com/meteor/react-meteor-data).
> Meteor works with Meteor packages and NPM packages, usually, Meteor packages are using Meteor internals or other Meteor packages.
This package is already included in the React skeleton (`meteor create yourproject`) so you don't need to add it but you can always add Meteor packages running `meteor add package-name`:
```shell
meteor add react-meteor-data
```
Now you are ready to import code from this package, when importing code from a Meteor package the only difference from NPM modules is that you need to prepend `meteor/` in the from part of your import.
The `useTracker` function exported by `react-meteor-data` is a React Hook that allows you to have reactivity in your React components. Every time the data changes through reactivity your component will re-render. Cool, right?
> For more information about React Hooks read [here](https://reactjs.org/docs/hooks-faq.html).
::: code-group
```javascript [imports/ui/App.jsx]
import React from "react";
import { useTracker } from "meteor/react-meteor-data";
import { TasksCollection } from "/imports/api/TasksCollection";
import { Task } from "./Task";
export const App = () => {
const tasks = useTracker(() => TasksCollection.find({}).fetch());
return (
Welcome to Meteor!
-
{tasks.map((task) => (
Loading...
;
}
...
}
```
As you can see, when subscribing to a publication using `useSubscribe` you'll get a `isLoading` function, that you can use to render some loading component before the data is ready.
> For more information on Publications/Subscriptions, please check our [docs](https://v3-docs.meteor.com/api/meteor.html#pubsub).
See how your app should look like now:
You can change your data on MongoDB in the server and your app will react and re-render for you.
You can connect to your MongoDB running `meteor mongo` in the terminal from your app folder or using a Mongo UI client, like [NoSQLBooster](https://nosqlbooster.com/downloads). Your embedded MongoDB is running in port `3001`.
See how to connect:
See your database:
You can double-click your collection to see the documents stored on it:
In the next step, we are going to create tasks using a form.
---
---
url: /tutorials/react/1.creating-the-app.md
---
## 1: Creating the app
### 1.1: Install Meteor {#install-meteor}
First, we need to install Meteor.
If you don't have Meteor installed, you can install it by running:
```shell
npx meteor
```
### 1.2: Create Meteor Project {#create-meteor-project}
The easiest way to setup Meteor with React is by using the command `meteor create` with the option `--react` and your project name (you can also omit the `--react` option since it is the default):
```shell
meteor create simple-todos-react
```
Meteor will create all the necessary files for you.
The files located in the `client` directory are setting up your client side (web), you can see for example `client/main.jsx` where Meteor is rendering your App main component into the HTML.
Also, check the `server` directory where Meteor is setting up the server side (Node.js), you can see the `server/main.js` is initializing your MongoDB database with some data. You don't need to install MongoDB as Meteor provides an embedded version of it ready for you to use.
You can now run your Meteor app using:
```shell
meteor run
```
Don't worry, Meteor will keep your app in sync with all your changes from now on.
Your React code will be located inside the `imports/ui` directory, and `App.jsx` file is the root component of your React To-do app.
Take a quick look at all the files created by Meteor, you don't need to understand them now but it's good to know where they are.
### 1.3: Create Task Component {#create-task-component}
You will make your first change now. Create a new file called `Task.jsx` in your `ui` folder.
This file will export a React component called `Task` that will represent one task in your To-Do list.
::: code-group
```js [imports/ui/Task.jsx]
import React from "react";
export const Task = ({ task }) => {
return Welcome to Meteor!
-
{ tasks.map(task =>
{{#if isUserLoggedIn}}
{{> form }}
...
```
:::
As you can see, if the user is logged in, we render the whole app (`isUserLoggedIn`). Otherwise, we render the Login template. Let’s now create our helper `isUserLoggedIn`:
::: code-group
```js [imports/ui/App.js]
...
const getUser = () => Meteor.user();
const isUserLoggedInChecker = () => Boolean(getUser());
...
Template.mainContainer.helpers({
...,
isUserLoggedIn() {
return isUserLoggedInChecker();
},
});
...
```
:::
### 7.5: Login Form style
Ok, let's style the login form now:
::: code-group
```css [client/main.css]
.login-form {
display: flex;
flex-direction: column;
height: 100%;
justify-content: center;
align-items: center;
}
.login-form > div {
margin: 8px;
}
.login-form > div > label {
font-weight: bold;
}
.login-form > div > input {
flex-grow: 1;
box-sizing: border-box;
padding: 10px 6px;
background: transparent;
border: 1px solid #aaa;
width: 100%;
font-size: 1em;
margin-right: 16px;
margin-top: 4px;
}
.login-form > div > input:focus {
outline: 0;
}
.login-form > div > button {
background-color: #62807e;
}
```
:::
Now your login form should be centralized and beautiful.
### 7.6: Server startup
Every task should have an owner from now on. So go to your database, as you learn before, and remove all the tasks from there:
`db.tasks.remove({});`
Change your `server/main.js` to add the seed tasks using your `meteorite` user as owner.
Make sure you restart the server after this change so `Meteor.startup` block will run again. This is probably going to happen automatically anyway as you are going to make changes in the server side code.
::: code-group
```js [server/main.js]
...
const user = await Accounts.findUserByUsername(SEED_USERNAME);
if ((await TasksCollection.find().countAsync()) === 0) {
[
"First Task",
"Second Task",
"Third Task",
"Fourth Task",
"Fifth Task",
"Sixth Task",
"Seventh Task",
].forEach((taskName) => {
Meteor.callAsync("tasks.insert", {
text: taskName,
createdAt: new Date(),
userId: user._id
});
});
}
...
```
:::
See that we are using a new field called `userId` with our user `_id` field, we are also setting `createdAt` field.
### 7.7: Task owner
First, let's change our publication to publish the tasks only for the currently logged user. This is important for security, as you send only data that belongs to that user.
::: code-group
```js [/imports/api/TasksPublications.js]
import { Meteor } from "meteor/meteor";
import { TasksCollection } from "./TasksCollection";
Meteor.publish("tasks", function () {
let result = this.ready();
const userId = this.userId;
if (userId) {
result = TasksCollection.find({ userId });
}
return result;
});
```
:::
Now let's check if we have a `user` before trying to fetch any data:
::: code-group
```js [imports/ui/App.js]
...
Template.mainContainer.helpers({
tasks() {
let result = [];
if (isUserLoggedInChecker()) {
const instance = Template.instance();
const hideCompleted = instance.state.get(HIDE_COMPLETED_STRING);
const hideCompletedFilter = { isChecked: { $ne: true } };
result = TasksCollection.find(hideCompleted ? hideCompletedFilter : {}, {
sort: { createdAt: -1, _id: -1 },
}).fetch();
}
return result;
},
hideCompleted() {
return Template.instance().state.get(HIDE_COMPLETED_STRING);
},
incompleteCount() {
result = '';
if (isUserLoggedInChecker()) {
const incompleteTasksCount = TasksCollection.find({ isChecked: { $ne: true } }).count();
result = incompleteTasksCount ? `(${incompleteTasksCount})` : '';
}
return result;
},
isUserLoggedIn() {
return isUserLoggedInChecker();
},
});
...
```
:::
Also, update the `tasks.insert` method to include the field `userId` when creating a new task:
::: code-group
```js [imports/api/TasksMethods.js]
...
Meteor.methods({
"tasks.insert"(doc) {
const insertDoc = { ...doc };
if (!('userId' in insertDoc)) {
insertDoc.userId = this.userId;
}
return TasksCollection.insertAsync(insertDoc);
},
...
```
:::
### 7.8: Log out
We can also organize our tasks by showing the owner’s username below our app bar. Let’s add a new `div` where the user can click and log out from the app:
::: code-group
```html [imports/ui/App.html]
...
{{#if isUserLoggedIn}}
In the next step, we are going to learn how to deploy your app!
---
---
url: /tutorials/blaze/5.styles.md
---
## 5: Styles
### 5.1: CSS
Our user interface up until this point has looked quite ugly. Let's add some basic styling which will serve as the foundation for a more professional looking app.
Replace the content of our `client/main.css` file with the one below, the idea is to have an app bar at the top, and a scrollable content including:
- form to add new tasks;
- list of tasks.
::: code-group
```css [client/main.css]
body {
font-family: sans-serif;
background-color: #315481;
background-image: linear-gradient(to bottom, #315481, #918e82 100%);
background-attachment: fixed;
position: absolute;
top: 0;
bottom: 0;
left: 0;
right: 0;
padding: 0;
margin: 0;
font-size: 14px;
}
button {
font-weight: bold;
font-size: 1em;
border: none;
color: white;
box-shadow: 0 3px 3px rgba(34, 25, 25, 0.4);
padding: 5px;
cursor: pointer;
}
button:focus {
outline: 0;
}
.app {
display: flex;
flex-direction: column;
height: 100vh;
}
.app-header {
flex-grow: 1;
white-space: nowrap;
overflow: hidden;
text-overflow: ellipsis;
}
.main {
display: flex;
flex-direction: column;
flex-grow: 1;
overflow: auto;
background: white;
}
.main::-webkit-scrollbar {
width: 0;
height: 0;
background: inherit;
}
header {
background: #d2edf4;
background-image: linear-gradient(to bottom, #d0edf5, #e1e5f0 100%);
padding: 20px 15px 15px 15px;
position: relative;
box-shadow: 0 3px 3px rgba(34, 25, 25, 0.4);
}
.app-bar {
display: flex;
justify-content: space-between;
}
.app-bar h1 {
font-size: 1.5em;
margin: 0;
display: inline-block;
margin-right: 1em;
}
.task-form {
display: flex;
margin: 16px;
}
.task-form > input {
flex-grow: 1;
box-sizing: border-box;
padding: 10px 6px;
background: transparent;
border: 1px solid #aaa;
width: 100%;
font-size: 1em;
margin-right: 16px;
}
.task-form > input:focus {
outline: 0;
}
.task-form > button {
min-width: 100px;
height: 95%;
background-color: #315481;
}
.tasks {
list-style-type: none;
padding-inline-start: 0;
padding-left: 16px;
padding-right: 16px;
margin-block-start: 0;
margin-block-end: 0;
}
.tasks > li {
display: flex;
padding: 16px;
border-bottom: #eee solid 1px;
align-items: center;
}
.tasks > li > label {
flex-grow: 1;
}
.tasks > li > button {
justify-self: flex-end;
background-color: #ff3046;
}
```
:::
> If you want to learn more about this stylesheet check this article about [Flexbox](https://css-tricks.com/snippets/css/a-guide-to-flexbox/), and also this free [video tutorial](https://flexbox.io/) about it from [Wes Bos](https://twitter.com/wesbos).
>
> Flexbox is an excellent tool to distribute and align elements in your UI.
### 5.2: Applying styles
Now you need to add some elements around your components. You are going to add a `class` to your main div in the `App`, also a `header` element with a few `divs` around your `h1`, and a main `div` around your form and list. Check below how it should be, pay attention to the name of the classes, they need to be the same as in the CSS file:
::: code-group
```html [imports/ui/App.html]
...
...
```
:::
Your app should look like this:
In the next step, we are going to make this task list more interactive, for example, providing a way to filter tasks.
---
---
url: /tutorials/blaze/4.update-and-remove.md
---
## 4: Update and Remove
Up until now, you have only inserted documents into our collection. Let's take a look at how you can update and remove them by interacting with the user interface.
### 4.1: Add Checkbox
First, you need to add a `checkbox` element to your `Task` component.
Next, let’s create a new file for our `task` template in `imports/ui/Task.html`, so we can start to separate the logic in our app.
::: code-group
```html [imports/ui/Task.html]
```
:::
Don’t forget to remove the template named `task` in `imports/ui/App.html`.
You must also add the following import:
::: code-group
```js [imports/ui/App.js]
...
import './Task';
...
```
:::
### 4.2: Toggle Checkbox
Now you can update your task document by toggling its `isChecked` field.
First, create a new method called `tasks.toggleChecked` to update the `isChecked` property.
::: code-group
```js [imports/api/TasksMethods.js]
import { Meteor } from "meteor/meteor";
import { TasksCollection } from "./TasksCollection";
Meteor.methods({
..
"tasks.toggleChecked"({ _id, isChecked }) {
return TasksCollection.updateAsync(_id, {
$set: { isChecked: !isChecked },
});
},
});
```
:::
Create a new file called `Task.js` so we can have our handlers to the `task` template:
::: code-group
```js [imports/ui/Task.js]
import { Template } from 'meteor/templating';
import { TasksCollection } from "../api/TasksCollection";
import '/imports/api/TasksMethods.js'; // this import in this client UI allows for optimistic execution
import './Task.html';
Template.task.events({
'click .toggle-checked'() {
// Set the checked property to the opposite of its current value
let taskID = this._id;
let checkedValue = Boolean(this.isChecked);
Meteor.callAsync("tasks.toggleChecked", { _id: taskID, isChecked: checkedValue });
},
});
```
:::
Toggling checkboxes should now persist in the DB even if you refresh the web browser.
Your app should look like this:
If your computer is fast enough, it's possible that when it sets up the default tasks a few will have the same date. That will cause them to non-deterministically "jump around" in the UI as you toggle checkboxes and the UI reactively updates. To make it stable, you can add a secondary sort on the `_id` of the task:
::: code-group
```js [imports/ui/App.js]
...
Template.mainContainer.helpers({
tasks() {
return TasksCollection.find({}, { sort: { createdAt: -1, _id: -1 } });
},
...
```
:::
### 4.3: Remove tasks
You can remove tasks with just a few lines of code.
First, add a button after text `label` in your `Task` component.
::: code-group
```html [imports/ui/Task.html]
...
```
:::
Next you need to have a function to delete the task. For that, let's create a new method called `tasks.delete`:
::: code-group
```js [imports/api/TasksMethods.js]
import { Meteor } from "meteor/meteor";
import { TasksCollection } from "./TasksCollection";
Meteor.methods({
..
"tasks.delete"({ _id }) {
return TasksCollection.removeAsync(_id);
},
});
```
:::
Now add the removal logic in the `Task.js`. It will just be a new event to the `task` template that is activated when the user clicks on a delete button (i.e. any button with the class `delete`):
::: code-group
```javascript [imports/ui/Task.js]
...
Template.task.events({
...,
'click .delete'() {
let taskID = this._id;
Meteor.callAsync("tasks.delete", { _id: taskID });
},
});
```
:::
Your app should look like this:
### 4.4: Getting data in event handlers
In a collection, every inserted document has a unique `_id` field that can refer to that specific document. Inside the event handlers, `this` refers to an individual task object. We can get the `_id` of the current task with `this._id` and any other field available on the client-side. Once we have the `_id`, we can use, update, and remove the relevant task. That’s how our code will update or remove a task.
In the next step, we are going to improve the look of your app using CSS with Flexbox.
---
---
url: /tutorials/blaze/3.forms-and-events.md
---
## 3: Forms and Events
All apps need to allow the user to perform some sort of interaction with the data that is stored. In our case, the first type of interaction is to insert new tasks. Without it, our To-Do app wouldn't be very helpful.
One of the main ways in which a user can insert or edit data on a website is through forms. In most cases, it is a good idea to use the `
{{getUser.username}} 🚪
{{> form }}
...
```
:::
Now, let’s create the `getUser` helper and implement the event that will log out the user when they click on this `div`. Logging out is done by calling the function `Meteor.logout()`:
::: code-group
```js [imports/ui/App.js]
...
Template.mainContainer.events({
...,
'click .user'() {
Meteor.logout();
},
});
...
Template.mainContainer.helpers({
...,
getUser() {
return getUser();
},
});
...
```
:::
Remember to style your username as well.
::: code-group
```css [client/main.css]
.user {
display: flex;
align-self: flex-end;
margin: 8px 16px 0;
font-weight: bold;
cursor: pointer;
}
```
:::
Phew! You have done quite a lot in this step. Authenticated the user, set the user in the tasks, and provided a way for the user to log out.
Your app should look like this:
In the next step, we are going to learn how to deploy your app!
---
---
url: /tutorials/blaze/5.styles.md
---
## 5: Styles
### 5.1: CSS
Our user interface up until this point has looked quite ugly. Let's add some basic styling which will serve as the foundation for a more professional looking app.
Replace the content of our `client/main.css` file with the one below, the idea is to have an app bar at the top, and a scrollable content including:
- form to add new tasks;
- list of tasks.
::: code-group
```css [client/main.css]
body {
font-family: sans-serif;
background-color: #315481;
background-image: linear-gradient(to bottom, #315481, #918e82 100%);
background-attachment: fixed;
position: absolute;
top: 0;
bottom: 0;
left: 0;
right: 0;
padding: 0;
margin: 0;
font-size: 14px;
}
button {
font-weight: bold;
font-size: 1em;
border: none;
color: white;
box-shadow: 0 3px 3px rgba(34, 25, 25, 0.4);
padding: 5px;
cursor: pointer;
}
button:focus {
outline: 0;
}
.app {
display: flex;
flex-direction: column;
height: 100vh;
}
.app-header {
flex-grow: 1;
white-space: nowrap;
overflow: hidden;
text-overflow: ellipsis;
}
.main {
display: flex;
flex-direction: column;
flex-grow: 1;
overflow: auto;
background: white;
}
.main::-webkit-scrollbar {
width: 0;
height: 0;
background: inherit;
}
header {
background: #d2edf4;
background-image: linear-gradient(to bottom, #d0edf5, #e1e5f0 100%);
padding: 20px 15px 15px 15px;
position: relative;
box-shadow: 0 3px 3px rgba(34, 25, 25, 0.4);
}
.app-bar {
display: flex;
justify-content: space-between;
}
.app-bar h1 {
font-size: 1.5em;
margin: 0;
display: inline-block;
margin-right: 1em;
}
.task-form {
display: flex;
margin: 16px;
}
.task-form > input {
flex-grow: 1;
box-sizing: border-box;
padding: 10px 6px;
background: transparent;
border: 1px solid #aaa;
width: 100%;
font-size: 1em;
margin-right: 16px;
}
.task-form > input:focus {
outline: 0;
}
.task-form > button {
min-width: 100px;
height: 95%;
background-color: #315481;
}
.tasks {
list-style-type: none;
padding-inline-start: 0;
padding-left: 16px;
padding-right: 16px;
margin-block-start: 0;
margin-block-end: 0;
}
.tasks > li {
display: flex;
padding: 16px;
border-bottom: #eee solid 1px;
align-items: center;
}
.tasks > li > label {
flex-grow: 1;
}
.tasks > li > button {
justify-self: flex-end;
background-color: #ff3046;
}
```
:::
> If you want to learn more about this stylesheet check this article about [Flexbox](https://css-tricks.com/snippets/css/a-guide-to-flexbox/), and also this free [video tutorial](https://flexbox.io/) about it from [Wes Bos](https://twitter.com/wesbos).
>
> Flexbox is an excellent tool to distribute and align elements in your UI.
### 5.2: Applying styles
Now you need to add some elements around your components. You are going to add a `class` to your main div in the `App`, also a `header` element with a few `divs` around your `h1`, and a main `div` around your form and list. Check below how it should be, pay attention to the name of the classes, they need to be the same as in the CSS file:
::: code-group
```html [imports/ui/App.html]
...
{{> form }}
-
{{#each tasks}}
{{> task}}
{{/each}}
In the next step, we are going to make this task list more interactive, for example, providing a way to filter tasks.
---
---
url: /tutorials/blaze/4.update-and-remove.md
---
## 4: Update and Remove
Up until now, you have only inserted documents into our collection. Let's take a look at how you can update and remove them by interacting with the user interface.
### 4.1: Add Checkbox
First, you need to add a `checkbox` element to your `Task` component.
Next, let’s create a new file for our `task` template in `imports/ui/Task.html`, so we can start to separate the logic in our app.
::: code-group
```html [imports/ui/Task.html]
If your computer is fast enough, it's possible that when it sets up the default tasks a few will have the same date. That will cause them to non-deterministically "jump around" in the UI as you toggle checkboxes and the UI reactively updates. To make it stable, you can add a secondary sort on the `_id` of the task:
::: code-group
```js [imports/ui/App.js]
...
Template.mainContainer.helpers({
tasks() {
return TasksCollection.find({}, { sort: { createdAt: -1, _id: -1 } });
},
...
```
:::
### 4.3: Remove tasks
You can remove tasks with just a few lines of code.
First, add a button after text `label` in your `Task` component.
::: code-group
```html [imports/ui/Task.html]
### 4.4: Getting data in event handlers
In a collection, every inserted document has a unique `_id` field that can refer to that specific document. Inside the event handlers, `this` refers to an individual task object. We can get the `_id` of the current task with `this._id` and any other field available on the client-side. Once we have the `_id`, we can use, update, and remove the relevant task. That’s how our code will update or remove a task.
In the next step, we are going to improve the look of your app using CSS with Flexbox.
---
---
url: /tutorials/blaze/3.forms-and-events.md
---
## 3: Forms and Events
All apps need to allow the user to perform some sort of interaction with the data that is stored. In our case, the first type of interaction is to insert new tasks. Without it, our To-Do app wouldn't be very helpful.
One of the main ways in which a user can insert or edit data on a website is through forms. In most cases, it is a good idea to use the `