Using ProjectTemplates

The Jumpstart plugin relies on ProjectTemplate - a file which defines a structured template of items and plugins to be downloaded, actions to be executed after download, and other project configuration.

By default, the plugin leverages the projectTemplates.json file. You can create your own project template to define your custom templates for your developers.

To use a custom project with the Jumpstart plugin, append --project-templates <source> to the command.

Creating a custom ProjectTemplate

Templates simplify preparation of a project. In projectTemplates, a project points to resources such as Apache Tomcat, Magnolia bundles, or various frontend projects.

Structure and types

The templates file structure provides an organized way to represent project templates. Below is a breakdown of its structure and the types used:

Template interfaces

interface TemplateBase {
    name: string; (1)
    auth?: boolean;
}

interface TemplateWithChildren extends TemplateBase {
    children: Array<Template>(4)
    bundles?: never;
    plugins?: never;
}

interface TemplateWithBundles extends TemplateBase {
    bundles: Array<Bundle>(2)
    children?: never;
    plugins?: never;
}

interface TemplateWithPlugins extends TemplateBase {
    plugins: Array<PluginRequirement>(3)
    bundles?: never;
    children?: never;
}

interface TemplateWithBundlesAndPlugins extends TemplateBase {
    bundles: Array<Bundle>(2)
    plugins: Array<PluginRequirement>(3)
    children?: never;
    configVars?: {[key: string]: any}; (5)
}

type TemplateWithoutChildren =
    | TemplateWithBundles
    | TemplateWithPlugins
    | TemplateWithBundlesAndPlugins;

type Template = TemplateWithChildren | TemplateWithoutChildren;
1 A unique name for the project template.
2 An array of bundles or resources that the template references and downloads.
3 An array of plugins for CLI that will be installed with the template.
4 An array of project templates that provides a hierarchical structure of the project templates.
5 A configuration object that will be automatically extracted and added to the mgnl.config.js file as global arguments. It should contain key-value pairs.

Bundle interface

interface Bundle {
    url: string; (1)
    auth?: boolean; (2)
    dest?: string; (3)
    postCommand?: string[]; (4)
    version?: string; (5)
    noVersion?: boolean; (6)
    alternative?: {
      groupId: string,
      artifactId: string
    }
}
1 A URL where the bundle or resource can be downloaded from.
2 (optional): Set to true if the URL endpoint requires an authentication.
3 (optional): Specifies where the resource should be downloaded and/or extracted to.
4 (optional): An array of commands to be executed after downloading the bundle. Commands available:

  • extract: Extract the resource after it’s been downloaded.

  • extract and unfold: Extract the contents of a compressed folder directly into the destination folder.

  • extract and override: Extract the resource without checking whether it exists already. This is useful for Magnolia webapp updates in Tomcat.

  • npm install: Execute the npm install command in the downloaded frontend project.
5 (optional): Set to a specific Magnolia version. By default, the latest version is always downloaded.
6 (optional): If set to true, the latest version is fetched, providing that the git tags are available.

PluginRequirement interface

interface PluginRequirement {
    plugin: string, (1)
    pluginArgs: object (2)
}
1 A reference required to install a particular package. It can be either the URL of a git repository or the name of a plugin available in the npm repository. String pattern: npm install <plugin>.
2 This refers to a configuration object that will be automatically extracted and passed as an argument during the instantiation of the plugin. It should contain key-value pairs.
To use a specific version of a package, include <name>@<version> in the plugin property.

Example templates

Example A

A projectTemplates.json that provides a template to download:

  • the latest Tomcat,

  • Magnolia DX Core,

  • the Next.js frontend,

and add various plugins to the available plugins:

Click to see the JSON

