En développement ne pas utiliser en production

Midgar

Qu'est ce que Midgar

Midgar est un framework nodejs modulaire utilisant le pattern Model View-Controller Service (MVCS). Il se base sur un système de plugin pour permettre de réaliser rapidement des applications web complexes de manière claire et structuré.

Démarrage

Le moyen le plus rapide de démarrer avec Midgar est d'utiliser le CLI pour générer la structure d'un projet.

$ npm install -g @midgar/midgar
$ midgar init ~/mon-projet/
$ cd ~/mon-projet/
$ npm i

En soit Midgar ne fait que charger des plugins, sans plugin, il ne fait donc rien de concret ! L'étape suivante est donc d'installer des plugins ou d'en créer un. L'installation des plugins se fait via npm ou yarn. L'utilisation des scripts de npm permet l'activation automatique des plugins sur le projet.

Vous pouvez voir la structure du projet générer par la commande init ici.

Documentation

documentation Api.

Plugins

Créer un plugin

Le CLI vous permet de générer la structure d'un plugin et de l'activer:

$ cd ~/mon-projet/
$ midgar new @ns/blog
$ npm update

Fichier plugin

Voici le fichier plugin généré par la command:

import { Plugin } from '@midgar/midgar'

/**
 * BlogPlugin class
 */
export default class BlogPlugin extends Plugin {
  /**
   * Init plugin
   */
  init () {

  }
}

La méthode init est appelée automatiquement au chargement des plugins. Elle sert notament à écouter les évènements:

init () {
  this.mid.on('@midgar/midgar:afterInitPlugins', async () => {
    // Ceci est exécuté une fois que tous les plugins ont été initialisé.
  })
}

Vous pouvez retouver la liste des évènements dans la documentation.

Package npm

Un plugin est en premier lieu un package npm et doit etre forcement accompagné d'un fichier package.json. Le main du package.json doit pointer sur le fichier plugin.

Pour fonctionner il doit aussi etre déclarré dans le fichier plugins.json contenu dans le dossier de configuration du projet. Les scripts postinstall et preuninstall peuvent être utiliser pour ajouter/supprimer automatiquement les plugins du fichier plugins.json.

Configuration du plugin

Vous pouvez ajouter un fichier plugin-config.js dans le même dossier que le fichier plugin.

Ce fichier est chargé avant le chargement des plugins et est injecté dans la proprité .config de l'instance du plugin. Voici un exemple:

export default {
  moduleTypes: {
    'midgar-mongo-model': 'models',
  }
}

Modules

Le système de plugin comprend un importer de modules. Vous pouvez déclarrer un type de module a importer dans la methode init de votre plugin:

import { Plugin } from '@midgar/midgar'

export default class TestPlugin extends Plugin {
  init () {
    this.pm.addModuleType('mon-type', 'mondossier')
  }
}

mon-type corréspond à l'identifiant du type de module.

modossier corréspond au chemin par défaut du dossier contenant ce type de modules.

@see: https://midgarjs.github.io/midgar/PluginManager.html#addModuleType__anchor

Pour importer les modules:

import { Plugin } from '@midgar/midgar'

export default class TestPlugin extends Plugin {
  init () {
    this.mid.on('@midgar/midgar:afterInitPlugins', async () => {
      const files = await this.mid.pm.importModules('mon-type', '**/*.js')
      ...
    })
  }
}

@see: https://midgarjs.github.io/midgar/PluginManager.html#importModules__anchor

La méthode importModules importe tous les modules mon-type pour tous les plugins.

Le chemin du dossier mon-type est par défaut ./mondossier/ relativement par rapport au fichier plugin.

La méthode importModules renvoit un tableau d'object:

[
  {
    path: '~/mon-projet/src/plugins/test-plugin/mondossier/fichier.js',
    export: ... // La valeur export default du fichier
    plugin: 'test-plugin',
    relativePath: 'fichier.js'
  },
  ...
}

Le chemin du dossier mon-type peut etre configuré pour chaque plugin dans le fichier plugin-config.js:

export default {
  moduleTypes: {
    'mon-type': 'mon/nouveau/dossier',
  }
}

ou

export default {
  moduleTypes: {
    'mon-type': {
      path: 'mon/nouveau/dossier',
      glob: '**/*.js',
      ignore: '**/*.schema.ks'
  }
}

Réecriture

Si un plugin ne fait pas axactement ce dont vous avez besoin, ou bien si vous voulez enrichir les fonctionnalitées d'un plugin, vous pouvez utiliser le système de réecture. Les plugins ainsi que les modules importé via la méthode importModules sont réecrivable.

Plugin

Pour réecrire un plugin, ajouter ceci dans le fichier plugin-config.js.

export default {
    rewrite:{
      plugin: '@midgar/service'
    }
  }
}

Lors du chargement des plugins, ce plugin sera chargé à la place du plugin @midgar/service.

Le plugin devrait ressembler à ceci:

import ServicePlugin from '@midgar/service'

export default class RewritePlugin extends ServicePlugin {
  async init () {
    await super.init()
    ....
  }
}

Module

Pour réecrir un module importé via la méthode importModules, ajouter ceci dans le fichier plugin-config.js.

export default {
  rewrite: {
    modules: {
      "midgar-mongoose-models": { // Type de module
        "@midgar/graphql-auth": { // nom du plugin a réecrire
          'user.js': './rewrite/models/user.js' // chemin du fichier a réecrire: chemin du module de remplacement
        }
      }
    }
  }
}

Lors de l'import des modules, le modules ./rewrite/models/user.js sera chargé à la place du modules user.js contenu dans le dossier midgar-mongoose-models et pour le plugin @midgar/graphql-auth

Réécriture et plugin local

La réecriture n'est pas supporté pour les plugins locaux. Les plugins locaux doivent etre uniquement utilisé pour le développement et les testes. Lorsque Midgar charge un plugin local, il utilise les fichiers du dossier local et non le dossier node_modules. Si un autre plugin import un module directement par son chemin, node importera le fichier dans le dossier node_modules.

Cli

Voici les commandes de base du cli

init:

$ midgar init ./mon-projet

Crée un projet Midgar dans le dossier ./mon-projet.

new:

$ midgar new

Crée un nouveau plugin local.

add:

$ midgar add monplugin

Ajoute un plugin au fichier plugins.json contenu dans le dossier de configuration du projet.

rm:

$ midgar rm @migar/service

Supprime le plugin @migar/service du fichier plugins.json.

enable:

$ midgar enable @migar/service

Active un plugin présent dans le fichier plugins.json. Si le plugin n'est pas présen, il n'est pas ajouté et un avertisement est affiché.

disable:

$ midgar disable @migar/service

Désactive le plugin @migar/service dans le fichier plugins.json. Si le plugin n'est pas présent, il n'est pas ajouté et un avertisement est affiché.

Paramètre optionnel:

$ midgar add @migar/service --config ~/mon-projet/src/config

Vous pouvez ajouter le chemin de la configuration du projet au cli. Par defaut, le cli cherche un fichier .midrc contenant le chemin de la configuration. S'il ne trouve pas ce fichier il cherche dans ./config.

Vous pouvez voir un exemple de fichier .midgarrc.js ici