unified-engine-gulp

unified engine to create a Gulp plugin from a processor

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
unified-engine-gulp
6010.0.07 months ago7 years agoMinified + gzip package size for unified-engine-gulp in KB

Readme

unified-engine-gulp
!Buildbuild-badgebuild !Coveragecoverage-badgecoverage !Downloadsdownloads-badgedownloads !Sponsorssponsors-badgecollective !Backersbackers-badgecollective !Chatchat-badgechat
unified engine to create a Gulp plugin from a unified processor.

Contents

*   [`engineGulp(options)`](#enginegulpoptions)

What is this?

This package wraps unified-engineunified-engine so that it can be used to create a Gulp plugin. It’s what you use underneath when you use gulp-remarkgulp-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 onlyesm. 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 pluginplugin 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.processorprocessor
Processor to inspect and transform files (Processorunified-processor, required).
options.streamErrorstream-error
Stream to write the report (if any) to (WritableStream, default: process.stderr).
options.treetree
Whether to treat both input and output as a syntax tree (boolean, default: false).
options.treeIntree-in
Whether to treat input as a syntax tree (boolean, default: tree).
options.treeOuttree-out
Whether to treat output as a syntax tree (boolean, default: tree).
options.inspectinspect
Skip the compilation phase and output a syntax tree formatted with unist-util-inspectunist-util-inspect (boolean, default: false).
options.rcNamerc-name
Name of configuration files to load (string, optional).
options.packageFieldpackage-field
Field at which configuration can be found in package.json files (string, optional).
options.detectConfigdetect-config
Whether to search for configuration files (boolean, default: whether rcName or packageField is given).
options.rcPathrc-path
File-path to a configuration file to load (string, optional).
options.settingssettings
Configuration for the parser and compiler of the processor (Object, optional).
options.ignoreNameignore-name
Name of ignore files to load (string, optional).
options.detectIgnoredetect-ignore
Whether to search for ignore files (boolean, default: whether ignoreName is given).
options.ignorePathignore-path
File-path to an ignore file to load (string, optional).
options.ignorePathResolveFromignore-path-resolve-from
Whether to resolve patterns in ignorePath relative to its directory or the current working directory ('dir' or 'cwd', default: 'dir').
options.ignorePatternsignore-patterns
Extra patterns to ignore in combination with ignorePath or found ignores (Array<string>, optional).
options.pluginsplugins
Map of plug-in names or paths and options to use (Object, optional).
options.pluginPrefixplugin-prefix
When given, optional prefix to use when searching for plug-ins (string, optional).
options.defaultConfigdefault-config
Optional object with plugins and/or settings to use if no config file is supplied by the user (Object, optional).
options.configTransformconfig-transform
Transform config files from a different schema (Function, optional).
options.reporterreporter
Reporter to use (string or function, default: require('vfile-reporter')).
options.reporterOptionsreporteroptions
Config to pass to the used reporter (Object?, optional).
options.colorcolor
Whether to report with ANSI color sequences (boolean, default: false).
options.silentsilent
Report only fatal errors (boolean, default: false).
options.quietquiet
Do not report successful files (boolean, default: silent).
options.frailfrail
Treat warnings as errors (boolean, default: false).
Returns
An through2through2 object stream, accepting Vinyl files (fileStream). Streaming vinyl files are not supported. Read more about why in Gulp’s docs (point 10)streaming.
There’s also a fileStream.use() function, which is like unified.use()use, in that it accepts a plugin and configuration. It returns the operated on fileStream.

Debugging

The engine can be debugged by setting the DEBUGdebug 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.mdcontributing in unifiedjs/.githubhealth for ways to get started. See support.mdsupport for ways to get help.
This project has a code of conductcoc. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MITlicense © Titus Wormerauthor