Philosophy

• Standard is god.
• It only do following:
  • Define folder structure
  • Define where to load config
  • Define how to setup and teardown modules
  • Define how to pass around module
• Everything else is up to you.

Status

API might change for all Magnet modules.

Module boilerplate

import Base from "magnet-core/dist/base";

export default class Module extends Base {
  init() {
    /*
      E.g. You can put @google/maps | apollo-server-express | apollo-server,
      it will format to snake case _google_maps | apollo_server_express | apollo_server.
      So we can use it as _google_maps.geocode({ address: '1600 Amphitheatre Parkway, Mountain View, CA' }).
      It's a Magnet practice to use npm module name for scoping, to reduce clash on namespace
    */
    this.moduleName = "<module npm name>";

    // Optional, path of default config folder
    this.defaultConfig = __dirname;
  }

  /**
   * Code to setup the module, either:
   * - Add module to this.app object
   * - Add middleware to this.app.application
   */
  async setup() {
    this.app.module = {};
  }

  /**
   * How to handle shutdown
   * Not implement yet
   */
  async teardown() {
    this.app.module = {};
  }
}

Folders structure

• docs
• local_modules
• src
  • builds
  • config
  • controllers
  • database
  • models
  • queues
  • routers
  • graphql
  • tcp
  • command
  • ws
  • schedulers
  • schemas
  • services
  • templates
  • utils
• static
• tests

App structure

App = {
  config: // magnet-config
};

Modules

Allow Magnet module is searchable under magnetjs keywords NPM search

Usage

es6

import magnet from "magnet-core";
import Config from "magnet-config";
import Logger from "magnet-bunyan";
import Router from "magnet-router";
import FileLoader from "../local_modules/file_loader";

magnet([
  Config,
  Logger,
  Router,
  {
    module: FileLoader,
    options: ""
  }
]);

es5

var magnet = require("magnet-core").default;

magnet([
  require("magnet-config").default,
  require("magnet-bunyan").default,
  require("magnet-router").default,
  {
    module: require("../local_modules/file_loader").default,
    options: ""
  }
]);

Magnet style

import magnet, { from, fromLocal } from "magnet-core";

magnet([
  from("magnet-config"),
  from("magnet-bunyan"),
  from("magnet-router"),
  fromLocal("file_loader")
]);

Example

Scheduler Server

import magnet from "magnet-core";
import Config from "magnet-config";
import Logger from "magnet-bunyan";
import Kue from "magnet-kue";

magnet([Config, Logger, Kue]);

API Server

import magnet from "magnet-core";
import Config from "magnet-config";
import Logger from "magnet-bunyan";
import Spdy from "magnet-spdy";
import Common from "magnet-server-common";
import Helmet from "magnet-helmet";
import Router from "magnet-router";
import Controller from "magnet-controller";
import Mongoose from "magnet-mongoose";
import Session from "magnet-redis-session";
import Respond from "magnet-respond";
import FileLoader from "../local_modules/file_loader";

magnet([
  Config,
  Logger,
  Spdy,
  [Respond, Session, Common, Helmet, Router, Mongoose],
  Controller,
  {
    module: FileLoader,
    options: ""
  }
]);

Scheduler Server

import magnet, { from, fromLocal } from "magnet-core";

magnet([
  fromM("config"),
  fromM("bunyan"),
  fromM("file_loader"),
  fromM("sequelize"),
  fromM("sequelize", {
    namespace: "sequelizeAnotherDb",
    database: "anotherDb"
  })
]);

// app.sequelize.query(...)
// app.sequelizeAnotherDb.query(...)

Multiple instance

import magnet from "magnet-core";
import Config from "magnet-config";
import Logger from "magnet-bunyan";
import Kue from "magnet-kue";

magnet([Config, Logger, Kue]);

Naming

All magnet module is store under app variables. To avoid conflict some rules is introduced.

• magmet, config, log is reserved
• npm organization scope replaced with underscore

// Reserved
const app = {
  magnet: null,
  config: null,
  log: null
};

this.app.koa = new Koa();
this.app._googleMaps = require("@google/maps").createClient({
  key: "your API key here"
});

CLI

Magnet come with cli command to copy all config files from following to server/config:

• local_modules/**/config/*.js
• node_modules/**/config/*.js

Just run from ./node_modules/.bin/magnet

Or install globally npm install -g magnet-core yarn global add magnet-core And run magnet

Roadmap

v5

• Find solution to copy config/* without babel
• DI support with https://github.com/jeffijoe/awilix
• Function based module structure
• Draft

v6

• Support serverless
• Auto update config/*.js when extra field introduced

Todo

• Why copyConfig doesn't get magnet-koa/config/koa
• Auto build modules structure via npm dependencies