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

To function correctly, plugins may:

  • Prompt you for values of required properties, if not already set and present in mgnl.config.js.

  • Save those properties to the configuration file.

  • Prompt you again if the properties are later removed from the configuration file.

For more details about the required properties, see the respective plugin documentation page.

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"

Windows users using PowerShell must enclose the two consecutive hyphens (--) in quotes:

npm run mgnl "--" ...

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

Windows users using PowerShell must enclose the two consecutive hyphens (--) in quotes:

npm run mgnl "--" ...

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'

Windows users using PowerShell must enclose the two consecutive hyphens (--) in quotes:

npm run mgnl "--" ...

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:

  1. 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'

    Windows users using PowerShell must enclose the two consecutive hyphens (--) in quotes:

    npm run mgnl "--" ...

    It has the highest priority and overrides/sets the value in the mgnl.config.js file.

  2. 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'
    })
  ],
  ...
};

  3. 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'
    })
  ],
  ...
};

  1. Using an option

    Running following command

    npm run mgnl -- create-app "my-app" --light-module "my-lm-3"

    Windows users using PowerShell must enclose the two consecutive hyphens (--) in quotes:

    npm run mgnl "--" ...

    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.

  2. Using a plugin argument

    Running following command

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

    Windows users using PowerShell must enclose the two consecutive hyphens (--) in quotes:

    npm run mgnl "--" ...

    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.

  3. 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"

    Windows users using PowerShell must enclose the two consecutive hyphens (--) in quotes:

    npm run mgnl "--" ...

    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.

Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the Magnolia CLI docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules