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.

@groupv0.6

Usable in args and inputs.

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 and inputs.

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 and inputs.

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 and inputs.

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 and inputs.

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 and inputs 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.

$languagev0.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'

$projectTypev0.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'

$taskPlatformv0.17

The platform that task will run against.

# Configured as
tasks:
  build:
    command: 'example --platform $taskPlatform'

# Resolves to
tasks:
  build:
    command:
      - 'example'
      - '--platform'
      - 'system'

$taskTypev0.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'