unified-engine-gulp
unified engine to create a Gulp plugin from a unified processor.
Contents
- What is this?
- When should I use this?
- Install
- Use
- API
- Debugging
- Types
- Compatibility
- Security
- Contribute
- License
What is this?
This package wraps unified-engine
so that it can be used to create a Gulp plugin. It’s what you use underneath when you use gulp-remark
.
When should I use this?
You can use this to let users process files from a gulp plugin, letting them configure from the file system.
Install
This package is ESM only. In Node.js (version 14.14+, 16.0+, or 18.0+), install with npm:
npm install unified-engine-gulp
Use
import {engineGulp} from 'unified-engine-gulp'
import {remark} from 'remark'
export const gulpRemark = engineGulp({
name: 'gulp-remark',
processor: remark,
rcName: '.remarkrc',
packageField: 'remarkConfig',
ignoreName: '.remarkignore',
pluginPrefix: 'remark'
})
API
This package exports the identifier engineGulp
. There is no default export.
engineGulp(options)
Create a Gulp plugin from a unified processor.
👉 Note: see writing a Gulp plugin for more info.
options
Anything not passed in options
, but in the below list, can be set later by users of the plugin.
options.name
(string
, required)
Name of Gulp plugin (used in errors).
options.processor
Processor to inspect and transform files (Processor
, required).
options.streamError
Stream to write the report (if any) to (WritableStream
, default: process.stderr
).
options.tree
Whether to treat both input and output as a syntax tree (boolean
, default: false
).
options.treeIn
Whether to treat input as a syntax tree (boolean
, default: tree
).
options.treeOut
Whether to treat output as a syntax tree (boolean
, default: tree
).
options.inspect
Skip the compilation phase and output a syntax tree formatted with unist-util-inspect
(boolean
, default: false
).
options.rcName
Name of configuration files to load (string
, optional).
options.packageField
Field at which configuration can be found in package.json
files (string
, optional).
options.detectConfig
Whether to search for configuration files (boolean
, default: whether rcName
or packageField
is given).
options.rcPath
File-path to a configuration file to load (string
, optional).
options.settings
Configuration for the parser and compiler of the processor (Object
, optional).
options.ignoreName
Name of ignore files to load (string
, optional).
options.detectIgnore
Whether to search for ignore files (boolean
, default: whether ignoreName
is given).
options.ignorePath
File-path to an ignore file to load (string
, optional).
options.ignorePathResolveFrom
Whether to resolve patterns in ignorePath
relative to its directory or the current working directory ('dir'
or 'cwd'
, default: 'dir'
).
options.ignorePatterns
Extra patterns to ignore in combination with ignorePath
or found ignores (Array<string>
, optional).
options.plugins
Map of plug-in names or paths and options to use (Object
, optional).
options.pluginPrefix
When given, optional prefix to use when searching for plug-ins (string
, optional).
options.defaultConfig
Optional object with plugins and/or settings to use if no config file is supplied by the user (Object
, optional).
options.configTransform
Transform config files from a different schema (Function
, optional).
options.reporter
Reporter to use (string
or function
, default: require('vfile-reporter')
).
options.reporterOptions
Config to pass to the used reporter (Object?
, optional).
options.color
Whether to report with ANSI color sequences (boolean
, default: false
).
options.silent
Report only fatal errors (boolean
, default: false
).
options.quiet
Do not report successful files (boolean
, default: silent
).
options.frail
Treat warnings as errors (boolean
, default: false
).
Returns
An through2
object stream, accepting Vinyl files (fileStream
). Streaming vinyl files are not supported. Read more about why in Gulp’s docs (point 10).
There’s also a fileStream.use()
function, which is like unified.use()
, in that it accepts a plugin and configuration. It returns the operated on fileStream
.
Debugging
The engine can be debugged by setting the DEBUG
environment variable to *
, such as DEBUG="*" gulp …
.
Types
This package is fully typed with TypeScript. It export the additional types Options
and FileStream
.
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-gulp
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-gulp
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.