@oclif/core v4 Proposal

[mdonnalley]

We've begun thinking about what we'd like to accomplish in the next major version of @oclif/core. Below is a list of changes that we're considering - we'd love any and all feedback!

Slimmer ux module

As described here, we're removing most of the methods in the ux module. We're simply unable to adequately support the feature set that ux offers and think that most people would benefit from using dedicated libraries that are better supported.

We are, however, keeping some of the functionality. The new ux module will contain the following:

Unchanged

• colorize
• error
• exit
• action - will be unchanged from previous version except that the spinner color will be configurable using themes.
• warn

Renamed

• stdout - rename of ux.log
• stderr - rename of ux.logToStderr

New

• colorizeJson - Apply color theme to arbitrary JSON.

What you'll need to do

You will need to replace everything that ux was doing with dedicated libraries. Here are a few suggestions:

• For prompts: inquirer
• For progress bars: cli-progress
• For hyperlinks: hyperlink
• For tables: tty-table, cliui
• For trees: object-treeify
• For notifications: node-notifier
• For links: terminal-link
• For rendering react components: ink

Customizable Logger

In the current major version, we exclusively use debug for debug logs. In the next major, we're going to export a Logger interface that will allow you to provide a custom logger for @oclif/core to use. This will be useful if you want all the @oclif/core debug logs to go through your own logger.

The default logger will continue to use debug under the hood. So if you choose to use the default, you can continue to use the DEBUG environment variable to access the debug logs in the console. The only breaking change will be that the namespace for all the logs with be prefixed with a root namespace, oclif.

So if you're used to using DEBUG=config:* my-cli do stuff, you'll need to start doing this instead: DEBUG=oclif:config:* my-cli do stuff

Proposed Interface

export type Logger = {
  debug: (formatter: unknown, ...args: unknown[]) => void
  error: (formatter: unknown, ...args: unknown[]) => void
  info: (formatter: unknown, ...args: unknown[]) => void
  trace: (formatter: unknown, ...args: unknown[]) => void
  warn: (formatter: unknown, ...args: unknown[]) => void
  child: (namespace: string) => Logger
  namespace: string
}

Proposed Usage

// oclif-logger.ts
import { format } from 'node:util';
import { Interfaces } from '@oclif/core';
import { Logger } from './my-cli-logger';

export const customLogger = (namespace: string): Interfaces.Logger => {
  const myLogger = new Logger(namespace);
  return {
    child: (ns: string, delimiter?: string) => customLogger(`${namespace}${delimiter ?? ':'}${ns}`),
    debug: (formatter: unknown, ...args: unknown[]) => myLogger.debug(format(formatter, ...args)),
    error: (formatter: unknown, ...args: unknown[]) => myLogger.error(format(formatter, ...args)),
    info: (formatter: unknown, ...args: unknown[]) => myLogger.info(format(formatter, ...args)),
    trace: (formatter: unknown, ...args: unknown[]) => myLogger.trace(format(formatter, ...args)),
    warn: (formatter: unknown, ...args: unknown[]) => myLogger.warn(format(formatter, ...args)),
    namespace,
  };
};

export const logger = customLogger('sf');

// bin/run.js
#!/usr/bin/env node

async function main() {
  const {execute} = await import('@oclif/core');
  const { logger } = await import('../dist/oclif-logger.js');
  await oclif.execute({
    dir: import.meta.url,
    loadOptions: {
      root: import.meta.dirname,
      logger,
    },
  });
}

await main();

You can also provide the logger to Config, in the event that you instantiate Config before calling run or execute

import {Config, run} from '@oclif/core'
const config = await config.load({
  logger,
});

await run(process.argv.slice(2), config)

Support for rc files

Currently the configuration for oclif must live inside the oclif section of your CLI or plugin's package.json. This can be difficult if you have a large amount of configuration, you want to dynamically change the configuration, or want to ensure that your configuration is correctly typed.

