Custom templates (Advanced)

Clingon is a versatile tool, it offers you more basic, intermediate, and advanced modes of use.

Introduction

If you have used Clingon previously, you must have had contact with the way of using it where you answered a questionnaire, or the way where you created a JSON that was basically a shortcut for the questions, these two ways had in common the use of templates ready-made and opinionated, which are found within the Clingon repository, and you cannot modify them before use. Now with this new mode (present from version 1.0.0), you have the possibility of creating your own templates locally and using them in your project. You can create any type of file, without limitations on quantity or purpose (backend, frontend, etc.).

Differences

Understand the differences between the ways in which Clingon is used

Usage requirements

To use advanced mode, you need to have a folder structure in your project with a meta configuration file, where you describe the entire structure of the customized templates, the need for structure only goes up to the meta file, inside the templates folder. you create the structure you want to organize your templates, what matters is passing the correct path in the meta file. But have common sense, create organized and easy-to-maintain structures.

I recommend that you run the init command so that it creates a basic example structure, which you can build on and continue creating your templates.

npx clingon init --examples

After init, the Clingon CLI will generate these files and folders:

But if you want to create everything by hand, the necessary folder and file structure is as follows:

Meta file

Your meta file must follow a predefined interface to work correctly, see below the interface and some YAML and JSON examples:

interface Meta {
 identifier:string
 folderWrapper?: boolean
 case?: Case
 resources: Resource[]
}
 
interface Resource {
 path:string
 template: string
}
 
typeCase =
 | 'camelCase'
 | 'PascalCase'
 | 'snake_case'
 | 'kebab case'
 | 'UPPERCASE'
 | 'lowercase'

And here is an example in JSON or YAML, you can choose either of the two formats to define your meta data.

- identifier: component
  folderWrapper: true
  case: PascalCase
  resources:
    - path: src/components
      template: ./Component/index.tsx
    - path: src/components
      template: ./Component/Component.tsx
    - path: src/components
      tempalte: ./Component/Component.spec.tsx
    - path: src/components
      template: ./Component/Component.stories.tsx
    - path: src/components
      template: ./Component/Component.styles.css

[
  {
    "identifier": "component",
    "folderWrapper": true,
    "case": "PascalCase",
    "resources": [
      {
        "path": "src/components",
        "template": "./Component/index.tsx"
      },
      {
        "path": "src/components",
        "template": "./Component/Component.tsx"
      },
      {
        "path": "src/components",
        "template": "./Component/Component.spec.tsx"
      },
      {
        "path": "src/components",
        "template": "./Component/Component.stories.tsx"
      },
      {
        "path": "src/components",
        "template": "./Component/Component.styles.css"
      }
    ]
  }
]

Custom templates

Custom templates must be created within the .clingon/templates folder, and the structure is free, create as you wish, but have common sense to maintain a structure that is simple to maintain, and that is not confusing to understand.

As a suggestion, I say that you can create folders similar to those in your project, which will be intuitive for those who work with the project, let's look at the following examples:

• I want to create frontend templates, for components, tests and stories, my project uses React, Storybook and Vitest.

Suggested structure:

And your meta file should look like this:

- identifier: react-component
  folderWrapper: true
  resources:
    - path: 'src/components'
      template: './component/React/index.tsx'
    - path: 'src/components'
      template: './component/React/Component.tsx'
    - path: 'src/components'
      template: './component/React/Component.spec.tsx'
    - path: 'src/components'
      template: './component/React/Component.stories.tsx'
    - path: 'src/components'
      template: './component/React/Component.styles.css'

• Note: When you have components with many files together, you can use folderWrapper to group them into a single folder with the name of the component, or if you have a structure where the component, test, stories, etc., are in different folders, use the path to indicate where it should be created.

Template path

The template path in the meta file should be considered as follows, the path starts from the .clingon/templates folder, so use ./ + templatePath, in the path key of the resources. Let's consider the meta file above (at the end of the previous section) as an example:

• Your customized template is at .clingon/templates/components/React:

• Your meta file must have the path like this:

- identifier: react-component
  folderWrapper: true
  resources:
    - path: 'src/components'
      template: './component/React/index.tsx'
    - path: 'src/components'
      template: './component/React/Component.tsx'
    - path: 'src/components'
      template: './component/React/Component.spec.tsx'
    - path: 'src/components'
      template: './component/React/Component.stories.tsx'
    - path: 'src/components'
      template: './component/React/Component.styles.css'

How to use

After creating all the necessary structure, you can run the scaffold command which will create your files based on the local template.

Be aware that the command has a flag called --template and the value that must be passed to it is the identifier key of the meta file.

The command must be used as follows:

npx clingon scaffold <name> --template <identifier>

Let's say I want to create a component called Accordion, and this component uses the template called basic-component (which we can assume already exists in my meta file), I call the command like this:

npx clingon scaffold Accordion --template basic-component

Resume