Roc features a configuration system that makes it possible for extensions to define useful data that other extensions and projects can use.
Configuration in extensions are similar to projects with some slight differences. Mainly the existence of a meta configuration that can be used to further enhance the user experience and documentation generation.
The configuration object in extensions has one property that is specially managed by Roc, settings, and one that extensions are not allowed to define, project. Other than that extensions are free to define additional properties as they need.
Example
{
settings: {},
custom: {}
}Read more about settings here.
Extensions are allowed to define additional properties to suit their needs. An example of this could be something that does not make sense to provide within the normal settings managed by the core. In general it is recommended to use settings to get the best possible documentation generation as well as allowing a user to define things on the command line. With custom properties you lose this.
Example
{
custom: {},
custom2: 4
}The meta configuration should mirror the normal configuration structure.
Custom properties that are defined by extensions can define useful meta information, description and override.
Example
{
custom: {
description: 'Some description',
override: true
},
custom2: {
description: (commandObject, configurationForProperty) => '',
override: 'roc-package-example'
}
}A string or a function that returns a string. Used when generating documentation and can contain markdown.
Function
(rocCommandObject, configurationForProperty) => StringcommandObject
The command object.
configurationForProperty
The final configuration value for the property.
Roc projects can be configured to a great extent using the roc.config.js file. By default it’s assumed that it is located inside the current working directory, that is from the directory where the command was invoked. You can override both the expected filename and the directory for the lookup using the command line interface, see below for more information.
Once imported to your project the configuration will persist throughout the process lifetime and it’s recommended that it is treated as it would be immutable.
Roc expects that the roc.config.js exports an object and by default some properties are managed as illustrated in the example below. Extensions can add more managed properties.
Example
module.exports = {
settings: {},
project: {
actions: [],
init: () => {}
},
// Extension defined / custom properties
custom: {}
};See the documentation for the extensions that are used in the project or the generated documentation from roc meta docs for the available settings.
A function or an array of functions and/or objects. The functions and objects work in the same way as for extensions.
See the documentation for the extensions that are used in the project or the generated documentation from roc meta docs for the available hooks that the project can register actions on.
See more here about the general structure.
A function that work much in the same way as for extensions. Can be used to modify the context in an advanced way. Most users will not need to use this.
Example
({ context }) => {}context
The context object.
Should return an object with the structure below, can both override properties from the extensions Roc object and update the context. Can also return false if nothing should be processed.
Example
{
roc: {
actions,
commands,
config,
hooks,
meta
},
context: {
actions,
commands,
config,
dependencies,
meta
}
}
roc
Will be shallow merged with the values already present directly on the Roc object.
Supports specifying:
- actions
- commands
- config
- hooks
- meta
context
Will replace the already present values on the context.
Supports specifying:
- actions
- commands
- config
- dependencies
- meta
Note: hooks are not present in the context object. This since it would not make sense to remove registered hooks from other extensions.
Note: dependencies are not present in roc.
roc <command> --directory path/to/directory
You can override the current working directory using the -d, --directory option. The path can be either relative to the current working directory or absolute.
This will not only change where Roc looks for the roc.config.js file but from where the entire runtime is started inside.
It’s possible to define where Roc should look for the roc.config.js by default by specifying a path inside the package.json. The path can be either relative to the current working directory or absolute.
{
...
"dependencies": {
...
},
"roc": {
"config": "./some/path/roc.config.js"
}
}roc <command> --config path/to/roc.config.js
You can override the current the location and name for the roc.config.js file using the -c, --config option. The path can be either relative to the current working directory or absolute. This option will override a potential value defined in the package.json.
Roc will look for two environment variables ROC_CONFIG_PATH, will override the previous ones.
If a configuration file path is provided by environment variable ROC_CONFIG_PATH it will load this instead of a configuration file within the project, without merging the two.
One big part of the configuration management in Roc is how configuration files are merged. Application configurations, and by default in extensions, are deeply merged using merge-options.
This results in that the merge is based on properties and values for those properties. Duplicated properties will overwrite each other. That means for instance that arrays will not be magically merged but rather overwrite the old value. A benefit of this is that it becomes trivial to override something defined in extensions.