All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

More jobs like this: Hand off a long task

Keep reading