All jobs

Upgrade Pinia 2 to Pinia 4 in a Vue 3 App

Yes. An agent moves pinia, vue and @vue/devtools-api together, rewrites defineStore({ id }) calls, runs the build and the browser test and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads the lockfile first, because the ranges in package.json say little about what is installed. In a Vue 3 app like piniajs/example-vue-3-vite, package.json asks for pinia ^2.0.34 and vue ^3.2.47, and yarn.lock holds exactly those: Pinia 2.0.34 on Vue 3.2.47, built by Vite 8.0.0. The two stores, src/stores/cart.ts and src/stores/user.ts, are both written as defineStore({ id: 'cart', state, getters, actions }), with the id inside the options object, and each ends with an acceptHMRUpdate block. src/layouts/default.vue imports version from pinia/package.json to print it in the footer. The scripts are build, start (vite serve), test (cypress run) and type-check (vue-tsc --noEmit), and the only test is cypress/e2e/main.cy.js, which adds two items to the cart and clears it.

It runs everything once before touching a version, and the baseline already has a hole. yarn build passes and the Cypress test passes, but yarn type-check fails before any change: the locked vue-tsc 3.0.2 asks the locked TypeScript 7.0.2 for typescript/lib/tsc, a path that package does not export, and Node stops with ERR_PACKAGE_PATH_NOT_EXPORTED. The newest vue-tsc on npm when this page was written, 3.3.14, fails the same way. That matters for what follows, because the type checker is the tool that would have flagged a removed defineStore overload. The agent records it as a failure that exists on the default branch and does not count it as a check for this upgrade.

Then the upgrade, in the order the errors force. Pinia's changelog names two majors between the lock and latest: 3.0.0 removed defineStore({ id }) and Vue 2 support, and 4.0.0 made the package ESM only and moved @vue/devtools-api to a peer dependency that must be installed beside it. yarn add pinia@^4 alone warns about both peers, and yarn build then fails because hasInjectionContext is not exported by the locked Vue. Adding vue@^3.5.11 and @vue/devtools-api@^8.2.1, the ranges Pinia 4.1.0 declares, makes the build pass. This is the trap: the build is green and the app is broken. The stores still use the removed signature, and the first component that calls one throws Cannot destructure property 'state' of 'options' as it is undefined. Only running the app shows it, and the Cypress test fails on exactly that error.

The fix is two lines per store: defineStore('cart', { ... }) and defineStore('user', { ... }), with the id as the first argument and nothing else changed. The agent raises @vue/compiler-sfc, a separate dev dependency that yarn add vue leaves at 3.2.47, to the same version as vue. It rebuilds, starts the server the way .github/workflows/test.yml does, with yarn run build and yarn run start, and runs cypress run against it. The footer import still resolves, since Pinia 4 keeps ./package.json in its export map, and the page now prints the new versions. The agent then searches for the other removed names, PiniaStorePlugin and any require('pinia'), finds neither in src, and writes that down too.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Upgrade Pinia in this Vue 3 app to the latest stable major. Read package.json, yarn.lock (the resolved pinia, vue, vite, typescript and vue-tsc versions), vite.config.ts, both tsconfig files, src/main.ts, src/App.vue, src/layouts/default.vue, both stores under src/stores, cypress.config.mjs, cypress/e2e/main.cy.js and .github/workflows/test.yml first. Before changing anything run yarn install, yarn build, yarn type-check and the Cypress test (yarn build, yarn start in the background, then yarn test), and record which pass; a check that fails before the upgrade is reported as pre-existing, not fixed here. Read the breaking changes for every Pinia major between the locked version and latest from its changelog, and the peer dependencies of the version you install from npm. Upgrade pinia, and vue and @vue/devtools-api as its peer ranges require, and keep @vue/compiler-sfc on the same version as vue. Rewrite every defineStore({ id: ... }) call to defineStore('id', { ... }) without changing state, getters or actions, and search src for PiniaStorePlugin and CommonJS requires of pinia. A passing build is not proof: run the Cypress test after the change and paste its result. Do not convert stores to setup syntax and do not upgrade unrelated packages. Open a pull request with a before and after table of versions and checks, the breaking changes with a verdict for each, and anything you found and left alone.",
  "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 that changes package.json, yarn.lock and two source files, each store by two lines. The description opens with a table: pinia, vue, @vue/devtools-api and @vue/compiler-sfc, the version before, the version after and the peer range that required the move. A second table lists the checks, before and after: the build, the Cypress test, and the type check, which is marked as failing on the default branch for a reason unrelated to Pinia, with the error text.

Then the breaking changes from the changelog, one line each with a verdict. The removed defineStore({ id }) signature: used in both stores, changed here. PiniaStorePlugin: not used. ESM only: the app imports Pinia through Vite and has no require, so nothing to change. @vue/devtools-api as a peer: added. The description also shows the intermediate state on purpose, the green build with the failing browser test, because it explains why the pull request touches the stores at all.

A reviewer checks two things the commands cannot. The devtools package is now a direct dependency of the app, and they decide whether it belongs in dependencies or devDependencies for how they ship. And they look at coverage honestly: one browser test adds two items and clears them, so purchaseItems, login and logout are exercised by nothing, and a store-level regression in those paths would not have been caught by this run.

Run it on every Monday morning

Create an automation in the Project that holds the repository with a schedule trigger, cron set to 0 8 * * 1 and your timezone, and this page's prompt with one sentence added: if the lockfile already resolves the latest stable Pinia, end with one line and open nothing. It runs as the member who last changed the automation. The repository has a renovate.json, and a bot's version bump is not a substitute here, because the bump that makes the build pass is the same one that breaks the app until the stores are edited; a github trigger would not start on the bot's pull request either, since it fires only for an owner, member or collaborator.

The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.

Why run it on Rush?

This upgrade has a state in the middle where every static signal says done. The install succeeds, the build is green, and the app throws on the first store it touches. Finding that takes a browser, a running server and a test that clicks through the page, which is the part people skip when they bump a version between other tasks. The agent has its own sandbox with room for all three, runs the test before and after, and keeps each command and its output in the session's transcript at GET /o/{org}/sessions/{id}/messages.

It also separates what the upgrade broke from what was already broken. A type check that fails on the default branch would otherwise be blamed on Pinia, or quietly dropped from the checklist. Because the baseline is run first and recorded, the pull request can say which failures are new, which are old, and which check was not available to it at all, and the reviewer merges knowing exactly what was proved.

Frequently asked questions

Is Pinia 2 to 4 a large migration?

Usually not. Pinia 3 removed APIs that were already deprecated, mainly defineStore({ id }) and Vue 2 support, and Pinia 4's changelog describes its own changes as technically breaking only: ESM only, and @vue/devtools-api installed by you. The work is in moving Vue to at least 3.5.11 with it and proving the app still runs.

Why does the build pass when the stores are still on the old signature?

Vite bundles the call without checking its arguments, so defineStore({ id }) compiles. It fails when a component first uses the store, with a TypeError about destructuring state. A type check would catch it earlier where one runs; in this repository it does not run, so the browser test is the proof.

Do I have to install @vue/devtools-api myself?

Yes, from Pinia 4. It is a peer dependency, ^8.2.1 for Pinia 4.1.0, and the package manager only warns when it is missing. The agent adds it in the same commit as the Pinia bump.

More Pinia jobs

More jobs like this: Upgrade dependencies weekly

Keep reading