# Upgrade an Eleventy Site's npm Dependencies Every Week

Yes. Once a week an agent bumps your Eleventy site's npm packages, rebuilds the site, diffs the HTML and feed it produced, and opens a PR with that evidence.

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

## What the agent does

The agent starts with what the site is built from. In a blog like 11ty/eleventy-base-blog, `package.json` has `"type": "module"`, `engines.node` of `>=18`, an `.nvmrc` of `22`, a `package-lock.json` at lockfile version 3, and no `test` script at all: `build` is `npx @11ty/eleventy`, `start` adds `--serve --quiet`, and `build-ghpages` passes `--pathprefix=/eleventy-base-blog/`. Everything is a devDependency except `@zachleat/heading-anchors`: `@11ty/eleventy` `^3.1.7`, `@11ty/eleventy-img` `^7.0.0`, `@11ty/eleventy-navigation` `^1.0.5`, `@11ty/eleventy-plugin-rss` `^3.0.0`, `@11ty/eleventy-plugin-syntaxhighlight` `^5.0.2`, `cross-env` `^10.1.0`, `luxon` `^3.7.2`, `prismjs` `^1.30.0` and `zod` `^4.4.3`. There is a `.github/dependabot.yml` for npm on a monthly schedule with a seven-day cooldown and `versioning-strategy: increase`, but the only workflow is `gh-pages.yml.sample`, so nothing builds the site on a pull request today.

It then reads how each package is used, because that decides which bumps are safe to take blind and which need a look. `eleventy.config.js` imports `IdAttributePlugin`, `InputPathToUrlTransformPlugin` and `HtmlBasePlugin` from Eleventy itself, `feedPlugin` from the RSS plugin with `type: "atom"` and `outputPath: "/feed/feed.xml"`, `eleventyImageTransformPlugin` with `formats: ["avif", "webp", "auto"]`, and registers two bundles with `addBundle` plus a `drafts` preprocessor. `_data/eleventyDataSchema.js` calls `z.object`, `z.optional`, `safeParse` and `z.prettifyError`, an API that exists only from Zod 4. `_config/filters.js` uses `DateTime.fromJSDate` and `toFormat` from Luxon. And `_includes/layouts/base.njk` inlines `node_modules/@zachleat/heading-anchors/heading-anchors.js` by path inside a `<script type="module">`, so a release of that package that renames the file breaks the build rather than the page.

With that map, the agent runs `npm ci` on Node 22, then `npm outdated` to see what moved. Minor and patch updates inside the existing caret ranges go in first with `npm update`, which rewrites only `package-lock.json`. Each major it finds is taken on its own: it reads that package's changelog, bumps the range in `package.json`, installs, and rebuilds. For Eleventy and its plugins it watches the plugin options named above; for `luxon` it checks the two filters still format `dd LLLL yyyy` and `yyyy-LL-dd`; for `zod` it checks `z.prettifyError` is still exported; for `prismjs` it checks the syntax highlight plugin's peer range. A major it cannot make build is left out and named in the description with the error it produced.

The proof is the build. Before touching anything the agent runs `npm run build` and keeps the `_site` folder; after the upgrade it builds again and diffs the two trees: the list of HTML files, `feed/feed.xml`, `sitemap.xml`, and the `avif` and `webp` files the image plugin wrote for `content/blog/fourthpost/possum.png`. A diff that is only the `currentBuildDate` comment at the foot of each page is the expected result; anything else, such as a changed heading id from `IdAttributePlugin` or a feed entry that lost its `<updated>`, is reported line by line. It finishes with `npm audit` and `npm ls` to show no advisory and no unmet peer dependency.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Upgrade this Eleventy site's npm dependencies. Read package.json, package-lock.json, .nvmrc, eleventy.config.js, _config/filters.js, _data/eleventyDataSchema.js and _includes/layouts/base.njk first, and note that base.njk inlines a file from node_modules by path. Run npm ci and npm run build on the Node version in .nvmrc and keep the _site output as a baseline. Apply minor and patch updates with npm update, then take each major version separately, reading its changelog and checking the plugin options, filters and schema calls this site uses. Rebuild after each step and diff _site against the baseline, ignoring only the build date comment; report every other difference. Leave out any major that does not build and say why. Finish with npm audit and npm ls. If no workflow builds the site on pull requests, add one in a separate commit. Open a pull request whose description lists each package with its old and new version and the build diff.",
  "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

