Tokens
Tokens are variables and functions that can be used by args
,
inputs
, and outputs
when configuring a
task. They provide a way of accessing file group paths, referencing values from other task fields,
and referencing metadata about the project and task itself.
Functions
A token function is labeled as such as it takes a single argument, starts with an @
, and is
formatted as @name(arg)
. The following token functions are available, grouped by their
functionality.
Token functions must be the only content within a list item, as they expand to multiple file paths.
File groups
These functions reference file groups by name, where the name is passed as the argument.
@group
v0.6
Usable in
args
andinputs
.
The @group(file_group)
token is a standard token that will be replaced with the file group items
as-is, for both file paths and globs. This token merely exists for reusability purposes.
When used in args
, it will return relative or absolute paths, depending
on run context, while inputs
will return absolute paths.
fileGroups:
storybook:
- '.storybook/**/*'
- 'src/**/*'
- '**/*.stories.*'
# Configured as
tasks:
build:
command: 'build-storybook'
inputs:
- '@group(storybook)'
start:
command: 'start-storybook'
inputs:
- '@group(storybook)'
# Resolves to
tasks:
build:
command: 'build-storybook'
inputs:
- '/path/to/project/.storybook/**/*'
- '/path/to/project/src/**/*'
start:
command: 'start-storybook'
inputs:
- '/path/to/project/.storybook/**/*'
- '/path/to/project/src/**/*'
@dirs
Usable in
args
andinputs
.
The @dirs(file_group)
token will be replaced with an expanded list of directory paths, derived
from the file group of the same name. If a glob pattern is detected within the file group, it will
walk the file system and aggregate all directories found.
When used in args
, it will return relative or absolute paths, depending
on run context, while inputs
will return absolute paths.
fileGroups:
lintable:
- 'src'
- 'tests'
- 'scripts'
- '*.config.js'
# Configured as
tasks:
lint:
command: 'eslint @dirs(lintable) --color'
inputs:
- '@dirs(lintable)'
# Resolves to
tasks:
lint:
command:
- 'eslint'
- 'src'
- 'tests'
- 'scripts'
- '--color'
inputs:
- '/path/to/project/src'
- '/path/to/project/tests'
- '/path/to/project/scripts'
@files
Usable in
args
andinputs
.
The @files(file_group)
token will be replaced with an expanded list of file paths, derived from
the file group of the same name. If a glob pattern is detected within the file group, it will walk
the file system and aggregate all files found.
When used in args
, it will return relative or absolute paths, depending
on run context, while inputs
will return absolute paths.
fileGroups:
config:
- '*.config.js'
- 'package.json'
# Configured as
tasks:
build:
command: 'webpack build @files(config)'
inputs:
- '@files(config)'
# Resolves to
tasks:
build:
command:
- 'webpack'
- 'build'
- 'babel.config.js'
- 'webpack.config.js'
- 'package.json'
inputs:
- '/path/to/project/babel.config.js'
- '/path/to/project/webpack.config.js'
- '/path/to/project/package.json'
@globs
Usable in
args
andinputs
.
The @globs(file_group)
token will be replaced with an expanded list of glob patterns (as-is),
derived from the file group of the same name. If a non-glob pattern is detected within the file
group, it will be ignored.
When used in args
, it will return relative or absolute paths, depending
on run context, while inputs
will return absolute paths and also be
used in affected files detection by matching against the patterns.
fileGroups:
tests:
- 'tests/**/*'
- '**/__tests__/**/*'
# Configured as
tasks:
test:
command: 'jest --testMatch @globs(tests)'
inputs:
- '@globs(tests)'
# Resolves to
tasks:
test:
command:
- 'jest'
- '--testMatch'
- 'tests/**/*'
- '**/__tests__/**/*'
inputs:
- '/path/to/project/tests/**/*'
- '/path/to/project/**/__tests__/**/*'
@root
Usable in
args
andinputs
.
The @root(file_group)
token will be replaced with the lowest common directory, derived from the
file group of the same name. If a glob pattern is detected within the file group, it will walk the
file system and aggregate all directories found before reducing.
When used in args
, it will return relative paths, while
inputs
will return absolute paths.
fileGroups:
sources:
- 'src/app'
- 'src/packages'
- 'src/scripts'
# Configured as
tasks:
format:
command: 'prettier --write @root(sources)'
inputs:
- '@root(sources)'
# Resolves to
tasks:
format:
command:
- 'prettier'
- '--write'
- 'src'
inputs:
- '/path/to/project/src'
When there's no directies, or too many directories, this function will return the project root using
.
.
Inputs & outputs
@in
Usable in
args
only.
The @in(index)
token will be replaced with a single path, derived from
inputs
by numerical index. If a glob pattern is referenced by index,
the glob will be used as-is, instead of returning the expanded list of files.
# Configured as
tasks:
build:
command:
- 'babel'
- '--copy-files'
- '--config-file'
- '@in(1)'
- '@in(0)'
inputs:
- 'src'
- 'babel.config.js'
# Resolves to
tasks:
build:
command:
- 'babel'
- '--copy-files'
- '--config-file'
- 'babel.config.js'
- 'src'
inputs:
- '/path/to/project/src'
- '/path/to/project/babel.config.js'
@out
Usable in
args
only.
The @out(index)
token will be replaced with a single path, derived from
outputs
by numerical index. If a glob pattern is referenced by index,
the process will fail, as it requires literal folder and file paths.
# Configured as
tasks:
build:
command:
- 'babel'
- '.'
- '--out-dir'
- '@out(0)'
outputs:
- 'lib'
# Resolves to
tasks:
build:
command:
- 'babel'
- '.'
- '--out-dir'
- 'lib'
outputs:
- '/path/to/project/lib'
Variables
Usable in
args
andinputs
only.
A token variable is a value that starts with $
and is substituted to a value derived from the
current workspace, project, and task. And unlike token functions, token variables can be placed
within content when necessary, and supports multiple variables within the same content.
$language
v0.7
Programming language the project is written in, as defined in moon.yml
. If
the project has not defined the language
setting, or does not have a
config, this defaults to "unknown".
# Configured as
tasks:
build:
command: 'example debug $language'
# Resolves to
tasks:
build:
command:
- 'example'
- 'debug'
- 'node'
$project
ID/name of the project that owns the currently running task, as defined in
.moon/workspace.yml
.
# Configured as
tasks:
build:
command: 'example --project $project'
# Resolves to
tasks:
build:
command:
- 'example'
- '--project'
- 'web'
$projectRoot
Absolute file path to the project root.
# Configured as
tasks:
build:
command: 'example --cwd $projectRoot'
# Resolves to
tasks:
build:
command:
- 'example'
- '--cwd'
- '/path/to/repo/apps/web'
$projectSource
Relative file path from the workspace root to the project root, as defined in
.moon/workspace.yml
.
# Configured as
tasks:
build:
command:
- 'example'
- '--cache-dir'
- '../../.cache/$projectSource'
# Resolves to
tasks:
build:
command:
- 'example'
- '--cache-dir'
- '../../.cache/apps/web'
$projectType
v0.7
The type of project, as defined in moon.yml
. If the project has not defined
the type
setting, or does not have a config, this defaults to "unknown".
# Configured as
tasks:
build:
command: 'example debug $projectType'
# Resolves to
tasks:
build:
command:
- 'example'
- 'debug'
- 'application'
$target
Target that is currently running. Is a combination of project and task name.
# Configured as
tasks:
build:
command: 'example $target'
# Resolves to
tasks:
build:
command:
- 'example'
- 'web:build'
$task
ID/name of the task that is currently running.
# Configured as
tasks:
build:
command: 'example --task=$task'
# Resolves to
tasks:
build:
command:
- 'example'
- '--task=build'
$taskPlatform
v0.17
The platform that task will run against.
# Configured as
tasks:
build:
command: 'example --platform $taskPlatform'
# Resolves to
tasks:
build:
command:
- 'example'
- '--platform'
- 'system'
$taskType
v0.17
The type of task, based on its configured settings.
# Configured as
tasks:
build:
command: 'example --type $taskType'
# Resolves to
tasks:
build:
command:
- 'example'
- '--type'
- 'build'
$workspaceRoot
Absolute file path to the workspace root.
# Configured as
tasks:
build:
command:
- 'example'
- '--cwd'
- '$workspaceRoot'
# Resolves to
tasks:
build:
command:
- 'example'
- '--cwd'
- '/path/to/repo'