Mantra

1.1What's Inside Mantra?

• It has a modern, React‐based UI component layer.
• It has a place to define business logic in your app. We call them actions.
• State management is not provided by Mantra itself, but it allows you to use a wide variety of state managers, including Meteor/Tracker, Redux, Rx.js Observables, Promises, and nearly anything else.
• It has a way to integrate both states and actions into UI components by composing containers.
• It allows you to inject dependencies.
• It helps you to unit test UI, actions, and integrations (containers).
• It has standards for directory layout, file naming, and everything else.

1.2What is Mantra Not?

• It’s not an application platform. An application platform takes care of bundling, network transport, deployment, etc. Mantra uses Meteor as the application platform.
• It’s not a boilerplate, even though we have a directory structure.
• It’s not a code generator. We may have a code‐generation tool, but that’s not a core part of Mantra.

1.3What is Mantra?

• It’s a set of standards for how to architect a Meteor app.
• It also comes with a set of curated libraries that help you implement Mantra on top of Meteor.

1.4Why a Spec?

Mantra is an application architecture. There will be a lot of stakeholders for Mantra, including app developers, tool builders, tutorial authors, and project managers, so it’s very important to have a common standard everyone follows. That’s what this specification does.

1.5Before You Read

This specification is written in a simple language. However, you may feel more comfortable if you have a sound knowledge of the following areas.

• ES2015
• React
• React Containers
• Meteor Basics (Pub/Sub, Tracker, ReactiveDict, etc.)

Refer to Appendix A to learn more about the above areas.

2.1Client-Side Focus

Mantra gives special attention to the client side of your app. Mantra does not mix client and server code together; instead, it recommends code sharing. Here are the reasons why:

• Client side is where you put in a lot of effort. It’s the biggest part of your codebase. Server‐side codebase is relatively simpler to manage and organize.
• In the future, client‐side apps will interact with the server using a schema. Client‐side apps will have no idea how the server was implemented.
• Mantra does not believe in Universal Apps. It encourages multiple apps for different platforms with code sharing. Then it’s common to have a single server to interact with a few client apps.

Based on the above factors, it’s not a good idea to mix client and server code together.

When we discuss Mantra further in this specification, it will be about the client side of your app.

However, most of the apps will have server‐side components. So, we have a directory layout for the server side as well. For that, refer to Appendix B.

2.2ES2015 Syntax and ES2015 Modules

We rely on different features of ES2015 and its module system. In order to use Mantra, you need to use Meteor 1.3, which comes with an implementation of the ES2015 module system.

2.3React as the UI

We use React as the UI (presentation) layer in Mantra.

UI components should not know anything about the rest of the app and should not read or modify the application’s state. Data and event handlers used to render the UI component should be passed in via props from containers or passed in as action props from inside event handlers. It is sometimes necessary to use temporary local state inside a UI component, but that state should never be referenced outside of its own component.

When writing your UI components, you can include any other React component. Here are some places you can import React components:

• Other UI components you define in your app.
• UI components from NPM (like material‐ui).
• Any Containers in your app (we’ll talk about this in a moment).

You can also import any library function and use them in the UI components. You can import them directly from NPM modules, but not from any Meteor packages. These functions should be pure.

Here’s a simple UI component:

import React from 'react';

const PostList = ({posts}) => (
  <div className='postlist'>
    <ul>
      {posts.map(post => (
        <li key={post._id}>
          <a href={`/post/${post._id}`}>{post.title}</a>
        </li>
      ))}
    </ul>
  </div>
);

export default PostList;

2.4Actions

Actions are where you write the business logic in your app. This includes:

• Validations
• State management
• Interacting with remote data sources

An action is a simple function that accepts the first argument as the whole Application Context in your app. Other arguments usually come when invoking the action.

Here are some actions:

export default {
  create({Meteor, LocalState, FlowRouter}, title, content) {
    if (!title || !content) {
      return LocalState.set('SAVING_ERROR', 'Title & Content are required!');
    }

    LocalState.set('SAVING_ERROR', null);

    const id = Meteor.uuid();
    // There is a method stub for this in the config/method_stubs
    // That's how we are doing latency compensation
    Meteor.call('posts.create', id, title, content, (err) => {
      if (err) {
        return LocalState.set('SAVING_ERROR', err.message);
      }
    });
    FlowRouter.go(`/post/${id}`);
  },

  clearErrors({LocalState}) {
    return LocalState.set('SAVING_ERROR', null);
  }
};

