assemble-handle

1.0.0 verified Sat Apr 25 auth: no javascript

Assemble pipeline plugin for handling custom middleware stages in the Assemble build system. Version 1.0.0 is the latest stable release, updated on npm with monthly downloads. It allows you to create and manage middleware stages like 'onStream', 'preWrite', and 'postWrite', and handle them on files via .pipe(). The package also provides a .once() method to prevent middleware from running multiple times for the same stage. Key differentiator: tightly integrated with Assemble, not a general-purpose middleware runner.

Common errors

error TypeError: app.handler is not a function ↓

cause Missing assemble-core dependency or incorrect import.

fix

Ensure you npm install assemble-core and require it before assemble-handle.

error Error: Middleware stage "onStream" is not defined ↓

cause Forgot to call app.handler('onStream') before using handle.

fix

Add app.handler('onStream') before calling handle(app, 'onStream').

error ReferenceError: handle is not defined ↓

cause Package not required properly.

fix

Add const handle = require('assemble-handle'); at top of file.

Warnings

gotcha The handle function must be called with app as first argument; order matters. ↓

fix Use handle(app, 'stageName'), not handle('stageName', app).

gotcha handle.once only prevents multiple calls within the same file stream; not global deduplication. ↓

fix Understand that .once() resets per stream; use other dedup patterns if needed.

gotcha Handlers must be created with app.handler() before being used. ↓

fix Always call app.handler('stageName') before accessing app.onStage or using handle.

deprecated Assemble ecosystem is largely superseded by other build tools; not actively maintained. ↓

fix Consider migrating to Gulp or other modern pipelines.

Install

npm install assemble-handle

yarn add assemble-handle

pnpm add assemble-handle

Imports

default

wrong

import handle from 'assemble-handle'

correct

const handle = require('assemble-handle')

CommonJS module; no default ESM export. Use require.

handle.once

wrong

handle.once('stageName', app)

correct

handle.once(app, 'stageName')

Arguments order: (app, stage).

handle

wrong

handle('stageName', app)

correct

const handle = require('assemble-handle'); handle(app, 'stageName')

Must pass app as first argument.

Quickstart

Demonstrates creating handlers, adding middleware, and using handle in a pipeline task.

const assemble = require('assemble-core');
const handle = require('assemble-handle');
const app = assemble();

// Create middleware stages
app.handler('onStream');
app.handler('preWrite');

// Add middleware
app.onStream(/.*/, function(file, next) {
  console.log('onStream:', file.relative);
  next();
});
app.preWrite(/.*/, function(file, next) {
  console.log('preWrite:', file.relative);
  next();
});

// Task using handle
app.task('default', function() {
  return app.src('*.js')
    .pipe(handle(app, 'onStream'))
    .pipe(handle(app, 'preWrite'))
    .pipe(app.dest('dist'));
});

app.build('default');