Configuring plugins

Magnolia CLI comes with a default configuration you can override by placing the mgnl.config.js file in the project directory. Use this file to:

import and initialize custom plugins
customize the logger
manage CLI usage analytics

Basic mgnl.config.js structure:

export default {
  plugins: [],
  logger: {
    filename: "./mgnl.error.log",
    fileLevel: "warn",
    consoleLevel: "debug"
  },
  analytics: {
    enabled: true,
    uuid: "<random-projects-uuid-v4>"
  }
};

The `plugins` property

The plugins property allows you to handle the plugins. In the following example, the property is used to add the cli-foo-plugin to the CLI.

import FooPlugin from "cli-foo-plugin";

export default {
  plugins: [
    new FooPlugin()
  ],
  ...
};

The `logger` property

The logger property allows you to modify the CLI logging behavior for both the CLI and its plugins.

You can customize your logging preferences as follows:

Adjust the log file’s name using the filename property.
Set the logging levels for:
- files, by updating the fileLevel property,
- the console, by updating the consoleLevel property.
  
  For more details about logging levels, see the winston npm package and its documentation.

export default {
  logger: {
    filename: "./mgnl.error.log",
    fileLevel: "warn",
    consoleLevel: "debug"
  },
  ...
};

The `analytics` property

With the analytics property, you can enable or disable anonymous analytics collection. By allowing it you help us improve the CLI and the plugins. For more details about what information is collected, see the Analytics page.

export default {
  analytics: {
    enabled: true,
    uuid: "<random-projects-uuid-v4>"
  },
  ...
};

Global and plugin properties

Global

Some plugin properties are accessible to more plugins, they are global in this sense. For example:

lightModulesPath - the path to all light modules
lightModule - a specific light module you want to work with

Therefore, these properties can be set in mgnl.config.js and each plugin loads them then.

Example

If the mgnl.config.js file contains the following,

import CreateContentTypePlugin from "@magnolia/cli-create-content-type-plugin";
import CreateAppPlugin from "@magnolia/cli-create-app-plugin";

export default {
  lightModulesPath: './light-modules',
  lightModule: 'my-lm',
  plugins: [
    new CreateContentTypePlugin(),
    new CreateAppPlugin()
  ],
  ...
};

and you run the create-app command,

npm run mgnl -- create-app "my-app"

a new my-app is created in the ./light-modules/my-lm directory.

Plugin

Some plugins allow you to pass arguments when the plugin is initialized, for example:

tomcatPath in the Start plugin - sets the path of the Apache Tomcat with a Magnolia webapp

Example

mgnl.config.js

import StartPlugin from "@magnolia/cli-start-plugin";

export default {
  lightModulesPath: './light-modules',
  lightModule: 'my-lm',
  plugins: [
    new StartPlugin({
      tomcatPath: './magnolia/apache-tomcat'
    }),
  ],
  ...
};

If you run,

npm run mgnl -- start

Apache Tomcat located in the ./magnolia/apache-tomcat directory starts.

You can override a plugin’s argument with an option, for example:

npm run mgnl -- start --tomcat-path './apache-tomcat'

Tomcat will start from ./apache-tomcat and the value will be updated in the mgnl.config.js file.

Value priorities

The priority of values is set as follows, from the highest to the lowest:

option value - a value provided by an option (-plugin-option option-value), for example:
```
npm run mgnl -- create-app "my-app" --light-module 'my-lm3'
```
It has the highest priority and overrides/sets the value in the mgnl.config.js file.

plugin argument - a value set in the mgnl.config.js file in the plugin, for example:

import CreateAppPlugin from "@magnolia/cli-create-app-plugin";

export default {
  ...
  plugins: [
    new CreateAppPlugin({
      lightModule: 'my-lm-2'
    })
  ],
  ...
};

global argument - a global value set in the mgnl.config.js file:
```
export default {
  lightModule: 'my-lm',
  ...
};
```

Examples

mgnl.config.js

import CreateApp from "@magnolia/cli-create-app-plugin";

export default {
  lightModulesPath: './light-modules',
  lightModule: 'my-lm',
  plugins: [
    new CreateApp({
      lightModule: 'my-lm-2'
    })
  ],
  ...
};

Using an option

Running following command
```
npm run mgnl -- create-app "my-app" --light-module "my-lm-3"
```
generates a new my-app in ./light-modules/my-lm-3, and also overrides my-lm-2 with my-lm-3 in the mgnl.config.js file.
Using a plugin argument

Running following command
```
npm run mgnl -- create-app "my-app"
```
generates a new my-app in ./light-modules/my-lm-2 Because the lightModule: 'my-lm-2' is set in the CreateApp plugin argument in the mgnl.config.js file.
Using a global argument

If you remove the lightModule: 'my-lm-2' part from the CreateApp plugin argument in mgnl.config.js and execute
```
npm run mgnl -- create-app "my-app"
```
a new my-app is created in ./light-modules/my-lm because lightModule: 'my-lm' is set as a global argument in mgnl.config.js.

Configuring plugins

The plugins property

The logger property

The analytics property

Global and plugin properties

Global

Example

Plugin

Example

Value priorities

Examples

Location

Main doc sections

The `plugins` property

The `logger` property

The `analytics` property