Jumpstart plugin
A plugin to download and set up a new headless or FreeMarker-based project with a Magnolia webapp.
The plugin is designed to start new projects using predefined templates and bundles. It allows you to choose a template and download the associated bundles while performing the necessary tasks such as authentication, bundle downloading, extraction, and post-command execution.
Package name |
|
Repository link |
|
Latest version |
|
Changelog link |
Installing
This plugin comes pre-installed and ready to be used.
You must install it manually for use in an already initialized project (containing the mgnl.config.js file).
|
Usage
Options
| Form (short and long) | Description |
|---|---|
|
Sets the Magnolia version for your project. By default, it uses the latest stable version. |
|
Downloads the latest snapshot version of the webapp specified. |
|
Sets a template from the available project templates. |
|
Specifies the source location to load the project templates from. |
|
Displays the version. |
|
Displays help information. |
Examples
Jumpstarting a project
npx @magnolia/cli jumpstartThis command will prompt you to choose a template from a list of available templates.
Once you select a template, the CLI will download and configure the project using the latest Magnolia version (or with a version associated with that template).
Jumpstarting a project with a specific Magnolia version
npx @magnolia/cli jumpstart --magnolia "6.2.11"This command will prompt you to choose a template from a list of available templates.
Once you select a template, the CLI will download and configure the project for Magnolia 6.2.11.
Jumpstarting a project with a snapshot Magnolia version
npx @magnolia/cli jumpstart --snapshotThis command will prompt you to choose a template from a list of available templates.
Once you select a template, the CLI will download and configure the project for use with the latest snapshot Magnolia version.
Jumpstarting a project with a specific template
npx @magnolia/cli jumpstart --template "standard-webapps/magnolia-community-webapp"This command will use the standard-webapps/magnolia-community-webapp template to download and configure the project for use with the latest Magnolia version.
Jumpstarting a project based on a custom template
npx @magnolia/cli jumpstart --project-templates "./path/to/custom-project-templates.json"This command will prompt you to choose a template from the ./path/to/custom-project-templates.json file.
Once you select a template, the CLI will download and configure the project for use with the latest Magnolia version (or with a version associated with that template).
In the source option (--project-templates <source>), you can also specify a URL pointing to a JSON file, for example a raw file stored in public Git repository.
|
Extensions
The extensions is a functionality in this plugin that allows developers to create a more interactive and automated project setup process, making it easier for the users to set up a new Magnolia project.
Extension YAML configuration file
The plugin searches for the <rootdir>/extensions/extension.yaml file in your project directory:
The file defines the additional prompts and post-command functions which can be helpful for tailoring the plugin’s functionality to specific requirements of your project.
File structure
The YAML file typically contains the following key sections:
-
extend: Specifies a JavaScript file that the extension will tie into for additional logic or configuration. -
prompts: A series of input prompts to gather the necessary information from the user. Each prompt can specify:-
type: The type of prompt, such asinputfor user text input. -
name: The internal name used to reference the data collected. -
message: The message displayed to the user during the prompt. -
default: The default value for the prompt, used if the user provides no input.
-
-
commands: Actions to be taken after the prompts have been completed, such as:-
post: Commands to be executed after the setup process. This could involve downloading the dependencies, setting up environment variables, and so on.
-
Example
extend: ./example.js
prompts:
- type: input
name: clientId
message: Client ID
default: clientId_001
- type: input
name: organizationId
message: Organization Id
default: organizationId_001
- type: input
name: siteId
message: Site Id
default: siteId_001
commands:
post:
- function: example
retry: 3
delay: 1000Execution flow
Upon project initialization, if an extension file is detected, the Jumpstart plugin executes the following steps:
-
Input Gathering: It asks the user for input based on the
promptsdefined in the extension’s YAML file. -
Configuration Integration: The plugin retrieves the main
package.jsonfile. The responses gathered from the prompts are then added to this configuration object under theanswersproperty.This augmented
package.jsonobject is then used to automatically populate the corresponding placeholders within your project files. -
Post-Command Execution: Each
post-commandfunction specified in the YAML file is executed. These functions have access to thepromptsobject, which contains the user’s responses, allowing the functions to perform tasks that are tailored to the user’s input.
Customization example
After gathering the inputs, a file with placeholders, for instance,
// config.js
export default {
clientId: <%=answers.siteId%>,
organizationId: <%=answers.organizationId%>,
siteId: <%=answers.siteId%>
};is transformed into the following:
// config.js
export default {
clientId: clientId_001,
organizationId: organizationId_001,
siteId: siteId_001
};