OXFmt and OXLint support for PlugJS

This plugin adds support for OXLint and OXFmt in PlugJS builds.

Contents

• Installation
• Linting
  • Standalone linting
• Formatting
  • Standalone formatting
• Combined Formatting and Linting
  • Standalone formatting and linting
• Default Configurations
• Apache 2.0 License
• Copyright Notice

Installation

npm install --save-dev @plugjs/oxc

Linting

Linting support is provided by the oxlint plug.

import '@plugjs/oxc'
import { find, plugjs } from '@plugjs/plug'

export default plugjs({
  // ... all your other tasks
  async lint(): Promise<void> {
    await find('**/*', { directory: 'src' }).oxlint(/* ...config file or options */)
  },
})

The side-effect import import '@plugjs/oxc' installs the .oxlint() pipe method.

The oxlint plug by default will look for the default configuration files as specified in the OXLint documentation.

Alternatively, it can be parameterized by specifying a configuration file or a set of options which includes the following:

• config: The path to the OXLint configuration file (string).
• tsConfig: The path to the TypeScript configuration file (string).
• fix: Whether to automatically fix linting errors (boolean, default: false).
• reportUnusedDisableDirectives: Whether to report unused disable directives (boolean, default: true).
• cwd: The current working directory for OXLint (string, default: current directory).

Standalone linting

OXLint can also be used directly as a utility (without piping file lists):

import { oxlint } from '@plugjs/oxc'
import { plugjs } from '@plugjs/plug'

export default plugjs({
  // ... all your other tasks
  async lint(): Promise<void> {
    await oxlint(/* ...paths to lint or options */)
  },
})

In this case, the paths to lint can be specified directly as string parameters (defaulting to all files in the current directory) or using the options specified above with the addition of:

• paths: The list of paths to lint (array of strings).

NOTE: Those are paths, not matching globs. Specifically, OXLint does NOT support negative globs (e.g., !something) and will fail if you try to use them.

Formatting

Formatting support is provided by the oxfmt plug.

import '@plugjs/oxc'
import { find, plugjs } from '@plugjs/plug'

export default plugjs({
  // ... all your other tasks
  async format(): Promise<void> {
    await find('**/*', { directory: 'src' }).oxfmt(/* ...config file or options */)
  },
})

The side-effect import import '@plugjs/oxc' installs the .oxfmt() pipe method.

The oxfmt plug by default will look for the default configuration files as specified in the OXFmt documentation.

Alternatively, it can be parameterized by specifying a configuration file or a set of options which includes the following:

• config: The path to the OXFmt configuration file (string).
• fix: Whether to automatically fix formatting errors (boolean, default: false).
• warnOnFormat: Whether to report formatting inconsistencies as warnings instead of errors (boolean, default: false).
• cwd: The current working directory for OXFmt (string, default: current directory).

Standalone formatting

OXFmt can also be used directly as a utility (without piping file lists):

import { oxfmt } from '@plugjs/oxc'
import { plugjs } from '@plugjs/plug'

export default plugjs({
  // ... all your other tasks
  async format(): Promise<void> {
    await oxfmt(/* ...paths to format or options */)
  },
})

In this case, the paths to format can be specified directly as string parameters (defaulting to all files in the current directory) or using the options specified above with the addition of:

• paths: The list of paths to format (array of strings).

Combined Formatting and Linting

Combined formatting and linting support is provided by the oxc plug. It runs OXFmt first, then OXLint, creating a single report for both operations.

import '@plugjs/oxc'
import { find, plugjs } from '@plugjs/plug'

export default plugjs({
  // ... all your other tasks
  async check(): Promise<void> {
    await find('**/*', { directory: 'src' }).oxc(/* ...options */)
  },
})

The side-effect import import '@plugjs/oxc' installs the .oxc() pipe method.

The oxc plug by default will look for the default configuration files as specified in the OXFmt and OXLint documentation.

Alternatively, it can be parameterized by specifying a set of options which includes the following:

• oxfmtConfig: The path to the OXFmt configuration file (string).
• oxlintConfig: The path to the OXLint configuration file (string).
• tsConfig: The path to the TypeScript configuration file (string).
• fix: Whether to automatically fix formatting and linting errors (boolean, default: false).
• warnOnFormat: Whether to report formatting inconsistencies as warnings instead of errors (boolean, default: false).
• reportUnusedDisableDirectives: Whether to report unused disable directives (boolean, default: true).
• cwd: The current working directory for OXFmt and OXLint (string, default: current directory).

Standalone formatting and linting

OXFmt and OXLint can also be used together directly as a utility (without piping file lists):

import { oxc } from '@plugjs/oxc'
import { plugjs } from '@plugjs/plug'

export default plugjs({
  // ... all your other tasks
  async check(): Promise<void> {
    await oxc(/* ...paths to format and lint or options */)
  },
})

In this case, the paths to format and lint can be specified directly as string parameters (defaulting to all files in the current directory) or using the options specified above with the addition of:

• paths: The list of paths to format and lint (array of strings).

NOTE: Those are paths, not matching globs. Specifically, OXLint does NOT support negative globs (e.g., !something) and will fail if you try to use them.

Default Configurations

This package also exports default OXFmt and OXLint configurations:

• @plugjs/oxc/configs/oxfmt: The default OXFmt configuration.
• @plugjs/oxc/configs/oxlint: The default OXLint configuration, kept as generic as possible.
• @plugjs/oxc/configs/oxlint.node: The default OXLint configuration extended with the node plugin for Node.js projects.

For example, an OXFmt configuration in another project can start from the default configuration like this:

import { defineConfig } from 'oxfmt'

import config from '@plugjs/oxc/configs/oxfmt'

export default defineConfig({
  // OXFmt does not support an `extends` option, so spread the default config.
  ...config,
})

An OXLint configuration can import either the generic default configuration or the Node.js-specific one:

import { defineConfig } from 'oxlint'

import config from '@plugjs/oxc/configs/oxlint.node'

export default defineConfig({
  extends: [config],
})