What the agent does
The agent reads how the app is started and which TypeScript features the runtime has to honour. In an API like santiq/bulletproof-nodejs, npm start runs nodemon, and nodemon.json holds the real command: ts-node -r tsconfig-paths/register --transpile-only ./src/app.ts, watching src and .env. tsconfig.json sets module to commonjs, maps @/* to ./src/*, and turns on experimentalDecorators and emitDecoratorMetadata. package-lock.json resolves ts-node 9.0.0, TypeScript 4.0.3 and typedi 0.8.0. src/app.ts imports reflect-metadata on its first line, and the services are classes marked @Service() that receive their collaborators through the constructor.
That last detail is where a swap to tsx goes wrong, and the agent finds it by calling the API, since starting the server is not enough. With ts-node the app boots and POST /api/auth/signup answers 201. With tsx 4.23.15, the release current when this page was written, the app boots the same way: tsx reads the paths mapping itself, so tsconfig-paths is no longer needed. The same signup request answers 500 with Cannot read properties of undefined (reading 'error'), raised at this.logger.error(e) in src/services/auth.ts. The logger was never injected. tsx compiles with esbuild, which does not emit the design:paramtypes metadata that emitDecoratorMetadata asks for. typedi 0.8.0 reads exactly that metadata to learn a constructor's parameters; when it is missing it calls the constructor with no arguments, so even the parameters carrying an explicit @Inject('logger') arrive as undefined.
The fix is to stop depending on emitted types. Two classes take constructor parameters, AuthService and MailerService. The agent turns each parameter into a decorated property: @Inject('userModel'), @Inject('logger') and the custom @EventDispatcher() keep their tokens, and the one parameter that had no decorator, the mailer, becomes @Inject(() => MailerService), because a bare type can no longer be read at run time. With that change signup answers 201 under tsx, and still 201 under ts-node, so the two commits can land separately.
Then it replaces the launcher. nodemon.json becomes tsx watch --include .env --exclude 'src/**/*.spec.ts' ./src/app.ts in the start script, inspect becomes tsx --inspect ./src/app.ts, and ts-node, tsconfig-paths and nodemon leave devDependencies. Jest keeps ts-jest, which does its own compiling, and the one test in tests/ still passes. The agent also reports something it found on the way and does not fix: npm run build prints 99 type errors and still writes build/, and node build/app.js, the command in the Procfile, fails with Cannot find module '@/config', because tsc does not rewrite path aliases.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Replace ts-node with tsx for running this TypeScript API in development. Read package.json, package-lock.json, nodemon.json, tsconfig.json, jest.config.js, the Procfile, src/app.ts, src/loaders and every class under src that uses a decorator. There is no Docker here: install a MongoDB server, start mongod on 127.0.0.1:27017, copy .env.example to .env and point MONGODB_URI at 127.0.0.1. Start the app with the current ts-node command and send a signup request to POST /api/auth/signup; record the status. Install tsx, start the app with it and send the same request. If the status differs, find the cause: check whether tsconfig.json enables emitDecoratorMetadata, what the dependency injection library reads at run time, and what tsx's compiler emits. Fix it in the source so the app works under both runners, without adding a second compiler, and show the request succeeding under each. Replace the nodemon and ts-node launcher with tsx watch, keeping the watched paths and the ignored spec files, update the inspect script, and remove ts-node, tsconfig-paths and nodemon if nothing else needs them. Run npm test and npm run build and report what each does, including any failure that was already there. Open a pull request with the output of every command.",
"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 two commits. The first changes src/services/auth.ts and src/services/mailer.ts from constructor injection to property injection and is safe on its own. The second changes the scripts, deletes nodemon.json and updates package.json and package-lock.json. The description has four request transcripts: signup under ts-node before, under tsx before, and under each after the fix, with the status and the server's log lines. It quotes the line in typedi that reads design:paramtypes, so the cause is shown and not asserted.
A reviewer weighs the injection change, since it touches how every service is built. Property injection means a service's dependencies are no longer visible in its constructor, and a new service written the old way will fail the same silent way under tsx; the description suggests a short note in the README and says no lint rule enforces it. They also read the build finding. The production start path was broken before this change and is still broken after it, and the pull request says so in its own section so that nobody reads a green dev server as a working deploy.
Run it on every service that still runs on ts-node
Each service is migrated once. For several, send this body to POST /o/{org}/sessions once per repository with that repository in resources, and a request_id that is a UUID v5 of the repository name so that sending the batch again starts nothing new. The prompt's first half, start it, call it, compare, is the part that carries over to any service; the route to call is the one line to change per repository.
Runs past the key's max_concurrent limit are created queued and start as slots free. With a webhook_url on the key, each run posts run.completed or run.failed when its turn ends, and the ones that found a behaviour difference say so at the top of their answer.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The bug this migration introduces is invisible to every cheap check. The server starts, the logs look the same, the one test passes. It shows up only when a request reaches a service whose constructor was never given its arguments. The agent has a sandbox where it runs the database and the API and sends that request under each runner, and the run keeps the four responses and the stack trace that pointed at the cause.
Finding the cause also means reading a dependency's source and checking a claim about a compiler, both of which are quick for an agent with the package tree on disk and tedious for a person in the middle of other work. What comes back is a pull request where the fix, the proof and the leftover problem are each stated once, with the command behind them.
Frequently asked questions
Does tsx support emitDecoratorMetadata?
No. tsx compiles with esbuild, which handles experimentalDecorators but does not emit the type metadata that emitDecoratorMetadata adds. Libraries that read design:paramtypes or design:type at run time, as typedi does for constructor parameters, get nothing. The code has to name its dependencies explicitly.
Do I still need tsconfig-paths?
Not for running under tsx, which resolves the paths entries in tsconfig.json on its own. In this repository the app started and resolved all its @/ imports with the -r tsconfig-paths/register flag removed. The compiled output is a different matter: tsc leaves the aliases in the emitted JavaScript.
Does tsx type-check my code?
No, and neither did the old command, which passed --transpile-only to ts-node. Type errors are found by tsc, which is a separate script. Here npm run build reports 99 of them, so the type check was not part of anyone's dev loop before this change either.
Which Node version does tsx need?
Its package.json declares node >=18.0.0. A repository whose CI image is older, like the Node 10 image named in this one's .circleci/config.yml, is outside that range, so the agent raises the image in the same pull request and says it did.
More ts-node jobs
More jobs like this: Hand off a long task
- Migrate a TypeScript Monorepo from TSLint to ESLint Flat Config (TSLint)
- Migrate a VS Code Extension from TSLint to ESLint (VS Code extension)
- Migrate a Python Test Suite From unittest to pytest (unittest)
- Migrate a Laravel Front End from Vue 2 to Vue 3 (Laravel)
- Migrate a Vue CLI Project to Vite (Vue CLI)