• Public
  • Public/Protected
  • All

Class Messages

The core message framework manages messages and allows them to be accessible by all plugins and consumers of sfdx-core. It is set up to handle localization down the road at no additional effort to the consumer. Messages can be used for anything from user output (like the console), to error messages, to returned data from a method.

Messages are loaded from loader functions. The loader functions will only run when a message is required. This prevents all messages from being loaded into memory at application startup. The functions can load from memory, a file, or a server.

In the beginning of your app or file, add the loader functions to be used later. If using json or js files in a root messages directory (<moduleRoot>/messages), load the entire directory automatically with Messages.importMessagesDirectory. Message files must be in .json or .js that exports a json object with only top level key-value pairs. The values support util.format style strings that apply the tokens passed into {@link Message.getMessage}

A sample message file.

   'msgKey': 'A message displayed in the terminal'

Note: When running unit tests individually, you may see errors that the messages aren't found. This is because index.js isn't loaded when tests run like they are when the package is required. To allow tests to run, import the message directory in each test (it will only do it once) or load the message file the test depends on individually.

// Create loader functions for all files in the messages directory

// Now you can use the messages from anywhere in your code or file.
// If using importMessageDirectory, the bundle name is the file name.
const messages : Messages = Messages.loadMessages(packageName, bundleName);

// Messages now contains all the message in the bundleName file.


  • Messages




  • new Messages(bundleName: string, locale: string, messages: Map<string, AnyJson>): Messages
  • Create a new messages bundle.

    Note: Use {Messages.loadMessages} unless you are writing your own loader function.


    • bundleName: string

      The bundle name.

    • locale: string

      The locale.

    • messages: Map<string, AnyJson>

      The messages. Can not be modified once created.

    Returns Messages



bundleName: string

The bundle name.


locale: string

The locale of the messages in this bundle.



  • getMessage(key: string, tokens?: Tokens): string

Static generateFileLoaderFunction

  • generateFileLoaderFunction(bundleName: string, filePath: string): LoaderFunction

Static getLocale

  • getLocale(): string
  • Get the locale. This will always return 'en_US' but will return the machine's locale in the future.

    Returns string

Static importMessageFile

  • importMessageFile(packageName: string, filePath: string): void
  • Add a single message file to the list of loading functions using the file name as the bundle name. The loader will only be added if the bundle name is not already taken.


    • packageName: string

      The npm package name.

    • filePath: string

      The path of the file.

    Returns void

Static importMessagesDirectory

  • importMessagesDirectory(moduleDirectoryPath: string, truncateToProjectPath?: boolean, packageName?: undefined | string): void
  • Import all json and js files in a messages directory. Use the file name as the bundle key when Messages.loadMessages is called. By default, we're assuming the moduleDirectoryPart is a typescript project and will truncate to root path (where the package.json file is). If your messages directory is in another spot or you are not using typescript, pass in false for truncateToProjectPath.

    // e.g. If your message directory is in the project root, you would do:


    • moduleDirectoryPath: string

      The path to load the messages folder.

    • Default value truncateToProjectPath: boolean = true

      Will look for the messages directory in the project root (where the package.json file is located). i.e., the module is typescript and the messages folder is in the top level of the module directory.

    • Optional packageName: undefined | string

      The npm package name. Figured out from the root directory's package.json.

    Returns void

Static isCached

  • isCached(packageName: string, bundleName: string): boolean
  • Check if a bundle already been loaded.


    • packageName: string

      The npm package name.

    • bundleName: string

      The bundle name.

    Returns boolean

Static loadMessages

  • loadMessages(packageName: string, bundleName: string): Messages

Static setLoaderFunction

  • setLoaderFunction(packageName: string, bundle: string, loader: LoaderFunction): void
  • Set a custom loader function for a package and bundle that will be called on Messages.loadMessages.


    • packageName: string

      The npm package name.

    • bundle: string

      The name of the bundle.

    • loader: LoaderFunction

      The loader function.

    Returns void