Watch mode
Watch mode lets Magnolia CLI watch your project files and re-run selected plugins whenever matching files are created, changed, or deleted. The watchers are managed entirely by the CLI. Plugins don’t manage the watchers themselves.
How it works
-
The CLI detects the
watch-modecommand and reads thewatchModeconfiguration frommgnl.config.jsor uses the--use-configoption. -
It configures file watchers for each enabled plugin and their
watchPaths. -
When a change is detected, the CLI logs the change and the plugin to be executed, then invokes the plugin as usual.
-
Plugins run exactly as they do when invoked manually. The CLI re-invokes the plugin and passes the changed file paths as
source.
The following are ignored by default at any directory level: /node_modules/, /.git/, /dist/, /build/, and /mgnl.error.log.
|
Running a watch mode
Prerequisites
-
Define
watchModefor at least one plugin inmgnl.config.js, or use the--use-configoption.
Start all configured watchers
npm run mgnl -- watch-mode|
Windows users using PowerShell must enclose the two consecutive hyphens ( |
| On first runs, keep an eye on the CLI logs. Some plugins may prompt for input (for example, confirmations or additional options), and you could miss the prompt if the terminal isn’t in focus. |
Start a watch mode
-
With an inline configuration
npm run mgnl -- watch-mode --use-config "CreateRestEndpointPlugin"If no watch paths are specified for a plugin, the CLI defaults to **/*.yaml. This pattern searches relative to the current working directory where the CLI is executed. -
With custom watch paths for plugins
npm run mgnl -- watch-mode --use-config "CreateRestEndpointPlugin::**/apps/*.yaml::**/dialogs/**/*.yaml" -
With multiple plugins with different configurations
npm run mgnl -- watch-mode --use-config "CreateRestEndpointPlugin::**/apps/*.yaml" "CreateModelPlugin::**/dialogs/**/*.yaml"
Example configuration (mgnl.config.js)
export default {
...
plugins: [
new CreateRestEndpointPlugin({...}),
new CreateModelPlugin({...})
],
watchMode: {
CreateRestEndpointPlugin: {
enabled: true,
watchPaths: [
'**/dialogs/**/*.yaml',
'**/contentTypes/*.yaml',
'**/apps/*.yaml',
],
},
CreateModelPlugin: {
enabled: true,
watchPaths: '**/dialogs/**/*.yaml'
}
}
};watch-mode options
-
-uc, --use-config [configs…]: Specify plugin configurations. The format is:<plugin-name>[::<watch-path1>…].
Examples:
-
"CreateRestEndpointPlugin" -
"CreateRestEndpointPlugin::**/apps/*.yaml::**/dialogs/**/*.yaml"
Configuration format
The --use-config option accepts plugin configurations in the format:
<plugin-name>[::<watch-path1>[::<watch-path2>…]]
-
Plugin name only: Uses the default watch paths (
**/*.yaml). -
Plugin with paths: Uses specified watch paths separated by
::.
Use double colons (::) to separate the plugin name from the watch paths.
Single colons (:) will not work correctly.
|
Path exclusion
The CLI automatically validates and excludes problematic paths that match:
-
/node_modules/ -
/.git/ -
/dist/ -
/build/ -
/mgnl.error.log
This validation applies to both --use-config and mgnl.config.js configurations.
If you specify excluded paths, the CLI will warn you and fall back to the default watch paths.