Craftsman

What is craftsman ?

Craftsman is CLI tool that helps you to simplify the process of creating code files by using templates. It's a simple way to make conventions on how a file must look like.

Installation

# Install craftsman
npm i -g @augustindlt/craftsman

Config

Create a config file inside your project : .craftsman/config.json

Config parameters :

| parameter | type | meaning | | --------- | ---------- | ------------------------------------------------------------------------- | | templates | Template[] | List of all templates | | helpers | Helpers | Set of functions that you can use inside the config and in your templates |

Template :

| parameter | type | meaning | | --------- | --------- | ------------------------------------------------------------- | | name | string | Name of the template | | files | File[] | List of all the files to generate | | path | string | Optional parameter to declare where the files will be created | | variables | Variables | Set of variables you need to create the files |

File :

| parameter | type | meaning | | ------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | path | string | Destination of the generated file | | name | string | Name of the generated file | | template | string | File name without extension which contains the template | | replaceExistingFile | "yes" | "no" | "ask" | Determines if the cli should replace the file or not if it already exists, by default this parameter by default this parameter is set to "ask" |

Variables :

The variables have all this base config :

{
  "templates": [
    {
      ...
      "variables": {
        "salutation": {...},
        "nameOfMyVariable": { // The name of the variable that you want to set
          "type": "text", // The type of question you want the cli ask you, it can be "text", "choices", "autocomplete", "file", "directory", "array"
          "message": "What value are you going to set to nameOfMyVariable ?", // The message that will be print, it's an optional parameter
          "condition": "salutation.toLowerCase() === 'hello' && 1 === 1" // A JS condition which will determine whether the cli will ask or not for this variable, if not the default value of variable will be "", it's an optional parameter

          // Here the other parameters depending on the type of the variable
        }
      }
    }
  ]
}

choices and autocomplete :

{
  ...
  "variables": {
    "nameOfMyVariable": {
      "type": "choices",
      "choices": ["yes", "no", "may be"] // Array of string that represent all the choices you can select
    }
  }
}

file and directory :

{
  ...
  "variables": {
    "component": {
      "type": "file",
      "matchString": ".component.tsx", // Filter files to show only those that contains this string in their path, it's an optional parameter
      "matchRegex": "\\.component\\.tsx$", // Same as the matchString but with a regex, it's an optional parameter
      "path": "./src" // Base path where is the file you want to select, the file can be inside of a sub folder, by default this parameter is set to "."
    }
  }
}

array :

{
  ...
  "variables": {
    "nameOfMyVariable": {
      "type": "array"
    }
  }
}

With the config below by default the cli will ask for text questions and will set nameOfMyVariable to an simple array of string like: ["hello", "hey" ...]

{
  ...
  "variables": {
    "nameOfMyVariable": {
      "type": "array",
      "variables": {
        "name": {
          "type": "text"
        },
        "wantACofee": {
          "type": "choices",
          "choices": ["yes", "no", "may be"]
        },
        "typeOfCofee": {
          "type": "autocomplete",
          "choices": ["Cappuccino", "Espresso", "Mochaccino", "Macchiato"],
          "condition": "wantACofee !== 'no'"
        }
      }
    }
  }
}

The config below will set nameOfMyVariable to an array of object with sub variables like: [{ name: "Jhon", wantACofee: "yes", typeOfCofee: "Cappuccino"}, { name: "Mary", wantACofee: "no", typeOfCofee: ""}]

Helpers :

Helpers are custom functions written in javascript, which can be used in your templates and configuration, here is an example of a helper declaration :

{
  "templates": [...],
  "helpers": {
    "skewer": "helpers/skewer" // The declaration of a helper takes his name as a key and his path without the extension as value
  }
}

.craftsman/helpers/skewer.js :

module.exports = (value) => Array.from(value).join("-");

Now we can use it :

{
  ...
  "condition": "skewer(nameOfMyVariable) === 'h-e-l-l-o'"
}

Template

Create a template file inside your project : .craftsman/nameOfMyTemplate.craft

Put inside this file the code you want to generate.

The cli use EJS as templating language, you can use all the variables of your template and all your helpers inside of the templates files, like :

.craftsman/nameOfMyTemplate.craft :

console.log(<%=skewer(nameOfMyVariable)>);

Usage

Inside your terminal :

cd path/to/your/project
craft

Example

Config :

.craftsman/config.json :

{
  "$schema": "https://raw.githubusercontent.com/augustindlt/craftman/master/json-schema.json",
  "templates": [
    {
      "name": "Hello",
      "files": [
        {
          "path": "./src/<%=fileName%>",
          "name": "<%=fileName%>.js",
          "template": "hello"
        }
      ],
      "variables": {
        "fileName": { "type": "text" },
        "salutation": { "type": "choices", "choices": ["Hey", "Hello"] },
        "name": { "type": "text" }
      }
    }
  ]
}

.craftsman/hello.craft :

console.log("<%=salutation%> <%=name%>");

Usage :

Inside the terminal :

craft

Enters all variables that we defined in the config :

After is done ! :

We can see the result :