CLI
Documentation for the Command Line Interface
Documentation for the Command Line Interface
The CLI for Lore is intended to be a complimentary tool for the application, and is designed in a way that allows it be extended from within a project. This means that you can add new commands to the CLI as well as overwrite existing commands, and all without leaving your project, or without needing to submit a PR to modify the CLI itself.
While the CLI originally started off as a simple convenience for generating basic project files, and was not expected to be useful much beyond the Quickstart, the inclusion of the extract commands have dramatically changed that relationship and have made the CLI useful as a permanent tool.
Beyond the ability to generate a new project, there are two types of commands in the CLI.
Generators are used to add common files (like components, actions, reducers) to your project, and include flags for generating those files in ES5, ES6 or ESNext style syntax.
Generators can be especially useful when you need to override a default action or reducer.
Extractors are used to extract files that mirror functionality that the framework is providing through conventions. These are different from generators in the sense that aren't intended to be a blank starting point; they're intended to say "show me what the framework is doing".
Extractors can be especially useful when you need to override a default action or reducer, but don't need to create something super custom. This allows you to start from what the framework is already doing and simplify modify it.
The CLI is controlled through the .lorerc file at the root of your project, which looks like this:
{
"generators": {
"language": "es5"
},
"commands": {}
}
{
"generators": {
"language": "es6"
},
"commands": {}
}
{
"generators": {
"language": "esnext"
},
"commands": {}
}
By default, this file is the same for all projects, except for the language specified for the project (which controls what generated files will look like).
The file contains two keys; generators and commands.
The settings for generators control what generated files will look like, such as when using the command lore generate component Header.
The settings for commands control what commands are available. This is your extension point for overriding the existing commands or extending the CLI with new commands.
A version of the .lorerc file that completely replaces the default set of CLI commands looks like this:
{
"generators": {
"language": "es5"
},
"commands": {
"new": "lore-generate-new",
"extract": {
"description": "Create files that mirror the blueprint behavior",
"commands": {
"action": "lore-extract-action",
"reducer": "lore-extract-reducer"
}
},
"generate": {
"description": "Generate common project files",
"commands": {
"action": "lore-generate-action",
"collection": "lore-generate-collection",
"component": "lore-generate-component",
"generator": "lore-generate-generator",
"hook": "lore-generate-hook",
"model": "lore-generate-model",
"reducer": "lore-generate-reducer"
}
}
}
}
The commands key is how you signal to the CLI that you have something you need to add to it.
If you want to add a command at the root, such as lore hello <arguments>, you would add it by specifying a key called "hello" with a value pointing to the module location:
{
"generators": {
"language": "es5"
},
"commands": {
"hello": "./commands/folder-name"
}
}
The value can be a relative path like ./commands/folder-name, an absolute path like /Users/jason/some-folder/command-folder, or a node_module like module-name. If you provide a node_module, the CLI will first look in the project's node_modules directory, and then look in the global node_modules directory before throwing an error if it can't find it in either location.
If you want to create a nested command, like lore hello world <arguments> then you need to nest your command inside a category, like this:
{
"generators": {
"language": "es5"
},
"commands": {
"description": "Describe what commands in this category are for",
"hello": {
"world": "./commands/folder-name"
}
}
}
The category description is completely optional. It defaults to an empty string. If you specify a description for a category that exists by default, such as extract or generate it will override the default description.