All jobs

Migrate a Hand-Rolled Hash Router to @solidjs/router in a SolidJS App

Yes. An agent replaces a custom hash router with @solidjs/router, keeps every existing URL working, and proves each route in the built app in its browser.

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 starts by mapping the router it is replacing, because every page in the app reaches it a different way. In an app like solidjs/solid-realworld, src/store/createRouteHandler.js is two dozen lines: a location signal fed by the hashchange event, a match(name, regex) function that tests the hash against a regular expression and stores the capture groups, and getParams(). src/App.js consumes it in a <Switch> of seven <Match> cases, editor with /^editor\/?(.*)/, settings, login, register, article with /^article\/(.*)/, profile with /^@([^/]*)\/?(favorites)?/, and home with /^#?$/. src/store/index.js hands the router to the tree through a RouterContext and a useRouter() hook, and src/components/NavLink.js builds every link as href={#/${route}} and marks it active when getParams()?.routeName matches.

It then finds the places that bypass the router entirely, which is where migrations like this break. src/pages/Auth.js reads location.hash.includes("login") to decide between sign in and sign up and redirects with location.hash = "/"; Settings.js, Article/Article.js and Editor/Editor.js redirect the same way after a save, a delete and a publish. src/pages/Home/index.js parses ?tab= out of location() by hand to switch between the global feed, the personal feed and a tag, and Home.js writes tag links as #/?tab=${tag}. Profile/index.js and Profile.js read props.params[0] for the username and test location().includes("/favorites") for the second tab, and Article/index.js and Editor/index.js take the slug from props.params[0]. The agent lists all of these in the pull request before changing any.

The replacement keeps hash URLs, because .github/workflows/gh-pages.yml publishes public/ to GitHub Pages, which cannot rewrite paths to index.html, so the agent uses HashRouter from @solidjs/router rather than Router. src/index.js wraps the app in it with the store Provider as the router's root, and App.js declares Route elements for /, /login, /register, /settings, /editor/:slug?, /article/:slug and the profile pages, with Settings and Auth still loaded through lazy as they are today. The @ prefix in profile URLs is the one pattern the agent has to check against the router's matcher before committing to it; if a literal prefix inside a segment is not matched, it declares the profile route with an array of two paths and reads the username from the location, so #/@jane and #/@jane/favorites keep resolving. NavLink.js becomes a thin wrapper over the router's A with activeClass="active" and end on the home link, Home/index.js switches to useSearchParams for tab, the four location.hash = redirects become useNavigate(), and Auth.js reads useLocation().pathname instead of the raw hash. createRouteHandler.js, the RouterContext and useRouter are deleted.

The proof is the built app behaving as before. The agent runs npm install and npm run build, which runs Rollup 2.52 with babel-preset-solid into public/, then serves public/ as npm start does and opens it in its browser in the sandbox: it visits #/, #/?tab=welcome, #/login, #/register, #/article/<slug> and #/@<username>/favorites against the RealWorld API the app already points at, and checks that the active class on the navbar follows the route, that the tag pill changes the feed, and that a hard reload on a deep link lands on the same page. The repository declares no tests ("test": "test" in package.json), so the browser session, with screenshots in the transcript, is the evidence, and the agent says so.

Start it with one API call

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

{
  "agent": "claude",
  "input": "Replace this SolidJS app's hand-written hash router with @solidjs/router while keeping every existing hash URL working. Read src/store/createRouteHandler.js, src/store/index.js, src/App.js, src/components/NavLink.js and every file under src/pages that reads location or assigns location.hash first, and list them. Use HashRouter because the site deploys to GitHub Pages, declare one Route per existing Match case with the same URL shapes, replace NavLink with the router's A component with the same active class, move query-string parsing to useSearchParams and redirects to useNavigate, and delete the old router. Run the Rollup build, serve public/, and open each route in the browser, including a tag filter, a profile favorites page and a hard reload on a deep link. Open a pull request listing every file changed and what each route maps to.",
  "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 adds @solidjs/router to package.json and package-lock.json, deletes src/store/createRouteHandler.js, and edits src/index.js, src/store/index.js, src/App.js, src/components/NavLink.js, src/components/NavBar.js and the page entry files under src/pages that read or wrote the hash. rollup.config.js, public/index.html and the deploy workflow are unchanged.

The description carries a table mapping each old Match regular expression to its new Route path, the list of files that touched location.hash and what replaced each, and the browser checks with a screenshot per route from the transcript at GET /o/{org}/sessions/{id}/messages. It says plainly that the repository has no test suite and that the browser session is the evidence.

Before merging, a reviewer reads the profile route, the one place the URL shape forced a judgment call, confirms the end prop on the home link so Home is not active on every page, and clicks through the deployed preview once. A follow-up through POST /o/{org}/sessions/{id}/messages can ask for route-level preload functions to replace the createComputed data loading in each page's index.js, which the agent leaves as it is in this pull request.

Run it on every terminal hand-off

A developer who has been meaning to retire the custom router for months starts this from the terminal with this body and the repository in resources, then goes back to feature work. The run reads the real Match cases and the real redirects, so the route table in the pull request is this app's, not a template's.

Send a request_id, a UUID, in the body so a retried start returns the run it already began. When the turn ends, GET /o/{org}/sessions/{id} names the pull request, and a follow-up through POST /o/{org}/sessions/{id}/messages wakes the parked sandbox, with the built app and its dependencies still in place, for the next step of the migration.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

A router swap touches every page, and the failures are the quiet kind: a link that stops highlighting, a ?tab= filter that no longer reads, a save that no longer redirects, a deep link that 404s on GitHub Pages because someone chose path routing. Each of those is one line in a different file. The agent finds them by reading for location and useRouter before it edits, and proves each route in a browser afterwards rather than trusting the build.

On Rush the build, the static server and the browser all run in the agent's own sandbox, and the screenshots and the route table live in the transcript next to the diff. The same body on another SolidJS app with its own home-grown router does the same inventory first, which is what makes the migration safe to hand off.

Frequently asked questions

Will my URLs change?

No. The agent uses HashRouter, so #/article/<slug>, #/@<username> and #/?tab=<tag> keep working, bookmarks included, and the GitHub Pages deploy needs no rewrite rule. Switching to path-based URLs is a separate decision that needs a host that can serve index.html for every path.

What happens to the @username profile URLs?

They are the one pattern the agent checks against the router's matcher before choosing. If a literal @ before a parameter matches, the route is /@:username with favorites as an optional segment; if not, the agent declares the two paths explicitly and derives the username from the location, and the description says which it did and why.

Does the lazy loading of Settings and Auth survive?

Yes. Route takes a component prop, and a component made with lazy() works there as it did inside Match, so Settings and Auth stay in their own chunks under public/. The agent compares the built file list before and after to show the chunks are still split.

There are no tests in this repository. How is the change checked?

By running the built app. The agent serves public/ and visits every route in its browser, including a tag filter, both profile tabs and a hard reload on an article URL, and keeps the screenshots in the transcript. The description says the evidence is a browser session rather than a suite, and offers component tests as a follow-up.

More SolidJS jobs

More jobs like this: Hand off a long task

Keep reading