3 configuration

Configuration

[ english ] [ spanish ]

sources

The magic can be configured from 3 different sources in json format. That it was mentioned before a node project does not need it, this tool is useful for whatever kind of project where you want/need shortcuts.

The files are: package.json, executor.json and whateverName.json, the configuration can be on some of three files, and is equal for each case.

package.json

Classic file for whatever node application or even on a web application.

To use this file as a source, only you need to put an attribute: executor and inside the "shortcuts" configuration , sample:

{
  "name": "myProject",
  "version": "0.0.1",
  "scripts": {
    ...
  },
  "dependencies": {
    ...
  },
  "devDependencies": {
    ...
  },
  "executor": {
    >> your configuration here! <<
  }
}

executor.json

Standalone file with the configuration.

Notes:

• Can coexist with package.json, winning uncouple, without adding the attribute executor on your package.json

custom.json

Standalone file configured on package.json if you want to change de name or location of your executor.json, sample:

  "executor": {
    "configFile": "configs/myConf.json"
  }

Notes:

• If you configured this file, it should ignore the executor.json even if it exists on the same folder.

configuration

Let us go to see how you can configure this tool and what options are on each central concepts: options and data.

options

Options of configuration to run it from the command line.

• dry: boolean = false
  It allows you to run the CLI without run the command; it is so useful to debug and build new shortcuts.
• showTime: boolean = true
  Shows the total time of the shortcut ran.
• showCommand: boolean = true
  It shows the final command.
  Note: If dry is active, it shows the command without matter about this option.
• useColors: boolean = true
  The output of the console will show with colours, but it can give some troubles on your console, you can deactivate it.
• colors: {primary, secondary, alert} You can configure the colours using this table code.

data

The "data" is the content that became a simple string or command to use on the console.

It will interpolate (interchange) the data with the delimiter: '${ }', this allows us to build templates, replacing placeholders by values.

We have 5 sources: def, env, pkg, templates, shortcuts.

Notes:

• It does not use the feature of ECMAScript, it is a simple replace function.
• The order is important! you need to define the data/template before using it on another template.

Let us see each source:

predefined (def)

We have some predefined values (read-only) that we can use for the templates, to the moment exist cwd, after the list will be increased "on demand".
Sample: echo this is your current folder: ${def.cwd}

• cwd: Current folder without taking care of the operating system ("/" or "", past problem).

environments (env)

Environment variables, use this object to get the value from your operating system.
Sample: echo this is your path variable: ${env.path}

package.json (pkg)

It read the package.json file if it exists on the same folder, and you can access to the configuration in an easy way using the object pkg Sample: echo current version of your package.json: ${pkg.version}

Or the scripts can be your sources for your shortcuts!:

{
  "name": "myProject",
  "version": "0.0.1",
  "scripts": {
    "build": "ng build"
  },
  "executor": {
    "shortcuts": {
      "bp": "${pkg.scripts.build} --prod --output-path build/${pkg.version}"
    }
  }
}

It should invoke an angular CLI and set the "production" mode, and it will create a folder with the number version set on package.json!

templates

There are the strings that you can use to build your commands, with the possibility to reuse them easily with less maintenance.

use

Sample:

templates: {
  "variable1": "foo",
  "variable2": "${variable1} bar" 
}

The result on variable2 will be: foo bar

features

• It supports templates of templates. Sample: templates: {templateUnion: "${template1} and ${template2}"}
• It support nested template if you want to keep it organized.
  Sample:

"templates": {
  "project": "myProject",
  "imageName": {
    "base": "${project}-base",
    "dev": "${project}-dev",
    "prod": "${project}-prod"
  }
}

• You can access to the sub-objects with the dot operator: '.'
  Sample: Image: ${imageName.prod}, the result is: myProject-prod
• It supports infinite levels of nested objects.

shortcuts

Finally, we reach the famous "shortcuts", it will be interpolated the same way that templates, that inherits the same features and add:

• We can use other shortcuts as templates.
• Each sub-object is for separate arguments.

Sample (Sorry for the simple sample, but the idea is to get knowledge about it):

"templates": {
  "project": "myProject",
  "imageName": {
    "prod": "${project}-prod"
  }
},
"shortcuts": {
  changeDir: "cd ${imageName.prod}", // only argument
  removeDir: "rm ${imageName.prod}", // only argument
  dir: {                             // first argument
    change: "cd ${imageName.prod}",  // second argument
    remove: "rm ${imageName.prod}"   // second argument 
  },
  showCommandChangeDir: "echo ${dir.change}" // only argument, it will use "." like template. 
}

The shortcuts ready to use should be:

> x changeDir
> x removeDir
> x dir change
> x dir remove
> x showCommandChangeDir

With this sample we can see three cases:

• Run with one argument (x changeDir)
• Run with two arguments (x dir change)
• Run with one argument, but internally it uses a shortcut as a template with the operator '.'. (x showCommandChangeDir)

As we can see, we can do the different way. The flexibility is here!

Tip: In my case, I prefer the format: "subject + verb" with two arguments, I know, it is not grammatically right, but it is more useful to interchange the verb, because I usually change the verb more than the subject, like e dir change.

Summary

With these, we have this five sources to build our shortcuts (in this order):

1. env
2. def
3. pkg
4. templates
5. shortcuts

Notes:

• The params after the last argument to get the shortcut will be sent to the command
  Sample: e mochaShortcut --watch, watch will be sent to the command
• In the case does not find a shortcut, it will show the keys and will return an error (exit code 1).
• Remember the order is essential even each source.

[ prev ][ next ]