unified-engine

unified engine to process multiple files, lettings users configure from the file system.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • engine(options, callback)
• Plugins
• Configuration
• Ignoring
• Types
• Compatibility
• Security
• Contribute
• License

What is this?

This package is the engine. It’s what you use underneath when you use remark-cli or a language server. Compared to unified, this deals with multiple files, often from the file system, and with configuration files and ignore files.

When should I use this?

You typically use something that wraps this, such as:

• unified-args — create CLIs
• unified-engine-gulp — create Gulp plugins
• unified-language-server — create language servers

You can use this to make such things.

Install

This package is ESM only. In Node.js (version 14.14+, 16.0+, or 18.0+), install with npm:

npm install unified-engine

Use

The following example processes all files in the current directory with a markdown extension with remark, allows configuration from .remarkrc and package.json files, ignoring files from .remarkignore files, and more.

/**
 * @typedef {import('unified-engine').Callback} Callback
 */

import {engine} from 'unified-engine'
import {remark} from 'remark'

engine(
  {
    processor: remark,
    files: ['.'],
    extensions: ['md', 'markdown', 'mkd', 'mkdn', 'mkdown'],
    pluginPrefix: 'remark',
    rcName: '.remarkrc',
    packageField: 'remarkConfig',
    ignoreName: '.remarkignore',
    color: true
  },
  done
)

/** @type {Callback} */
function done(error) {
  if (error) throw error
}

API

This package exports the identifier engine. There is no default export.

engine(options, callback)

Process files according to options and call callback when done.

options

• processor (Processor) — unified processor to transform files
• cwd (string or URL, default: process.cwd()) — directory to search files in, load plugins from, and more
• files (Array<string|URL|VFile>, optional) — paths or globs to files and directories, virtual files, or URLs, to process
• extensions (Array<string>, optional) — if files matches directories, include files with extensions
• streamIn (ReadableStream, default: process.stdin) — stream to read from if no files are found or given
• filePath (string, optional) — file path to process the given file on streamIn as
• streamOut (WritableStream, default: process.stdout) — stream to write processed files to
• streamError (WritableStream, default: process.stderr) — stream to write the report (if any) to
• out (boolean, default: depends) — whether to write the processed file to streamOut
• output (boolean or string, default: false) — whether to write successfully processed files, and where to
• alwaysStringify (boolean, default: false) — whether to always serialize successfully processed files
• tree (boolean, default: false) — whether to treat both input and output as a syntax tree
• treeIn (boolean, default: tree) — whether to treat input as a syntax tree
• treeOut (boolean, default: tree) — whether to treat output as a syntax tree
• inspect (boolean, default: false) — whether to output a formatted syntax tree
• rcName (string, optional) — wame of configuration files to load
• packageField (string, optional) — property at which configuration can be found in package.json files
• detectConfig (boolean, default: whether rcName or packageField is given) — whether to search for configuration files
• rcPath (string, optional) — filepath to a configuration file to load
• settings (Object, optional) — configuration for the parser and compiler of the processor
• ignoreName (string, optional) — name of ignore files to load
• detectIgnore (boolean, default: whether ignoreName is given) — whether to search for ignore files
• ignorePath (string, optional) — filepath to an ignore file to load
• ignorePathResolveFrom ('dir' or 'cwd', default: 'dir') — resolve patterns in ignorePath from the current working directory or the file’s directory
• ignorePatterns (Array<string>, optional) — patterns to ignore in addition to ignore files, if any
• ignoreUnconfigured (boolean, default: false) — ignore files that do not have an associated detected configuration file
• silentlyIgnore (boolean, default: false) — skip given files if they are ignored
• plugins (Array|Object, optional) — plugins to use
• pluginPrefix (string, optional) — optional prefix to use when searching for plugins
• configTransform (Function, optional) — transform config files from a different schema
• reporter (string or function, default: import {reporter} from 'vfile-reporter') — reporter to use
• reporterOptions (Object?, optional) — config to pass to the used reporter
• color (boolean, default: false) — whether to report with ANSI color sequences
• silent (boolean, default: false) — report only fatal errors
• quiet (boolean, default: silent) — do not report successful files
• frail (boolean, default: false) — call back with an unsuccessful (1) code on warnings as well as errors

function callback(error[, code, context])

Called when processing is complete, either with a fatal error if processing went horribly wrong (probably due to incorrect configuration on your part as a developer), or a status code and the processing context.

Parameters

• error (Error) — fatal error
• code (number) — either 0 if successful, or 1 if unsuccessful, the latter occurs if fatal errors happen when processing individual files, or if frail is set and warnings occur
• context (Object) — processing context, containing internally used information and a files array with the processed files

Plugins

doc/plugins.md describes in detail how plugins can add more files to be processed and handle all transformed files.

Configuration

doc/configure.md describes in detail how configuration files work.

Ignoring

doc/ignore.md describes in detail how ignore files work.

Types

This package is fully typed with TypeScript. It additionally exports the following types:

• VFileReporterOptions — models options passed to vfile reporters
• VFileReporter — models the signature accepted as a vfile reporter
• FileSet — models what is passed to plugins as a second parameter
• Completer — models file set plugins
• ResolveFrom — models the enum allowed for options.ignorePathResolveFrom
• ConfigTransform — models the signature of options.configTransform
• Preset — models a preset, like Preset from unified but accepts strings
• Options — models configuration
• Context — models the third parameter to callback
• Callback — models the signature of callback

Compatibility

Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 14.14+, 16.0+, and 18.0+. Our projects sometimes work with older versions, but this is not guaranteed.

Security

unified-engine loads and evaluates configuration files, plugins, and presets from the file system (often from node_modules/). That means code that is on your file system runs. Make sure you trust the workspace where you run unified-engine and be careful with packages from npm and changes made by contributors.

Contribute

See contributing.md in unifiedjs/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Titus Wormer