2.5State Management

In an app, we need to deal with different kinds of states. We can divide them into two different categories:

1. Local State – State in the client‐side app that will never be synced with a remote server (errors, validation messages, current page).
2. Remote State – This is the state usually fetched from a remote server and synced with it.

We have different solutions for managing states in our app, including:

• Meteor/MiniMongo (Remote State)
• Tracker/ReactiveDict (Local State)
• FlowRouter (Local State)
• Redux (Local State)
• GraphQL (Remote State)
• Falcor (Remote State)

This is where a lot of innovation is happening in the JavaScript community. So, Mantra is flexible when it comes to state management. You can use anything you want.

For example, you can use the following for your app when starting:

• Meteor/MiniMongo (Remote State)
• Tracker/ReactiveDict (Local State)
• FlowRouter (Local State)

Later on you can move on to different solutions.

• Any write operations to states should be done inside an action.
• You can read states in both actions and containers.
• You should not read or write into states directly inside UI components. UI components should know nothing about states in your app.

See the following links for some sample usage of states:

• Reading from local state – inside a container
• Writing into local state – inside an action
• Reading from a remote state – inside a container

2.6Containers

Containers are the integration layer in Mantra. They perform these actions:

• Use state to modify variables and pass them into UI components via props.
• Pass actions into UI components.
• Pass items in Application Context into UI components.

A container is a React component.

Containers are composed using react‐komposer. It supports different data sources, including Meteor/Tracker, Promises, Rx.js Observable, and nearly anything else.

Normally, inside a container you need to write the following functions:

• composer functions to get data from state managers.
• mapper function to get data from dependency injection layer.

We have some rules when creating a container:

• There should be only one container inside a single file and the container should be the default export.
• composer functions and the mapper function should be exported from the container module.
• Composer functions should only use variables coming via props.
• The mapper function should be pure.

Here’s an example container:

import PostList from '../components/postlist.jsx';
import {useDeps, composeWithTracker, composeAll} from 'mantra-core';

export const composer = ({context}, onData) => {
  const {Meteor, Collections} = context();
  if (Meteor.subscribe('posts.list').ready()) {
    const posts = Collections.Posts.find().fetch();
    onData(null, {posts});
  }
};

export default composeAll(
  composeWithTracker(composer),
  useDeps()
)(PostList);

2.7Application Context

Application Context is available to all actions and containers, so this is the place for shared variables in your app. These include:

• Meteor namespace
• Meteor Collections
• LocalState
• FlowRouter
• Any other Meteor package
• Redux Stores
• Rest Clients
• DDP Clients

Here’s a simple Application Context:

import * as Collections from '/lib/collections';
import {Meteor} from 'meteor/meteor';
import {FlowRouter} from 'meteor/kadira:flow-router';
import {ReactiveDict} from 'meteor/reactive-dict';
import {Tracker} from 'meteor/tracker';

export default function () {
  return {
    Meteor,
    FlowRouter,
    Collections,
    LocalState: new ReactiveDict(),
    Tracker
  };
}

2.8Dependency Injection

Mantra uses dependency injection to isolate different parts of your app including UI components and actions.

We use a project called react-simple-di that uses React Context behind the scenes. It accepts both Application Context and Actions as dependencies.

Once configured, Application Context will be injected into each action. That’s the first argument of an action. So, you don’t need to pass the application context manually.

Application Context can be accessed within Containers as well.

import React from 'react';
export default function (injectDeps) {
  // See: Injecting Deps
  const MainLayoutCtx = injectDeps(MainLayout);

  // Routes related code
}

2.9Routing & Component Mounting

We normally use a Router to mount components to the UI. There could be multiple solutions (for example, Flow Router and React Router).

The Router’s only functionality in Mantra is to mount components to the UI. It’s just a tool.

See how to use FlowRouter as the router:

import React from 'react';
import {FlowRouter} from 'meteor/kadira:flow-router';
import {mount} from 'react-mounter';

import MainLayout from '/client/modules/core/components/main_layout.jsx';
import PostList from '/client/modules/core/containers/postlist';