What comes back is a pull request on its own branch that changes `package.json` and `package-lock.json` and, when a major needed it, one source file such as `eleventy.config.js` or `_data/eleventyDataSchema.js` with the smallest edit that keeps the site building. Patch and minor bumps sit in one commit; each major is its own commit with the changelog link in its message, so a reviewer can drop one without losing the rest.

The description is a table of packages with the version before and after, the `npm outdated` output the run started from, the `_site` diff summary (files added, removed or changed, with the build-date comment filtered out), the `npm audit` line and any major the agent left behind with the error it hit. The transcript at `GET /o/{org}/sessions/{id}/messages` keeps every `npm` and `eleventy` command with its full output.

Before merging, a reviewer reads the diff summary rather than the lockfile: an unchanged page set and an unchanged `feed/feed.xml` mean the upgrade is invisible to readers. If an image or heading id changed, the description names the file and the reviewer opens the built page to decide. Because this site has no pull-request workflow, the reviewer can also take the agent's suggested `build.yml`, offered as a separate commit, so the next weekly run is checked by GitHub too.

## Run it on every Monday morning

Create an automation in the Project that holds the site with a `schedule` trigger, a `cron` such as `0 7 * * 1` in your `timezone`, and this prompt. Every Monday one run installs, upgrades, rebuilds and diffs, and opens one pull request; a week with nothing outdated opens none and says so in its result. An automation run has its own `max_runs_per_hour` cap.

To start it from your own scheduler instead, send `POST /o/{org}/sessions` with this body and the repository in `resources`, and include a `request_id` that is a UUID v5 of the repository name and the ISO week, so a retried call returns the run already started rather than opening a second pull request.

## Why run it on Rush?

An Eleventy site has no test suite to tell you an upgrade was safe; the only evidence is the built output, and comparing two `_site` trees by hand is the step nobody does. The agent does it every time, in a sandbox with the exact Node from `.nvmrc`, and keeps the before-and-after build logs with the pull request.

The majors are the part that costs attention: a plugin option renamed, a Zod helper moved, a file path under `node_modules` that a layout inlines. Reading each changelog against the files that call the package is slow on a laptop and routine for an agent, and doing it weekly keeps each pull request to a few lines instead of a quarterly rewrite. Many sites can run at once, each in its own sandbox with its own pull request.

## Frequently asked questions

### How does it know the upgrade did not change the site, with no tests?

It builds before and after and diffs the two `_site` trees: the HTML files, `feed/feed.xml`, `sitemap.xml` and the images the image plugin generates. The only expected difference is the `currentBuildDate` comment at the end of each page, which it filters out; everything else is listed in the pull request for a reviewer to judge.

### There is already a dependabot.yml. Why run this too?

Dependabot opens one pull request per package on its monthly schedule and never builds the site, so a plugin major and the config change it needs arrive as a red pull request with no fix. The agent takes all the updates together, makes the config edit a major needs, and shows the build. Keeping `dependabot.yml` for security advisories alongside it is fine.

### What happens with a major that breaks the build?

It tries the fix the changelog describes, such as a renamed plugin option in `eleventy.config.js`. If the build still fails, it reverts that one package to its previous range, keeps everything else, and names the package and the error in the description so you can decide whether to take it by hand.

### Does it touch the heading-anchors script inlined in base.njk?

Only if the package's new release moves or renames `heading-anchors.js`, which the build would catch because the `include` would fail. In that case the agent updates the path in `_includes/layouts/base.njk` in the same commit as the bump and points to it in the description.

## More Eleventy jobs

- [Write Playwright Tests for an Eleventy Blog](https://getrush.ai/run/write-playwright-tests/eleventy/)
- [Add a Dark Mode Toggle to an Eleventy Site](https://getrush.ai/run/add-dark-mode/eleventy/)
- [Add a GitHub Pages Deploy Workflow to an Eleventy Site](https://getrush.ai/run/add-deploy-workflow/eleventy/)

## The same job on other stacks

- [Upgrade npm Dependencies in a Fastify API](https://getrush.ai/run/upgrade-npm-dependencies/fastify/)
- [Upgrade npm Dependencies in a Hono API](https://getrush.ai/run/upgrade-npm-dependencies/hono/)
- [Upgrade npm Dependencies Weekly for a Lit Component Library](https://getrush.ai/run/upgrade-npm-dependencies/lit/)

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