@magnolia/cli-create-component

Cli Create Component Plugin

This plugin creates a new component based on templates provided from available npm packages:

• @magnolia/cli-freemarker-prototypes
• @magnolia/cli-angular-prototypes
• @magnolia/cli-react-prototypes
• @magnolia/cli-vue-prototypes

Installation

Install plugin via npm:

npm i @magnolia/cli-create-component

Add CreateComponentPlugin to mgnl.config.js file:

import CreateComponentPlugin from "@magnolia/cli-create-component";

export default {
  commands: [
    new CreateComponentPlugin()
  ]
};

Usage

npm run mgnl create-component -- <name> [options]

Command-line parameter

• <name>, the name of the new component, required

Command-line options

You can customize the create-component plugin's actions using these command-line options:

• -lm, --light-module <name>, set the light module for the component template; defaults to the directory specified in mgnl.config.js file
• -P, --prototype [prototype], select a prototype for component creation
• -a, --available <path-to-page[@area]>, specify the page you want to make the component available to; must start with the path to the page template within the templates directory and end with an area name; if the area does not exist, it will be added; defaults to 'main' area if not specified

Options that can be set in mgnl.config.js file:

• type, lightModulePath, componentMappingFilePath are shared between 'CreateComponentPlugin' and 'CreatePagePlugin'
• componentsSpaPath, framework, prototype, templateData, templateArgs are for 'CreateComponentPlugin' only

import CreateComponentPlugin from "@magnolia/cli-create-component";

export default {
  type: 'ts',
  lightModulePath: './magnolia/light-modules',
  lightModule: 'spa-lm',
  componentMappingFilePath: './spa/react-minimal/src/magnolia.config.js',
  
  commands: [
    new CreateComponentPlugin({
      componentsSpaPath: './spa/react-minimal/src/components',
      framework: '@magnolia/cli-react-prototypes',
      prototype: "_default",
      templateData: {
        // {{customName}} in .hbs file
        customName: "customValue"
      },
      templateArgs: {
        // Use default light module template from cli-create-component-template if component template doesn't have any, default true
        useDefaultLightModuleTemplate: true,
        // For headless only:
        /*
         * Remove extension from import string, default false:
         *  - true => import { componentName } from ./path/to/component;
         *  - false => import { componentName } from ./path/to/component.js;
         */
        removeExtension: false,
        /*
         * Use named import, default false:
         *  - true => import { componentName } from ./path/to/component;
         *  - false => import componentName from ./path/to/component;
         */
        namedImport: true,
        /*
         * Specify the file to use for imports when multiple files in template exist, it selects based on the following logic:
         * 1. Single file: Directly use it.
         * 2. Multiple files: Prefers 'index' prefixed, then component-named file ({{name}}). If neither is uniquely identifiable, manual specification is required.
         * Example structure and import behavior:
         * /tsx
         * |--/index.tsx (default import)
         * |--/{{name}}.tsx
         * |--/{{name}}.stories.tsx
         * |--/{{name}}.model.tsx
         *
         * - not set => import componentName from ./path/to/index.tsx;
         * - '{{name}}.tsx' => import componentName from ./path/to/{{name}}.tsx;
         */
        importSource: '{{name}}.tsx'
      }
    })
  ]
};

Example

Examples are shown in a headless/minimal-headless-spa-demos/dx-core/latest project.

Download with:

npx @magnolia/cli@preview jumpstart -t headless/minimal-headless-spa-demos/dx-core/latest

Install CreateComponentPlugin

npm i @magnolia/cli-create-component

Add to mgnl.config.js

import CreateComponentPlugin from "@magnolia/cli-create-component";

export default {
  type: 'ts',
  lightModulePath: './magnolia/light-modules',
  lightModule: 'spa-lm',
  componentMappingFilePath: './spa/react-minimal/src/magnolia.config.js',
  
  logger: {
    filename: "./mgnl.error.log",
    fileLevel: "warn",
    consoleLevel: "debug"
  },
  commands: [
    new CreateComponentPlugin({
      componentsSpaPath: './spa/react-minimal/src/components',
      framework: '@magnolia/cli-react-prototypes',
      prototype: '_default',
      templateArgs: {
        removeExtension: true
      }
    })
  ]
};

Example 1: Create component with @magnolia/cli-react-prototypes stored in npx repository

Run:

npm run mgnl -- create-component Hero

Will create following files:

• /PATH/TO/PROJECT/magnolia/light-modules/spa-lm/dialogs/components/Hero.yaml

  label: Hero
  form:
    properties:
      text:
        label: Hero Text
        $type: textField
        i18n: true

• /PATH/TO/PROJECT/magnolia/light-modules/spa-lm/templates/components/Hero.yaml

  title: Hero
  dialog: spa-lm:components/Hero

• /PATH/TO/PROJECT/spa/react-minimal/src/components/Hero.js

  import React from 'react';
  
  const Hero = props => <h2>{props.text}</h2>;
  
  export default Hero;

Will modify following file:

• /PATH/TO/PROJECT/spa/react-minimal/src/magnolia.config.js

  import HeroComponent from './components/Hero'
  import Basic from './pages/Basic';
  import Contact from './pages/Contact';
  import Headline from './components/Headline';
  import Image from './components/Image';
  import Paragraph from './components/Paragraph';
  import Expander from './components/Expander';
  import List from './components/List';
  import Item from './components/Item';
  import Personalization from './pages/Personalization';
  
  const config = {
    'componentMappings': {
      'react-minimal-lm:pages/basic': Basic,
      'react-minimal-lm:pages/contact': Contact,
      'react-minimal-lm:pages/personalization': Personalization,
  
      'react-minimal-lm:pages/basic-autogeneration': Basic,
      'react-minimal-lm:pages/contact-inheritance': Contact,
  
      'spa-lm:components/headline': Headline,
      'spa-lm:components/image': Image,
      'spa-lm:components/paragraph': Paragraph,
      'spa-lm:components/expander': Expander,
      'spa-lm:components/list': List,
      'spa-lm:components/listItem': Item,
      "spa-lm:components/Hero": HeroComponent
    }
  };
  
  export default config;

Example 2: Create component with locally cloned @magnolia/cli-react-prototypes

Clone: cli-react-prototypes

Change framework in mgnl.config.js:

import CreateComponentPlugin from "@magnolia/cli-create-component";

export default {
  ...
  commands: [
    new CreateComponentPlugin({
      componentsSpaPath: './spa/react-minimal/src/components',
      framework: '/Path/To/Cloned/cli-react-prototypes',
      prototype: '_default',
      templateArgs: {
        removeExtension: true
      }
    })
  ]
};

Run:

npm run mgnl -- create-component Hero

Will behave like Example 1, but use the local 'components' folder.