# Migrate an Express App From Jade to Pug

Yes. An agent renames the templates, swaps jade for pug, renders every view with both engines to compare the HTML, and opens a pull request.

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

## What the agent does

`npm install` on an app that depends on `jade` prints the notice that sends people here: "Jade has been renamed to pug, please install the latest version of pug instead of jade". The agent starts with what the app has. In an Express app like tutsplus/passport-mongo, `package.json` pins `jade` at `~1.11.0`, `app.js` sets `app.set('view engine', 'jade')`, and `views/` holds five templates: `layout.jade`, `index.jade`, `register.jade`, `home.jade` and `error.jade`. `routes/index.js` renders three of them by name with `res.render`, and the error handler in `app.js` renders the fourth.

Three things change together, and a partial change fails in a specific way. The dependency becomes `pug`, the view engine setting becomes `'pug'`, and every template is renamed with `git mv` so history follows the file. The rename is not cosmetic. Four of the five views begin with `extends layout`, and Pug resolves that to `layout.pug`. Point Pug at an unrenamed `index.jade` and it stops with `ENOENT: no such file or directory` for `views/layout.pug`. The `res.render('index')` calls need no edit because they name no extension.

Then the agent looks for syntax that Jade 1.x accepted and Pug rejects or reads differently, and it tests each form instead of trusting a list. Pug no longer interpolates inside attribute values, so `a(href='/u/#{id}')` renders the characters `#{id}` literally where Jade rendered the value. A mixin called with the `mixin` keyword fails with `Mixin item declared without body`, and `- each` fails with a message that `each` should no longer be prefixed with a dash. The passport-mongo templates use none of these: every `#{...}` sits in text, such as `#{user.firstName}` in `home.jade`, and there are no mixins or loops. The agent reports that finding with the search it ran, so the reviewer knows the absence was checked.

The proof is a render of every view through both engines with the same data. This app connects to MongoDB at startup, `mongoose.connect(dbConfig.url)` in `app.js`, so the agent does not need the server running: it writes a short script that calls `renderFile` from `jade` and from `pug` on each template with sample `message`, `user` and `error` values and compares the output. Of the four views the app renders, `error` comes out byte for byte the same. The other three differ in one way only: Jade 1.11 moves `class` to the end of each tag's attributes and Pug keeps the order written in the template, so `<form action="/login" method="POST" class="form-signin">` becomes `<form class="form-signin" action="/login" method="POST">`. The agent then removes `jade` from the manifest and runs `npm audit` before and after.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Migrate this Express app from the jade package to pug. Read package.json, the file that sets the view engine, and every template under the views directory. Rename each .jade file to .pug with git mv, including layouts, includes and mixin files, and update the view engine setting and any render call or include that names the .jade extension. Before editing templates, search them for syntax Pug handles differently from Jade 1.x: interpolation inside attribute values, mixins called with the mixin keyword instead of a plus sign, each or for prefixed with a dash, the old doctype shorthand, and files that mix tabs and spaces. Confirm each difference with a two-line test against both packages and quote the output. Fix every occurrence and list them by file and line; if there are none, say which searches found nothing. Write a script that renders every view with both engines using the same sample locals, taken from what the routes pass to res.render, and compares the HTML. Report each view as identical or show the first difference, and say whether the difference changes what a browser displays. Do not start the server if it needs a database; render the templates directly. Replace jade with the current pug release in package.json, update the lock file if one is committed, and run npm audit before and after, reporting the advisories that left with jade. Leave unrelated dependencies alone. Open a pull request.",
  "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 with five renames, a one-word change in `app.js` and a one-line change in `package.json`. Git shows the templates as renames with no content change, which is the point: for an app whose templates use only tags, classes and text interpolation, the migration is a rename. The description carries the comparison table, one row per view, and for the views that differ it shows one tag before and after so the attribute reordering is visible and can be judged harmless.

