# Replace Gulp With npm Scripts and a Plain Node Build Script

Yes. An agent rewrites the gulpfile as a small Node script behind npm scripts, proves the output is byte-identical, and opens a pull request without gulp.

[Run this on Rush](https://cloud.getrush.ai/run/migrate-gulp-to-npm-scripts/gulp/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the gulpfile as a specification: what goes in, what comes out, and which plugins do real work. In a project like h5bp/html5-boilerplate, `gulpfile.mjs` is 143 lines. `clean` deletes `dist` and `archive` with `del`. Four copy tasks fill `dist`: `index.html`, `LICENSE.txt`, everything else under `src` including dotfiles, and the stylesheet, which is `node_modules/main.css/dist/main.css` passed through `gulp-header`, `gulp-autoprefixer` and `gulp-rename` to become `css/style.css`. `lint:js` runs ESLint through `gulp-eslint-new`, and `archive` zips `dist` with `archiver`. `package.json` wires this up as `"build": "gulp build"` and `"test": "gulp archive && mocha --reporter spec --timeout 5000"`.

Before writing anything it captures what gulp produces, because the replacement is judged against that. It runs `npm test` (25 Mocha tests passing when this page was written), keeps a copy of `dist`, and lists the archive: 19 entries. It also measures what each plugin contributes. Comparing `style.css` with the source stylesheet shows that autoprefixer, at the installed 10.5.2, removes exactly one line of `main.css` 3.0.0, the `-webkit-min-device-pixel-ratio` media condition, and the only other difference is the banner. Two details in the gulpfile turn out to be inert: the copy task excludes `src/css/main.css`, a path that does not exist, and `archive:zip` calls `done()` right after `zip.finalize()` as well as on the stream's `close` event, so gulp reports the task finished before the file is closed.

The constraint that shapes the rewrite is in `.github/workflows/test.yml`: the matrix runs Node 22, 24 and 26 on both `ubuntu-latest` and `windows-latest`. Shell one-liners with `rm -rf` and `cp -r` in `package.json` would break half of it. So the agent writes one Node script of about 60 lines, `scripts/build.mjs`, using `fs.rmSync`, `fs.cpSync` with a filter for `.DS_Store`, `postcss` with `autoprefixer` called directly, and the same `archiver` and `glob` calls the gulpfile made, this time awaiting the output stream's `close`. The scripts become `npm run lint && node scripts/build.mjs` and the same with `archive` ahead of Mocha. The existing `lint` script, `eslint .`, covers the `.js` files the gulp task linted. The agent also checks that `eslint.config.mjs` applies its rules only to `**/*.js`, so the `test/*.mjs` files gulp passed to ESLint were getting no rules either way.

Then it proves equivalence and removes the old tool. `diff -r` between the gulp-built `dist` and the script-built one reports nothing, the new archive has the same 19 entries, and the 25 tests pass. Uninstalling `gulp`, `gulp-autoprefixer`, `gulp-eslint-new`, `gulp-header`, `gulp-rename` and `del` removes 186 packages; adding `postcss` and `autoprefixer` as direct dependencies adds 13, and the installed tree goes from 365 packages to 192.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Replace gulp in this repository with npm scripts and a single Node build script, with identical output. Read gulpfile.mjs, package.json, eslint.config.mjs, the files in test and every workflow under .github/workflows first, and write down each gulp task, its inputs, its outputs and the plugin that does the work. Before changing anything, run npm ci and npm test, keep a copy of the dist directory gulp builds and a listing of the archive it creates, and work out exactly what each plugin changes in the stylesheet. The CI matrix includes Windows, so do not put rm, cp or mkdir shell commands in package.json: write scripts/build.mjs with Node's fs API, postcss and autoprefixer called directly, and the archiver and glob packages already in devDependencies. Keep the build and test script names. Compare your dist with the saved one using diff -r, compare the archive listings, and run the tests. Then uninstall gulp and every gulp plugin, delete gulpfile.mjs, run npm ci and repeat the comparison from a clean install. Do not commit changes to dist that come from dependency versions rather than from your work; report them. Open a pull request with the output of every command and the before and after package counts.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

A pull request that adds `scripts/build.mjs`, deletes `gulpfile.mjs`, and changes `package.json` and `package-lock.json`. The description has a table of the gulp tasks and the lines of the new script that replace each one, the empty `diff -r`, the two archive listings side by side, the Mocha summary, and the package counts before and after. It lists the two inert details it found in the gulpfile and what the new script does about each.

A reviewer checks that the workflows still call what exists: `test.yml` runs `npm test`, `build-dist.yml` runs `npm run build` and opens a pull request when `dist` changes, and both script names are kept. They look at one thing the agent reports but leaves alone. After any build, gulp or not, `dist/package.json` differs from the committed copy by three version lines, because `src/package.json` has moved on since `dist` was last committed. That is the `build-dist.yml` workflow's job to pick up, and mixing it into this pull request would hide the claim that the output is unchanged.

## Run it on every repository with a gulpfile

Removing a task runner is a one-time job per repository. If you maintain several older front-end projects, list the ones that still have a `gulpfile` and send this body to `POST /o/{org}/sessions` once per repository, each with its own URL in `resources`. A `request_id` that is a UUID v5 of the repository name makes the batch safe to send twice.

The gulpfiles will differ, which is why the prompt asks for the task table first and the byte comparison last: those two steps hold for any of them. Runs past the key's `max_concurrent` limit wait as `queued` and start as earlier ones finish, and a `webhook_url` on the key receives each result when its turn ends.

## Why run it on Rush?

"Identical output" is a claim about bytes, and proving it takes two full builds from clean installs and a recursive diff. The agent has a sandbox in which to do exactly that: install the locked dependencies, build with gulp, save the result, rewrite, build again, compare, uninstall, reinstall from scratch and compare once more. Every command and its output is kept with the run, so the empty diff in the description is one a reviewer can trace to the command that printed it.

Measuring first also keeps the rewrite small. Knowing that autoprefixer changes one line, that an exclude matches nothing and that the lint task adds nothing over `npm run lint` is what lets 143 lines of tasks and six packages become one short script and two direct dependencies. A person porting the gulpfile line by line on a laptop would carry the dead parts across.

## Frequently asked questions

### Why a Node script and not shell commands in package.json?

Because of Windows. This project's CI runs on `windows-latest` as well as Ubuntu, where `rm -rf` and `cp -r` are not available in the default shell npm uses. Node's `fs.rmSync` and `fs.cpSync` behave the same on both, and need no extra packages such as rimraf or cpy.

### Do I still need autoprefixer without gulp-autoprefixer?

Only if it changes your CSS, and the agent checks. Here it removes a single vendor-prefixed media condition, so keeping it preserves byte-identical output. It runs through `postcss` directly, with the same `cascade: false` option the gulpfile passed.

### How do I know the new build produces the same files?

The agent builds with gulp, saves `dist`, builds with the new script and runs `diff -r` on the two directories. It also compares the list of entries in the zip archive, and runs the project's own tests, which check the expected files and the stylesheet banner. All three results are in the pull request.

### What happens to gulp's parallel and series ordering?

It becomes ordinary sequential code. The gulpfile ran `clean` and `lint:js` in parallel and the copy tasks in series; the script lints, cleans, copies, then archives, awaiting each step. The build is a handful of file copies, and its order is now readable from top to bottom.

## More Gulp jobs

- [Fix "AssertionError: Task function must be specified" After Upgrading to gulp 4](https://getrush.ai/run/fix-gulp-task-function-must-be-specified/gulp/)
- [Fix "npm warn deprecated gulp-util: gulp-util is deprecated" in a Gulp Build](https://getrush.ai/run/fix-gulp-util-is-deprecated-warning/gulp/)
- [Fix "ReferenceError: primordials is not defined" by Upgrading gulp 3](https://getrush.ai/run/fix-primordials-is-not-defined/gulp/)

## More jobs like this: Hand off a long task

- [Migrate a Jenkins Pipeline to GitHub Actions for a Maven Project](https://getrush.ai/run/migrate-jenkins-to-github-actions/maven/)
- [Migrate a Chrome Extension from Jest to Vitest](https://getrush.ai/run/migrate-jest-to-vitest/chrome-extension/)
- [Migrate Jest to Vitest in an Electron App](https://getrush.ai/run/migrate-jest-to-vitest/electron/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
