# Upgrade npm Dependencies Weekly for a Lit Component Library

Yes. Each week the agent bumps a Lit library's toolchain by group, runs lint, the browser tests and the docs build, and opens one PR listing what it held back.

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

## What the agent does

A web component package has one runtime dependency and a long tail of tools, and the tools are where upgrades go wrong. In a Lit library like lit/lit-element-starter-ts, `package.json` depends on `lit` `^3.2.0` and then on twenty-one development packages: `typescript` pinned with `~5.9.0`, `eslint` `^8.15.0` with `@typescript-eslint` at `^5.25.0`, `@web/test-runner` `^0.15.0` with its Playwright launcher, `@web/dev-server` and `@web/dev-server-legacy`, `@11ty/eleventy` `^1.0.1` for the docs site, `rollup` 4 with its plugins, `prettier` `^2.6.2`, `rimraf` `^3.0.2`, `lit-analyzer` and the custom elements manifest analyzer. No lock file is committed, there is no `engines` field and no `.nvmrc`, so the ranges are the only record of what the project runs on. The agent reads the manifest, `.eslintrc.json`, `tsconfig.json`, `web-test-runner.config.js`, `rollup.config.js`, `.eleventy.cjs` and `.prettierrc.json` before it changes a version.

It records a baseline first: `npm install`, then `npm ls --depth=0` for the versions the ranges resolve to today, `npm run build`, `npm run lint`, `npm test` after installing Playwright's browsers, which runs the suite in Chromium, Firefox and WebKit in dev and prod mode, `npm run docs`, and `npm run checksize` for the gzipped bundle size. Then it groups the bumps by what has to move together and commits each group separately. In-range updates and `lit` itself are the first group. Rollup's plugins are another. The test runner, its Playwright launcher and both dev-server packages move as one, because the current major of each asks for the same newer Node.

The interesting groups are the ones where a bump is not just a number. Moving `@typescript-eslint` to its current major while staying on ESLint 8 is allowed by its peer range, but that major removed the `ban-types` rule that `.eslintrc.json` switches off by name, so the agent deletes that line or ESLint stops with a missing rule definition. ESLint's later majors default to flat config and the newest does not read `.eslintrc.json` at all, so that bump is held unless the same commit replaces `.eslintrc.json` and `.eslintignore` with an `eslint.config.js`. The plugin's peer range also caps TypeScript below the newest major, so TypeScript moves only as far as that range allows and the pull request says which package is holding it. `rimraf` is a quiet one: since version 4 its command line no longer expands glob patterns unless given `--glob`, and the `clean` script passes brace patterns such as `my-element.{d.ts,d.ts.map,js,js.map}`, so after the bump the script can succeed while deleting nothing. The agent adds the flag and proves it by building, cleaning and listing the directory.

After each group it reruns the whole baseline and compares. `prettier --check` shows whether the new formatter major wants to rewrite files; this repository sets `trailingComma` explicitly, so the changed default should not apply, and the check confirms it. The docs build is compared with `git diff --stat docs`, since the generated site is committed. A group whose tests or build fail is reverted and named in the report with the failing output. The last step states the Node version the upgraded toolchain needs, read from each package's `engines`, and suggests recording it in `package.json`.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Upgrade the npm dependencies of this Lit component library. Read package.json, .eslintrc.json, .eslintignore, tsconfig.json, web-test-runner.config.js, web-dev-server.config.js, rollup.config.js, .eleventy.cjs and .prettierrc.json first. Record a baseline: npm install, npm ls --depth=0, npm run build, npm run lint, npx playwright install --with-deps, npm test, npm run docs, npm run checksize. Then upgrade in groups, one commit each: in-range updates and lit; rollup and its plugins; @web/test-runner, @web/test-runner-playwright, @web/dev-server and @web/dev-server-legacy together; @typescript-eslint, removing any rule the new major deleted from .eslintrc.json; typescript only as far as the lint plugin's peer range allows; prettier; rimraf, checking that the clean script still deletes its brace patterns and adding --glob if it does not; eleventy and its plugin. Keep eslint on its current major unless you also write a flat config in the same commit, and say which you did. After each group rerun the baseline; revert a group that fails and quote the failure. Compare the docs output with git diff --stat docs and run prettier --check. Report the Node version the new toolchain requires from each package's engines field. Open one pull request with a table of package, old range, new range and commit, and a list of everything held back with the reason.",
  "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