export default function (injectDeps) {
  const MainLayoutCtx = injectDeps(MainLayout);

  FlowRouter.route('/', {
    name: 'posts.list',
    action() {
      mount(MainLayoutCtx, {
        content: () => (<PostList />)
      });
    }
  });
}

2.10Libraries

Every app has some utility functions to do different tasks. You can also get them via NPM. These libraries will export functions. So, you can import them anywhere in your app including inside actions, components, and containers.

> When using a library function inside a component, it should be pure.

2.11Testing

Testing is a core part of Mantra. Mantra helps you test every part of your application. Rules we’ve enforced will help you write those tests. You can use familiar tools such as Mocha, Chai, and Sinon to perform testing.

With Mantra, you can unit test three core parts in your app. See:

• UI components - Example
• Actions - Example
• Container composers and deps mappers - Example

2.12Mantra Modules

Mantra follows a modular architecture. All the components of Mantra except “Application Context” should reside inside a module.

You can create as many as modules you like and communicate between them via imports.

export default {
  // optional
  load(context, actions) {
    // do any module initialization
  },
  // optional
  actions: {
    myNamespace: {
      doSomething: (context, arg1) => {}
    }
  },
  // optional
  routes(injectDeps) {
    const InjectedComp = injectDeps(MyComp);
    // load routes and put `InjectedComp` to the screen.
  }
};

2.13Single Entry Point

With Mantra, we want our app to be predictable. Therefore, there is a single entry point in your app. That’s the client/main.js.

It’ll initialize the Application Context and load all the modules in your app. Here’s an example client/main.js file:

import {createApp} from 'mantra-core';
import {initContext} from './configs/context';

// modules
import coreModule from './modules/core';
import commentsModule from './modules/comments';

// init context
const context = initContext();

// create app
const app = createApp(context);
app.loadModule(coreModule);
app.loadModule(commentsModule);
app.init();

3.1Top-Level Directory Structure

All the Mantra‐related code stays inside the client directory of the app. Inside that, there are usually two directories and one JavaScript file. They are:

* configs
* modules
* main.js

Let’s have a look at each of these in detail.

* actions
* components
* configs
* containers
* libs
* routes.jsx
* index.js

* posts.js
* index.js
* tests
    - posts.js

export default {
  create({Meteor, LocalState, FlowRouter}, title, content) {
    //...
  },

  clearErrors({LocalState}) {
    //...
  }
};

import posts from './posts';

export default {
  posts
};

* main_layout.jsx
* post.jsx
* style.css
* tests
  - main_layout.js
  - post.js

* post.js
* postlist.js
* tests
    - post.js
    - postlist.js

export default function (context) {
  // do something
}

import React from 'react';
import {FlowRouter} from 'meteor/kadira:flow-router';
import {mount} from 'react-mounter';

import MainLayout from '/client/modules/core/components/main_layout.jsx';
import PostList from '/client/modules/core/containers/postlist';

export default function (injectDeps) {
  const MainLayoutCtx = injectDeps(MainLayout);

  FlowRouter.route('/', {
    name: 'posts.list',
    action() {
      mount(MainLayoutCtx, {
        content: () => (<PostList />)
      });
    }
  });
}

import methodStubs from './configs/method_stubs';
import actions from './actions';
import routes from './routes.jsx';

export default {
  routes,
  actions,
  load(context) {
    methodStubs(context);
  }
};

import {createApp} from 'mantra-core';
import initContext from './configs/context';

// modules
import coreModule from './modules/core';
import commentsModule from './modules/comments';

// init context
const context = initContext();

// create app
const app = createApp(context);
app.loadModule(coreModule);
app.loadModule(commentsModule);
app.init();

4.1Server-Side Rendering (SSR)

It’s extremely possible to do SSR with Mantra. We are trying to do this in a tool‐agnostic manner, but the reference implementation will be based on FlowRouter SSR.

4.2Distributing Mantra Modules via NPM

We could distribute Mantra modules via NPM. Once we do that, we could do reuse a lot of code between apps and organizations.

4.3Standard for Styling

It’s better to have a standard for styling UI components.

4.4Standard for Tests

It’s better to have a standard for writing test cases.

4.5Reusing Composers

Sometimes, we can use reuse composers for the same function in many places. We need to find a pattern for doing that.

