@stackline/unified-engine

Process files with unified plugins, configuration, and ignore rules using the unified-engine 10 callback API.

Documentation | npm | Issues | Repository

Current package version: 1.0.4

Why this package?

Maintained MIT-licensed fork of [email protected], retaining its callback API and unified 10 / vfile 5 type model. Requires Node.js 20.19+ on the 20.x line, or Node.js 22.12+.

The file finder uses glob 13 with brace-aware magic detection and a Promise-to-callback bridge. @stackline/load-plugin removes obsolete glob/inflight dependencies from the plugin-resolution path while preserving the original options.

Development: npm ci, npm run build, npm test, npm run lint. npm run build validates the preserved published declarations with modern TypeScript; it does not regenerate unrelated legacy JSDoc. See UPSTREAM-TYPES.md. Tests include the upstream integration suite and focused glob regressions.

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

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.

Compatibility

| Item | Value | | --- | --- | | Package | @stackline/[email protected] | | Supported Node.js | ^20.19.0 || >=22.12.0 | | Module entry | index.js (ES modules) | | Runtime dependencies | 22 direct dependencies | | Types | index.d.ts |

This fork supports Node.js 20.19+ on the 20.x line, and Node.js 22.12+. The callback API and unified 10 / vfile 5 type model are preserved.

Installation

npm install @stackline/unified-engine

This package is ESM only. In Node.js (20.19+ on the 20.x line, or 22.12+), install with npm:

npm install @stackline/unified-engine

Usage

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 '@stackline/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
}

Security

Plugins and JavaScript configuration can execute code. Review the existing security guidance before processing an untrusted project.

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.

API Surface

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) — name 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

Local Development

Clone the repository and run the following commands from its root:

npm ci
npm run build
npm test
npm run lint
npm run test:types

The retained upstream development notes below include historical tooling; the commands above are the maintained package checks.

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.

Release Checklist

1. Update the package version, lockfile, generated version fields, and changelog together.
2. Run the development checks above and audit both npm audit and npm audit --omit=dev.
3. Use the GitHub publish workflow with its Prod environment to publish the exact CI tarball.
4. Verify public npm bytes, package identity, provenance, and the immutable GitHub release evidence.

License

MIT. Original copyright notices and upstream attribution are retained.

MIT © Titus Wormer

See NOTICE for retained attribution.

Credits and original authors

• Original project: unified-engine.
• Titus Wormer.
• Christian Murphy.
• Copyright (c) 2016 Titus Wormer [email protected].
• Stackline modifications Copyright 2026 Stackline contributors.
• Stackline maintenance: Alexandro Paixao Marques and Stackline contributors.

Original copyright, license notices and contributor acknowledgements remain part of this distribution. Stackline maintenance does not replace authorship of the original work.

Community and Links

• Stackline website
• GitHub projects
• npm packages
• Reddit community — r/Stackline
• Maintainer LinkedIn

Use this repository's issue tracker for reproducible bugs and feature requests. Join r/Stackline for examples, usage questions and release discussions.