One pull request, one commit per group, each changing `package.json` and whatever that group needed: a line removed from `.eslintrc.json`, `--glob` added to the `clean` script, a config key a new test runner major renamed. The description starts with the table of package, old range, new range and commit. Under it are the baseline and final results side by side: the versions `npm ls` resolved, lint, the test totals per browser and mode as the runner printed them, the docs diff summary and the gzipped bundle size. A held-back section lists each package that did not move and why, for example ESLint waiting on a flat config or TypeScript capped by a peer range.

A reviewer looks at three things. First, the Node requirement: if the new test runner needs a newer Node than the team's CI image has, that group is one commit to revert. Second, the docs diff, because a static site generator that jumps two majors can change markup without failing. Third, the `clean` proof, which is a directory listing before and after and is easy to verify by eye. Nothing is published to npm by this run; it changes development tooling and the one runtime range.

## Run it on every Monday morning

Save the prompt as an automation in the Project that holds the library, with a `schedule` trigger: `cron` `0 7 * * 1` and your `timezone`. The first run is the large one. Later runs mostly find in-range updates, and because no lock file is committed they also catch the week a transitive release breaks the build, which nobody would otherwise see until the next fresh install.

If the result should reach a chat channel or a dashboard, start the weekly run from your own scheduler with an API key that has a webhook URL. `run.completed` arrives with the `session_url`, and reading that session gives the pull request link and the final answer, which is the held-back list.

## Why run it on Rush?

The tooling around a component library ages in a way that is invisible until someone clones it fresh: a test runner that predates its 1.0 release, a linter whose config format is being retired, a clean script that silently stopped cleaning. Each fix is small and each needs the full loop of install, build, lint, three browsers, docs. In a Rush sandbox the agent runs that loop after every group, with Playwright's browsers installed there and not on a laptop, and the output of every command is kept with the run.

The value is in the grouping and the honesty about limits. Peer ranges decide what can move, and the pull request names the package that blocks each held-back bump, so the next run or the next person knows what to wait for. Design systems split across several packages get one run per repository, started together, each producing its own reviewable branch.

## Frequently asked questions

### Will it upgrade ESLint to the latest major?

Only together with a flat config. The newest ESLint major does not read `.eslintrc.json`, so bumping the version alone breaks `npm run lint`. The agent either writes `eslint.config.js` in the same commit or keeps ESLint where it is and says so, depending on what the prompt asks.

### Why is TypeScript not moved to the newest version?

Because the lint plugin declares which TypeScript versions it supports in its peer dependencies, and installing outside that range gives warnings at best and parser errors at worst. The agent moves TypeScript to the newest version inside the range and reports the cap.

### Does it run the tests in real browsers?

Yes. The repository's test runner config launches Chromium, Firefox and WebKit through Playwright, and the agent installs those browsers in its sandbox before `npm test`. Results are reported per browser, in both dev and prod mode, as the scripts define them.

### Should we commit a lock file?

That is the team's call, and the run does not add one unasked. Without it, the weekly run doubles as an early warning for breaking transitive releases; with it, upgrades become explicit diffs. Ask in the prompt and the agent commits `package-lock.json` as a final, separate commit.

## More Lit jobs

- [Add Accessibility Tests to a Lit Component](https://getrush.ai/run/add-accessibility-tests/lit/)
- [Add a Bundle Size Check to a Lit Component](https://getrush.ai/run/add-bundle-size-check/lit/)
- [Add Test Coverage to CI for a Lit Web Component](https://getrush.ai/run/add-coverage-to-ci/lit/)

## The same job on other stacks

- [Upgrade npm Dependencies in a Next.js App](https://getrush.ai/run/upgrade-npm-dependencies/nextjs/)
- [Upgrade npm Dependencies in an Obsidian Plugin](https://getrush.ai/run/upgrade-npm-dependencies/obsidian-plugin/)
- [Upgrade the npm Dependencies of a Pulumi Program](https://getrush.ai/run/upgrade-npm-dependencies/pulumi/)

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