A.1ES2015

ES2015 is the standard version of JavaScript for 2015. It’s not fully implemented by all browsers or server‐side environments. But, using transpilers like babel, we can use E2015 today.

ES2015 is the best thing happen to JavaScript. It introduces a lot of features and fixes a lot of common issues.

• Learn ES2015: Say Hello to ES2015

A.2React

React is a UI framework based on JavaScript. Basically, you create the UI inside JavaScript. At first, it feels weird. But you’ll find it very interesting once you learn the basics.

Just forget about what you already know about HTML for a moment, and learn React. Then rethink. Here are some resources:

• Official Tutorial
• Getting Started Tutorial at Scotch.io
• React Components, Elements, and Instances

A.3React Containers

Now, we rarely use states in React components. Instead, we accept data via props. React’s stateless components make it very easy.

Then, we compose React containers to fetch data from different sources and load them into UI components. Projects like react‐komposer make it simple. Check out the following article for more information:

• Let’s Compose Some React Containers

A.4Meteor Basics

You need to have a better understanding of Meteor. For that, follow Meteor’s official tutorial.

B.1methods

This is the directory where we can put methods in your app. This is how the files in this directory look like:

* posts.js
* index.js
* tests
  - posts.js

Here we have a file called posts.js which has methods for the feature posts in our app. Depending your app, we can have different files.

Inside this JavaScript file, we have a default export which is a function. Meteor methods are defined inside that function.

When naming methods inside the posts.js, always prefix the method name. That prefix is the name of the file with a dot (.).

In our case, the prefix is posts.

For an example, here are some methods inside posts.js:

import {Posts, Comments} from '/lib/collections';
import {Meteor} from 'meteor/meteor';
import {check} from 'meteor/check';

export default function() {
  Meteor.methods({
    'posts.create'(_id, title, content) {
      //  method body
    }
  });

  Meteor.methods({
    'posts.createComment'(_id, postId, text) {
      //  method body
    }
  });
}

Finally, there is a file called index.js which imports all other modules in this directory and invokes them in a default export. So, when importing methods, we can do it with a single import.

Here’s a sample index.js file:

import posts from './posts';
import admin from './admin';

export default function () {
  posts();
  admin();
}

B.2publications

This directory is identical to the methods directory, but we write publications instead of methods.

B.3libs

This directory contains utility functions which we can use inside the server.

B.4configs

This is the place where we can write configurations in our app. These configuration files should have a default export function which can be imported and invoked. Configuration code should stay inside that function.

Here’s an example configuration:

export default function() {
  //  invoke the configuration here
}

B.5main.js

This is the place where we can start as the entry point for our app. We’ll import methods, publications and configuration inside this file and invoke.

Here’s an example main.js file:

import publications from './publications';
import methods from './methods';
import addInitialData from './configs/initial_adds.js';

publications();
methods();
addInitialData();

C.1Single Core Module

For a simple app, we can put all the code inside a single module and name it as core. This would work for a simple app where there is a smaller client‐side codebase.

C.2Core Module & Multiple Feature Modules

This is an extended version of the above “Single Module App” pattern. Here it is:

• We have a core module containing all the core client‐side code, including all the routes in the app.
• Then we have different modules for major features in our app. These modules do not contain routes.

C.3Multi Modules

This the multi‐module approach where there is no single core module.

• There are multiple modules for each main feature in the app.
• Each of them has its own route.

C.4Pages Module

Sometimes, we need to show some UI pages. They don’t have their own actions, routes, or configurations. They only contain some UI code. These can be either UI components or some containers.

For this purpose, we can use an implicit module.

D.1Source File Names

When we remove the extension from the filename it should satisfy following conditions:

• All letters should be lower case.
• Filename should be alphanumeric and can have the _ symbol.
• Filename should start with a letter.

Here’s the regular expression for the above rules:

/^[a-z]+[a-z0-9_]+$/

D.2Test File Names

This is how we name files inside the tests directory. Here are the rules:

• There should be an identical filename in the source directory.
• If not, when removing the postfix, there should be an identical filename in the source directory.

posts-part1.js
posts-part2.js

/^([a-z]+[a-z0-9_]+)(\-[a-z]+[a-z0-9_]+)*$/