# Replace Grunt With npm Scripts in a Node.js App

Yes. An agent reads your Gruntfile, moves each task that still matters to an npm script with the tool it wrapped, drops the grunt packages, and opens a PR.

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

## What the agent does

The agent reads the Gruntfile and what calls it. In an app like OWASP/NodeGoat, `Gruntfile.js` registers `precommit` (`jsbeautifier` then `jshint`), `test` (`env:test` then `mochaTest:unit` over `test/unit/*.js`), `testsecurity` (which installs `chromedriver` at run time through `grunt-npm-install` and runs `mochaTest:security`), `db-reset` (a shell-out to `node artifacts/db-reset.js` with `NODE_ENV`), `run` and `default` (`precommit` then `concurrent` with `nodemon` and `watch`, with livereload), plus a `retire` config. Two lines matter for how honest those tasks are: `grunt.option("force", true)` makes every task succeed even when it fails, and `test/unit/` does not exist, since `test/` holds only `e2e/` (Cypress) and `security/` (Selenium against ZAP), so `npm test` has been passing with zero tests. `package.json` maps `test` to `grunt test`, `precommit` to `grunt precommit` and `db:seed` to `grunt db-reset`, and declares eleven `grunt*` devDependencies, one of them `grunt-if` as a tarball URL, while the `grunt-nodemon` the Gruntfile loads is not declared at all.

It then reads around the Gruntfile. `.github/workflows/lint.yml` already bypasses Grunt and runs `npx --no-install jshint@2.12.0 .` on Node 14; `e2e-test.yml` runs the Cypress suite on Node 10, 12 and 14 against a Mongo container; `.travis.yml` is a leftover. `.jshintrc` and `.jshintignore` configure the linter, `nodemon.json` the dev server, and `cypress.json` blacklists `*:35729`, the livereload port that `config/env/development.js` injects into every page through `environmentalScripts`. `Dockerfile` builds on `node:12-alpine`, so whatever replaces the grunt packages has to install on Node 12.

The agent rewrites `scripts` so each task names the tool Grunt was wrapping: `lint` runs `jshint .`, `format` runs `js-beautify --replace` over the same globs the Gruntfile listed, with the Gruntfile's beautifier options moved to a `.jsbeautifyrc`, `precommit` runs `format` then `lint`, `test:unit` runs `cross-env NODE_ENV=test mocha "test/unit/**/*.js"`, `test:security` runs the same over `test/security`, `db:seed` becomes `cross-env NODE_ENV=test node artifacts/db-reset.js` with no Grunt in between, `audit:retire` runs `retire --path . --package`, and `dev` stays `nodemon`. Because there is no unit test directory, it makes `test` run `lint` and says so in the pull request rather than keep a command that passes on nothing; with force mode gone, a jshint error now fails `npm test`. It adds `js-beautify`, `retire` and `chromedriver` as devDependencies at versions that install on Node 12, removes the eleven grunt packages and `Gruntfile.js`, drops the livereload script injection from `development.js` since nothing serves it any more, and points `lint.yml` at `npm ci` and `npm run lint` so CI and the local script run the same thing.