{
  "projectTemplates": [
    {
      "name": "headless",
      "children": [
        {
          "name": "minimal-headless-spa-demos",
          "children": [
            {
              "name": "dx-core",
              "bundles": [
                {
                  "url": "https://bitbucket.org/magnolia-cms/minimal-headless-spa-demos/get/HEAD.zip",
                  "postCommand": [
                    "extract and unfold"
                  ]
                },
                {
                  "url": "https://nexus.magnolia-cms.com/service/rest/v1/search/assets?sort=version&repository=public&maven.groupId=info.magnolia.tomcat.barebone&maven.artifactId=magnolia-tomcat-barebone&maven.extension=zip",
                  "dest": "./magnolia",
                  "postCommand": [ "extract" ]
                },
                {
                  "url": "https://nexus.magnolia-cms.com/service/rest/v1/search/assets?sort=version&repository=enterprise&maven.groupId=info.magnolia.dx&maven.artifactId=magnolia-dx-core-webapp&maven.extension=war",
                  "auth": true,
                  "version": "latest",
                  "dest": "./magnolia/apache-tomcat/webapps/magnoliaAuthor",
                  "postCommand": [
                    "extract and override"
                  ]
                }
              ],
              "plugins": [
                {
                  "plugin": "@magnolia/cli-start-plugin",
                  "pluginArgs": {
                    "tomcatPath": "./magnolia/apache-tomcat"
                  }
                },
                {
                  "plugin": "@magnolia/cli-create-component-plugin",
                  "pluginArgs": {
                    "componentsSpaPath": "./spa/nextjs-ssr-minimal/templates/components",
                    "framework": "@magnolia/cli-react-prototypes",
                    "prototype": "_default"
                  }
                },
                {
                  "plugin": "@magnolia/cli-create-page-plugin",
                  "pluginArgs": {
                    "pagesSpaPath": "./spa/nextjs-ssr-minimal/templates/pages",
                    "framework": "@magnolia/cli-react-prototypes",
                    "prototype": "_default"
                  }
                }
              ],
              "configVars": {
                "type": "js",
                "lightModulesPath": "./magnolia/light-modules",
                "lightModule": "nextjs-ssr-minimal-lm",
                "componentMappingFilePath": "./spa/nextjs-ssr-minimal/pages/[[...pathname]].js"
              }
            }
          ]
        }
      ]
    }
  ]
}

Example B

A projectTemplates.json that provides a template to:

  • download and install the latest version or version 6.2.11 of the Magnolia Empty Webapp,

  • add the StartPlugin to the available plugins.

Click to see the JSON

{
  "projectTemplates": [
    {
      "name": "standard-webapps",
      "children": [
        {
          "name": "magnolia-empty-webapp",
          "children": [
            {
              "name": "latest",
              "bundles": [
                {
                  "url": "https://nexus.magnolia-cms.com/service/rest/v1/search/assets?sort=version&repository=public&maven.groupId=info.magnolia.tomcat.barebone&maven.artifactId=magnolia-tomcat-barebone&maven.extension=zip",
                  "postCommand": [
                    "extract"
                  ]
                },
                {
                  "url": "https://nexus.magnolia-cms.com/service/rest/v1/search/assets?sort=version&repository=public&maven.groupId=info.magnolia&maven.artifactId=magnolia-empty-webapp&maven.extension=war",
                  "version": "latest",
                  "dest": "./apache-tomcat/webapps/magnoliaAuthor",
                  "postCommand": [
                    "extract and override"
                  ]
                }
              ],
              "plugins": [
                {
                  "plugin": "@magnolia/cli-start-plugin",
                  "pluginArgs": {
                    "tomcatPath": "./magnolia/apache-tomcat"
                  }
                }
              ]
            },
            {
              "name": "6.2.11",
              "bundles": [
                {
                  "url": "https://nexus.magnolia-cms.com/service/rest/v1/search/assets?sort=version&repository=public&maven.groupId=info.magnolia.tomcat.barebone&maven.artifactId=magnolia-tomcat-barebone&maven.extension=zip",
                  "postCommand": [
                    "extract"
                  ]
                },
                {
                  "url": "https://nexus.magnolia-cms.com/service/rest/v1/search/assets?sort=version&repository=public&maven.groupId=info.magnolia&maven.artifactId=magnolia-empty-webapp&maven.extension=war",
                  "version": "6.2.11",
                  "dest": "./apache-tomcat/webapps/magnoliaAuthor",
                  "postCommand": [
                    "extract and override"
                  ]
                }
              ],
              "plugins": [
                {
                  "plugin": "@magnolia/cli-start-plugin",
                  "pluginArgs": {
                    "tomcatPath": "./magnolia/apache-tomcat"
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
For a more complex example, see the default projectTemplates.json file.
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