CLI

The CLI package is a simple way for users to interact with some of the build/validation tooling. As new capabilities are added to the ecosystem, they may be exposed via this cli to use of use for developers.

Config

Config files are able to customize the behavior of the CLI commands without requiring args. Behavior specific to execution can leverage plugins, which can be composed together using presets. Full configs can also be shared using extensions.

To resolve a full configuration, the extension is taken as the base, the presets are applied in order, then local plugins. The format is similar to eslint, babel and other .rc/json/js based approaches.

Config files are searched using cosmiconfig with “player” as the module name for cosmiconfig purposes.

Example:

module.exports = {
  extends: "@my-scope/base",
  plugins: [
    "plugin-npm-package",
    ["some-plugin-with-config", { config: true }],
    {
      // Plugins can also be defined inline
      handler: () => {},
    },
  ],
};

Options defined via the CLI arguments will take precedence over the config files (for things that overlap).

JavaScript/TypeScript Config Files

JavaScript and TypeScript config files (playerrc.js, player.config.ts, config/playerrc.mjs, etc.) support three plugin formats:

Option A: Package name (string)

module.exports = {
  plugins: [
    "@fancy-dog/dsl-plugin",
  ],
};

Option B: Package name with options (array)

module.exports = {
  plugins: [
    ["@fancy-dog/dsl-plugin", { customOption: "value" }],
  ],
};

Option C: Direct plugin instance (object)

const { FancyDogPlugin } = require("@fancy-dog/dsl-plugin");

module.exports = {
  plugins: [
    new FancyDogPlugin({ customOption: "value" }),
  ],
};

JSON/YAML Config Files

JSON and YAML config files (.playerrc, .playerrc.json, .playerrc.yaml, package.json, etc.) only support string and array formats (you cannot instantiate plugin classes in JSON):

String format:

JSON

{
  "plugins": [
    "@fancy-dog/dsl-plugin"
  ]
}

YAML

plugins:
  - "@fancy-dog/dsl-plugin"

Array with options format:

JSON

{
  "plugins": [
    ["@fancy-dog/dsl-plugin", { "customOption": "value" }]
  ]
}

YAML

plugins:
  - - "@fancy-dog/dsl-plugin"
    - customOption: "value"

Plugins

Plugins are the way to change runtime behavior of the CLI actions. This includes augmenting the behavior of the DSL compiler, language-service, and more. For detailed information on creating and using CLI plugins, see the CLI Plugins documentation.

Below are some plugins made available to you for your convenience.

LSPPluginPlugin

The LSPPluginPlugin allows you to add custom Language Service Plugins to the Player CLI configuration. This enables you to extend the LSP functionality with custom validation, completion, hover information, and more.

Usage:

import { LSPPluginPlugin } from "@player-ui/language-service";

const config = {
  plugins: [
    new LSPPluginPlugin([customPlugin1, customPlugin2])
  ]
};

For more information on creating Language Service Plugins, see the LSP documentation.

LSPTransformsPlugin

The LSPTransformsPlugin allows you to add custom XLR transform functions to the Player CLI configuration. This enables you to modify the types that are loaded into the LSP’s SDK. This may be useful if there is functionality that is available via a Plugin but isn’t part of core type definitions.

Usage:

import { LSPTransformsPlugin } from "@player-ui/language-service";

const config = {
  plugins: [
    new LSPTransformsPlugin({
      "exampleTransform1": exampleTransform1Fn,
      "exampleTransform2": exampleTransform2Fn,
    })
  ]
};

For more information on XLR transforms, see the XLR documentation.

LSPAssetsPlugin

The LSPAssetsPlugin allows you to load asset type definitions from packages into the Player CLI configuration. This enables the LSP to provide type checking, validation, and autocomplete for your custom assets and data types.

Usage:

import { LSPAssetsPlugin } from "@player-tools/cli";
import path from "path";

const config = {
  plugins: [
    new LSPAssetsPlugin(
      ["@player-ui/types", "@player-ui/reference-assets-plugin"].map((pkg) => ({
        path: path.join(
          path.dirname(require.resolve(`${pkg}/package.json`)),
          "dist",
        ),
      })),
    ),
  ],
};

For more information on loading asset types, see the LSP documentation.

Commands

• player dsl compile Compile Player DSL files into JSON after running TSC compiler against Typescript files

USAGE
  $ player dsl compile -i <value> [-c <value>] [-o <value>] [--skip-validation]

FLAGS
  -c, --config=<value>  Path to a specific config file to load.
                        By default, will automatically search for an rc or config file to load
  -i, --input=<value>   (required) An input directory to compile.
                        Any jsx/ts/tsx files will be loaded via babel-require automatically.
  -o, --output=<value>  [default: _out] Output directory to write results to
  --skip-validation     Option to skip validating the generated JSON

DESCRIPTION
  Compile Player DSL files into JSON after running TSC compiler against Typescript files

• player dsl validate Runs isolated TSC compiler on authored Player DSL Typescript files.

USAGE
  $ player dsl validate [-f <value>] [-c <value>]

FLAGS
  -c, --config=<value>  Path to a specific config file to load.
                        By default, will automatically search for an rc or config file to load
  -f, --files=<value>...  A list of files or globs to validate

DESCRIPTION
  Runs isolated TSC compiler on authored Player DSL Typescript files.

• player json validate Validate Player JSON content

USAGE
  $ player json validate -f <value> [-c <value>]

FLAGS
  -c, --config=<value>    Path to a specific config file to load.
                          By default, will automatically search for an rc or config file to load
  -f, --files=<value>...  (required) A list of files or globs to validate

DESCRIPTION
  Validate Player JSON content

• player dependency-versions check Checks for @player-ui/@player-tools dependency version mismatches and issues warnings/solutions accordingly

USAGE
  $ player dependency-versions check [-c <value>] [-v] [-p] [-i <value>]
FLAGS
  -c, --config=<value>     Path to a specific config file to load.
                           By default, will automatically search for an rc or config file to load
  -i, --ignore=<value>...  Ignore the specified pattern(s) when outputting results. Note multiple patterns can be passed
  -p, --path               Outputs full path to dependency
  -v, --verbose            Give verbose description
DESCRIPTION
  Checks for `@player-ui/@player-tools` dependency version mismatches and issues warnings/solutions accordingly
  Consider the following:
  - The interpretation of TOP-LEVEL and NESTED dependencies is as follows:
  a. TOP-LEVEL dependencies only have one 'node_modules' in their path
  b. NESTED dependencies have more than one 'node_modules' in their path
  - `@player-ui/@player-tools` dependencies are fetched not only from inside the 'node_modules' at the top of the repository in which it is run but also from 'node_modules' in sub-directories.
  For example, if you have some 'node_modules' inside of a 'packages' folder that contains `@player-ui/@player-tools` dependencies, then these will also be fetched.
  The display of such dependencies also depends on the first bullet point.