Each replaced task is run in the sandbox before the pull request: `npm ci` on Node 12 to confirm the new devDependencies resolve, `npm run lint` with its exit code compared against `npx jshint .` on the original tree so the migration neither hides nor invents findings, `npm run format` on a copy to confirm the beautifier settings produce no diff against the formatted tree, `npm run db:seed` against a local MongoDB to confirm the reset script still runs with the environment it expects, and `npm run audit:retire` to read what retire reports today. `test:security` needs a running ZAP proxy and is not run; the pull request says so.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Replace Grunt with npm scripts in this Node.js app. Read Gruntfile.js, package.json, .jshintrc, .jshintignore, nodemon.json, cypress.json, config/env/*.js, Dockerfile, .travis.yml and every workflow under .github/workflows first, and list what each registered Grunt task actually runs, noting force mode and any task whose target files do not exist. Rewrite the scripts so each task calls the tool Grunt wrapped directly: jshint for lint, js-beautify with the Gruntfile's options moved to .jsbeautifyrc for format, mocha with cross-env for the unit and security suites, node artifacts/db-reset.js for the seed, retire for the dependency check, and nodemon for dev. Make npm test honest about what exists and explain the choice in the pull request. Add the direct tools as devDependencies at versions that install on the Node version the Dockerfile uses, remove every grunt package and Gruntfile.js, remove the livereload injection that no longer has a server, and point the lint workflow at npm run lint. In the sandbox run npm ci, the lint script with its exit code compared against the original jshint run, the format script against a copy, the seed script against a local MongoDB and the retire script, and open a pull request with the task-by-task mapping and that output.",
  "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

The pull request removes `Gruntfile.js` and the grunt devDependencies, rewrites the `scripts` block in `package.json` with the matching `package-lock.json` change, adds `.jsbeautifyrc`, edits `config/env/development.js` to drop the livereload script tag, and changes `.github/workflows/lint.yml` to install and run `npm run lint`. Application code under `app/` and `server.js`, the Cypress suite and `e2e-test.yml` are untouched.

The description is a table: each Grunt task, the npm script that replaces it, the tool it calls, and whether it was run in the sandbox, followed by the jshint exit codes before and after, the retire output, and the note that `test/unit/` does not exist and `npm test` now runs the linter. The full commands and their output are in the session transcript at `GET /o/{org}/sessions/{id}/messages`.

Before merging, a reviewer reads the mapping table for a task the team still relies on, confirms the Node 12 install in the Dockerfile still succeeds with the new devDependencies, and decides whether `npm test` should stay on lint or point at the Cypress suite. A follow-up message to the same session can add a first unit test under `test/unit/` and switch `test` to the mocha script.

## Run it on every terminal hand-off

A developer tired of a build tool nobody on the team remembers starts this from the terminal with this body and goes back to the feature branch. The run reads the real Gruntfile and the real workflows, so the mapping it writes covers the tasks this project has, including the ones that were quietly doing nothing.

Send a `request_id`, a UUID, with the body so a retried start returns the run it already began. The pull request is on the run's `GET /o/{org}/sessions/{id}` answer once it is open.

## Why run it on Rush?

A Grunt removal is only safe if every replaced task is run and compared, and that means an old Node version, a MongoDB for the seed script and a careful read of options spread over a 194-line Gruntfile. The agent does that in its own sandbox, with Node 12 for the install check and a local database for the seed, and records each exit code next to the original so the review is a comparison rather than a leap of faith.

Every command it ran is kept with its output in the session record, including the jshint run on the untouched tree that proves the new lint script reports the same findings. A team with several legacy services can send the same request for each at once and get one pull request per repository, each with that repository's own task table.

## Frequently asked questions

### Why does npm test run the linter now?

Because the Grunt `test` task ran mocha over `test/unit/*.js`, a directory that does not exist, under force mode, so it always passed. The agent would rather make `npm test` run a check that exists and say so than keep a green command that tests nothing. `test:unit` is there for the day a unit test is written, and the pull request asks whether the Cypress suite should take over `test` instead.

### Will the formatting of existing files change?

Not from the migration itself. The Gruntfile's `jsbeautifier` options are copied into `.jsbeautifyrc`, and the agent runs the new `format` script on a copy of the tree to confirm it produces no diff before the pull request. If it does produce one, that diff is reported separately rather than folded into the migration.

### What about the security tests and ZAP?

`test:security` runs mocha over `test/security/`, which drives Chrome through Selenium against a ZAP proxy on the host named in `config/env/test.js`. The sandbox has no ZAP, so that script is written but not run, and the pull request says so. `chromedriver` becomes a declared devDependency instead of a package Grunt installed at run time.

### Does this change the Dockerfile or the Cypress CI?

No. The Dockerfile installs with `--production`, so devDependencies never reached the image, and `e2e-test.yml` runs Cypress through `npm run test:ci`, which never used Grunt. Only `lint.yml` changes, from a bare `npx jshint` call to the same `npm run lint` a developer runs.

## More Node.js jobs

- [Run a Security Audit on a Node.js App](https://getrush.ai/run/security-audit/nodejs/)
- [Update the GitHub Actions in a Node.js Repository's Workflows](https://getrush.ai/run/update-github-actions/nodejs/)
- [Upgrade an Express 4 App to Express 5 in Node.js](https://getrush.ai/run/upgrade-express-5/nodejs/)

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

- [Replace Gulp With npm Scripts and a Plain Node Build Script](https://getrush.ai/run/migrate-gulp-to-npm-scripts/gulp/)
- [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/)

## 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/)
