# gulp-plugin-extras

> Useful utilities for creating Gulp plugins

Latest version **1.1.0** (published 2024-10-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install gulp-plugin-extras
pnpm add gulp-plugin-extras
yarn add gulp-plugin-extras
bun add gulp-plugin-extras
```

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2024-10-14 |
| First published | 2023-10-31 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=18 |
| Dependencies | 3 |
| Unpacked size | 11.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 14 |
| Author | Sindre Sorhus |
| Maintainers | sindresorhus |
| Keywords | gulp, plugin, extras, utilities |

## Links

- npm: https://www.npmjs.com/package/gulp-plugin-extras
- Repository: https://github.com/sindresorhus/gulp-plugin-extras
- Homepage: https://github.com/sindresorhus/gulp-plugin-extras#readme
- Issues: https://github.com/sindresorhus/gulp-plugin-extras/issues
- Funding: https://github.com/sponsors/sindresorhus
- npm.io page: https://npm.io/package/gulp-plugin-extras

## Dependencies (3)

- [chalk](https://npm.io/package/chalk.md) ^5.3.0
- [@types/vinyl](https://npm.io/package/@types/vinyl.md) ^2.0.12
- [easy-transform-stream](https://npm.io/package/easy-transform-stream.md) ^1.0.1

## Recent versions

- 1.1.0 (latest) — 2024-10-14
- 1.0.0 — 2024-05-02
- 0.3.0 — 2023-11-03
- 0.2.2 — 2023-11-01
- 0.2.1 — 2023-10-31
- 0.2.0 — 2023-10-31
- 0.1.0 — 2023-10-31

## README

# gulp-plugin-extras

> Useful utilities for creating [Gulp](https://github.com/gulpjs/gulp) plugins

## Install

```sh
npm install gulp-plugin-extras
```

## Usage

```js
import {gulpPlugin, PluginError} from 'gulp-plugin-extras';

const pluginName = 'gulp-foo';

export default function gulpFoo(requiredArgument) {
	if (!requiredArgument) {
		throw new PluginError(pluginName, 'Missing argument `requiredArgument`');
	}

	return gulpPlugin(pluginName, async file => {
		file.contents = await someKindOfTransformation(file.contents);
		return file;
	});
}
```

## API

### `gulpPlugin(name, onFile, options?)`

Create a Gulp plugin.

If you throw an error with a `.isPresentable = true` property, it will not display the error stack.

*This does not support streaming unless you enable the `supportsAnyType` option.*

#### name

Type: `string`

The plugin name.

#### onFile

Type: `(file) => file`

The function called for each [Vinyl file](https://github.com/gulpjs/vinyl) in the stream. Must return a modified or new Vinyl file. May be async.

#### options

Type: `object`

##### supportsDirectories

Type: `boolean`\
Default: `false`

Whether the plugin can handle directories.

##### supportsAnyType

Type: `boolean`\
Default: `false`

Whether the plugin can handle any Vinyl file type.

Useful for custom type filtering.

Supersedes `supportsDirectories`.

##### onFinish

Type: `async function * (stream: NodeJS.ReadableStream): AsyncGenerator<File, never, void>`

An async generator function executed for finalization after all files have been processed.

You can yield more files from it if needed.

```js
import {gulpPlugin} from 'gulp-plugin-extras';

export default function gulpFoo() {
	return gulpPlugin(
		'gulp-foo',
		async file => { … },
		{
			async * onFinish() {
				yield someVinylFile;
				yield someVinylFile2;
			}
		}
	);
}
```

### `PluginError`

Create a Gulp plugin error. See the [types](index.d.ts) for docs.

---
_Source: https://npm.io/package/gulp-plugin-extras · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._