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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
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 (Joda-Time)
- Migrate a Maven Project From JUnit 4 to JUnit 5 (JUnit)
- Migrate dgrijalva/jwt-go to golang-jwt in a Go Auth Service (jwt-go)
- Replace lazy_static With std::sync::LazyLock in a Rust Project (lazy_static)
- Migrate a chi API from Logrus to log/slog (chi)
- Migrate a Sphinx Project From m2r to m2r2 (m2r)