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
- 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 CLIsunified-engine-gulp
— create Gulp pluginsunified-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 filescwd
(string
orURL
, default:process.cwd()
) — directory to search files in, load plugins from, and morefiles
(Array<string|URL|VFile>
, optional) — paths or globs to files and directories, virtual files, or URLs, to processextensions
(Array<string>
, optional) — iffiles
matches directories, include files withextensions
streamIn
(ReadableStream
, default:process.stdin
) — stream to read from if no files are found or givenfilePath
(string
, optional) — file path to process the given file onstreamIn
asstreamOut
(WritableStream
, default:process.stdout
) — stream to write processed files tostreamError
(WritableStream
, default:process.stderr
) — stream to write the report (if any) toout
(boolean
, default: depends) — whether to write the processed file tostreamOut
output
(boolean
orstring
, default:false
) — whether to write successfully processed files, and where toalwaysStringify
(boolean
, default:false
) — whether to always serialize successfully processed filestree
(boolean
, default:false
) — whether to treat both input and output as a syntax treetreeIn
(boolean
, default:tree
) — whether to treat input as a syntax treetreeOut
(boolean
, default:tree
) — whether to treat output as a syntax treeinspect
(boolean
, default:false
) — whether to output a formatted syntax treercName
(string
, optional) — wame of configuration files to loadpackageField
(string
, optional) — property at which configuration can be found inpackage.json
filesdetectConfig
(boolean
, default: whetherrcName
orpackageField
is given) — whether to search for configuration filesrcPath
(string
, optional) — filepath to a configuration file to loadsettings
(Object
, optional) — configuration for the parser and compiler of the processorignoreName
(string
, optional) — name of ignore files to loaddetectIgnore
(boolean
, default: whetherignoreName
is given) — whether to search for ignore filesignorePath
(string
, optional) — filepath to an ignore file to loadignorePathResolveFrom
('dir'
or'cwd'
, default:'dir'
) — resolve patterns inignorePath
from the current working directory or the file’s directoryignorePatterns
(Array<string>
, optional) — patterns to ignore in addition to ignore files, if anyignoreUnconfigured
(boolean
, default:false
) — ignore files that do not have an associated detected configuration filesilentlyIgnore
(boolean
, default:false
) — skip given files if they are ignoredplugins
(Array|Object
, optional) — plugins to usepluginPrefix
(string
, optional) — optional prefix to use when searching for pluginsconfigTransform
(Function
, optional) — transform config files from a different schemareporter
(string
orfunction
, default:import {reporter} from 'vfile-reporter'
) — reporter to usereporterOptions
(Object?
, optional) — config to pass to the used reportercolor
(boolean
, default:false
) — whether to report with ANSI color sequencessilent
(boolean
, default:false
) — report only fatal errorsquiet
(boolean
, default:silent
) — do not report successful filesfrail
(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 errorcode
(number
) — either0
if successful, or1
if unsuccessful, the latter occurs if fatal errors happen when processing individual files, or iffrail
is set and warnings occurcontext
(Object
) — processing context, containing internally used information and afiles
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 reportersVFileReporter
— models the signature accepted as a vfile reporterFileSet
— models what is passed to plugins as a second parameterCompleter
— models file set pluginsResolveFrom
— models the enum allowed foroptions.ignorePathResolveFrom
ConfigTransform
— models the signature ofoptions.configTransform
Preset
— models a preset, likePreset
fromunified
but accepts stringsOptions
— models configurationContext
— models the third parameter tocallback
Callback
— models the signature ofcallback
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.