Tokens
Tokens are variables and functions that can be used by command
,
args
, env
(>= v1.12),
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 value, as they expand to multiple files. When
used in an env
value, multiple files are joined with a comma (,
).
File groups
These functions reference file groups by name, where the name is passed as the argument.
@group
Usable in
args
,env
,inputs
, andoutputs
.
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.
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
,env
,inputs
, andoutputs
.
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.
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
,env
,inputs
, andoutputs
.
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.
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
,env
,inputs
, andoutputs
.
The @globs(file_group)
token will be replaced with the 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.
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
,env
,inputs
, andoutputs
.
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.
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 token function 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
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.
Workspace
$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'
Project
$language
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'
$projectAlias
Alias of the project that owns the currently running task. If not enabled, or no alias exists for the project, this will return an empty string.
# Configured as
tasks:
build:
command: 'example --projectAlias $projectAlias'
# Resolves to
tasks:
build:
command:
- 'example'
- '--projectAlias'
- '@web/app'
$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
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'
Task
$target
Target that is currently running.
# 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
The platform that task will run against, as defined in moon.yml
.
# Configured as
tasks:
build:
command: 'example --platform $taskPlatform'
# Resolves to
tasks:
build:
command:
- 'example'
- '--platform'
- 'system'
$taskType
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'
Date/Time
$date
The current date in the format of YYYY-MM-DD
.
# Configured as
tasks:
build:
command: 'example --date $date'
# Resolves to
tasks:
build:
command:
- 'example'
- '--date'
- '2023-03-17'
$time
The current time in the format of HH:MM:SS
.
# Configured as
tasks:
build:
command: 'example --time $time'
# Resolves to
tasks:
build:
command:
- 'example'
- '--time'
- '14:05:10'
$datetime
The current date and time in the format of YYYY-MM-DD_HH:MM:SS
.
# Configured as
tasks:
build:
command: 'example --datetime $datetime'
# Resolves to
tasks:
build:
command:
- 'example'
- '--datetime'
- '2023-03-17_14:05:10'
$timestamp
The current date and time as a UNIX timestamp in seconds.
# Configured as
tasks:
build:
command: 'example --timestamp $timestamp'
# Resolves to
tasks:
build:
command:
- 'example'
- '--timestamp'
- '1679087127'