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
  • engineGulp(options)
  • FileStream
  • Options
• 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 16+), install with npm:

npm install unified-engine-gulp

Use

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

export const gulpRemark = engineGulp({
  ignoreName: '.remarkignore',
  name: 'gulp-remark',
  packageField: 'remarkConfig',
  pluginPrefix: 'remark',
  processor: remark,
  rcName: '.remarkrc'
})

API

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

engineGulp(options)

Create a Gulp plugin.

👉 Note: see writing a Gulp plugin for more info.

Parameters

• options (Options, required]) — configuration

Returns

Gulp plugin, which can be called with options (same as Options but w/o name or processor) and returns a through2 stream accepting Vinyl files (FileStream).

FileStream

File stream (TypeScript type).

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 or a preset. It returns the operated on fileStream.

Type

import type {Transform} from 'node:stream'

type FileStream = Transform & {use: Use}

type Use = (...values: unknown[]) => FileStream

Options

Configuration (TypeScript type).

Type

import type {EngineOptions} from 'unified-engine'

type Options = {name: string} & Omit<
  EngineOptions,
  | 'alwaysStringify'
  | 'cwd'
  | 'extensions'
  | 'files'
  | 'out'
  | 'output'
  | 'plugins'
  | 'silentlyIgnore'
  | 'streamIn'
  | 'streamOut'
>

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 exports the additional types FileStream and Options.

Compatibility

Projects maintained by the unified collective are compatible with maintained versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line, unified-engine-gulp@^11, compatible with Node.js 16.

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.

License

MIT © Titus Wormer