To solve this, we can use a library like cosmiconfig or lilconfig to read in a variety of rc files.

Despite being able to use an rc file, @oclif/core will still be dependent on your package.json to get the name, version, and dependencies. We could ask that you put those value in your rc file, but duplicating that information across two files feels like something people would rather not do.

If you choose to use an rc file, one thing you must consider is that there will be a slight performance hit due to needing to search for the rc file in addition to the package.json.

Small Bits

Improved Interfaces.PJSON

The current interface is not as well organized as we would like. It would also be nice to be able to export an OclifConfig interface that people could use for .ts rc files

Improve types by enabling exactOptionalPropertyTypes

While we're improving types, we would also address #960

Apply target/identifier logic to custom help classes

In case you missed it, we introduced new command discovery strategies that make bundling possible. In order to do that, the location of commands and hooks needed to be configured using a target (i.e. a file or directory containing the commands or hooks) and an identifier (i.e. the name of the export inside the target).

This change only works for commands and hooks so in the next major we'd apply the same logic to custom help classes so that those can be bundled as well.

Remove default property from config

The default property was used for single command CLIs before command discovery strategies were added. Instead of using the default property, checkout the documentation on how to use the single strategy

Top level exports

We'll have top level exports for:

• 'args'
• 'command'
• 'config'
• 'errors'
• 'execute'
• 'flags'
• 'flush'
• 'handle'
• 'help'
• 'hooks'
• 'interfaces'
• logger
• 'performance'
• 'run'
• 'settings'
• 'util/ids'
• 'ux'

The current way of accessing these looks like this:

import {run, flush, handle} from '@oclif/core'

With top level exports, you could access those like this:

import run from '@oclif/core/run'
import flush from '@oclif/core/flush'
import handle from '@oclif/core/handle'

The benefit of this is that you'll be able to import those utilities without also importing everything else that @oclif/core exports.

As a result of this change, deep imports (e.g. import {Command} from '@oclif/core/lib/command.js will no longer work.

Remove support for baseFlags

We've decided to NOT move forward with this

Currently, in order for one Command class to inherit flags from another Command class is to use a property called baseFlags (see docs).

This solution assumes that you'll only ever have one layer of abstraction, which is not a safe assumption. So in order for commands to inherit flags from multiple parents you have to use the spread operator

import {Command, Flags} from '@oclif/core'

abstract class BaseCommand1 extends Command {
  static baseFlags = {
    loglevel: Flags.boolean()
  }
}

abstract class BaseCommand2 extends BaseCommand1 {
  static baseFlags = {
    ...BaseCommand1.baseFlags,
    verbose: Flags.boolean()
  }
}

abstract class BaseCommand3 extends BaseCommand2 {
  static baseFlags = {
    ...BaseCommand2.baseFlags,
    silent: Flags.boolean()
  }
}

export default class MyCommand extends BaseCommand3 {
  static flags = {
    username: Flags.string()
  }
}

Because of this, we're proposing that we remove baseFlags and require the spread operator anytime you want flags to be inherited. So the above example would change to this:

import {Command, Flags} from '@oclif/core'

abstract class BaseCommand1 extends Command {
  static flags = {
    loglevel: Flags.boolean()
  }
}

abstract class BaseCommand2 extends BaseCommand1 {
  static flags = {
    ...BaseCommand1.flags,
    verbose: Flags.boolean()
  }
}

abstract class BaseCommand3 extends BaseCommand2 {
  static flags = {
    ...BaseCommand2.flags,
    silent: Flags.boolean()
  }
}

export default class MyCommand extends BaseCommand3 {
  static flags = {
    ...BaseCommand3.flags,
    username: Flags.string()
  }
}

The downside is that it will require an extra line of code for those who are only using a single base Command class but the upside is that there won't be any confusion about the difference between baseFlags and flags and when to use each.

[mdonnalley]

Closing this since v4 has now been released: https://github.com/oclif/core/releases/tag/4.0.0