It also carries the audit result. A fresh install of `jade` 1.11.0 brings `constantinople` 3.0.2, `clean-css` 3.4.28, `transformers` and two copies of `uglify-js`, and `npm audit` reports five vulnerable packages, `jade` among them, three rated critical. A fresh install of `pug` 3 reports none. The reviewer checks that no test, scraper or cached page depends on the exact attribute order of the HTML, opens the pages once with a database running, and merges.

## Run it on every issue labelled jade-to-pug

Old Express apps scaffolded by the generator tend to sit in many repositories, each small and each with the same five-file `views/` directory. To work through them as people have time to review, create an automation in the Project that holds a repository, save this prompt in it, and give it a `github` trigger on `issues.labeled` with `labels` set to `jade-to-pug`. Labelling an issue then starts one run. The trigger adds the event after the saved prompt and fills in nothing, so the prompt must stand on its own, as this one does.

Only a label applied by an owner, member or collaborator of the repository fires the trigger; one applied by a bot does not. If you would sooner drive it from a list, skip the automation and send this body to `POST /o/{org}/sessions` once per repository, each with its own `resources` URL.

## Why run it on Rush?

The question a reviewer has about a template engine swap is whether the pages still come out the same, and that can only be answered by rendering them. The run installs both packages in its own sandbox, renders every view twice and diffs the result, and the script and its output stay in the session transcript. The claim in the pull request that three views differ only in attribute order is backed by the diff that showed it.

It also removes guesswork about syntax. Lists of Jade to Pug breaking changes are long and most entries do not apply to a given app. The agent tests the forms against the installed versions, searches the templates for each, and reports which exist in this codebase, so the review covers the app's real templates and not a generic checklist.

## Frequently asked questions

### Do I have to rename every .jade file?

Yes, in practice. Pug looks for `.pug` when a template says `extends layout` or `include header` without an extension, so a layout left as `layout.jade` is not found. Express also looks up `res.render('index')` using the view engine's extension. Renaming everything in one commit avoids both problems.

### Will my templates render exactly the same HTML?

The same elements and attributes, not always the same bytes. Jade 1.11 writes `class` after the other attributes; Pug writes attributes in the order the template lists them. A browser treats the two as equal, but a test that compares HTML strings will need its expected value updated.

### What breaks most often in a Jade to Pug migration?

Attribute interpolation. `a(href='/user/#{id}')` worked in Jade and in Pug renders the literal text `#{id}` with no error, so it is easy to miss. The fix is a JavaScript expression, `a(href='/user/' + id)` or a template literal. The agent searches for it specifically because nothing fails loudly.

### Do I need to change my res.render calls?

Not if they name the view without an extension, as `res.render('index', {...})` does. Only the `view engine` setting changes, from `'jade'` to `'pug'`. A call that spells out `'index.jade'` needs the new extension.

### Can the agent verify the pages without my database?

It verifies the templates, which is where this change can go wrong. It renders each view directly with sample data shaped like what the routes pass in. Checking a full sign-in flow needs the app's database, so that part is left to the reviewer or to a run that is given a test database.

## More jobs like this: Upgrade dependencies weekly

- [Migrate a Java Project From Joda-Time to java.time](https://getrush.ai/run/migrate-joda-time-to-java-time/joda-time/)
- [Migrate a Maven Project From JUnit 4 to JUnit 5](https://getrush.ai/run/migrate-junit-4-to-junit-5/junit/)
- [Migrate dgrijalva/jwt-go to golang-jwt in a Go Auth Service](https://getrush.ai/run/migrate-jwt-go-to-golang-jwt/jwt-go/)
- [Replace lazy_static With std::sync::LazyLock in a Rust Project](https://getrush.ai/run/migrate-lazy-static-to-lazylock/lazy-static/)
- [Migrate a chi API from Logrus to log/slog](https://getrush.ai/run/migrate-logrus-to-slog/chi/)
- [Migrate a Sphinx Project From m2r to m2r2](https://getrush.ai/run/migrate-m2r-to-m2r2/m2r/)

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