# Convert a CoffeeScript Project to Modern JavaScript With decaffeinate

Yes. An agent runs decaffeinate over each .coffee file, fixes what the tool flags, drops the compile step and proves the old tests pass on the new code.

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

## What the agent does

The agent starts with the build, because a CoffeeScript project has two copies of every file and it has to know which one ships. In a library like jsog/jsog, `package.json` lists `coffee-script` `^1.10.0` beside `mocha` and `moment`, and the `compile` script runs `coffee --compile --output lib/ src/*.coffee` and then the same for `src-test/` into `test/`. `main` points at `lib/JSOG`, the compiled files are committed with a `// Generated by CoffeeScript 1.10.0` header, and `.npmignore` leaves `src` out of the package. The `coffee-script` name itself is deprecated on npm with the note that CoffeeScript has moved to `coffeescript`, with no hyphen. An install today resolves 1.12.7, so `npm test` rewrites that header line in both committed outputs before a single test runs.

Before converting anything the agent runs `npm test` and keeps the output as the baseline. Then it runs decaffeinate on `src/JSOG.coffee` and `src-test/JSOGtest.coffee`. The tool prints a list of suggestion codes at the top of each result, and the agent treats that list as its work queue. For the library it names DS101 (an `Array.from` wrapped around each comprehension), DS207 (verbose null checks) and DS209 (a top-level `return`). For the test file it names DS102, the `return` it adds in front of every `it(...)` call because CoffeeScript returns the last expression of a function.

DS209 is the one that can break users. The source ends with a bare `return JSOG`, which was legal because the CoffeeScript compiler wraps every file in `(function() { ... }).call(this)`. decaffeinate emits no wrapper, so the converted file still loads through `require`, where Node supplies a function around the module, but a browser parsing it as a plain script stops with `SyntaxError: Illegal return statement`. This library sets `window.JSOG` and registers an AMD module, and `bower.json` names `lib/JSOG.js` as `main`, so script-tag use is a supported path. The agent restores a function wrapper around the file and deletes the trailing `return`. That also keeps `JSOG`, `nextId` and `isArray` from becoming page-level bindings.

It handles the rest one by one. The `Array.from` calls sit behind the file's own `isArray` check, so they come out. The defaults stay as decaffeinate wrote them, `if (idProperty == null) { idProperty = '@id'; }`, because a CoffeeScript default applies to `null` as well as to a missing argument and a JavaScript default parameter does not. Then it removes `coffee-script`, the `compile`, `build` and `prepublish` scripts and the `src` line in `.npmignore`, makes `lib/JSOG.js` the hand-edited source, and runs the old compiled test file from git against the new library before it runs the converted tests.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Convert this CoffeeScript project to plain JavaScript with decaffeinate and remove the compile step. First read package.json, any Cakefile or Makefile, .npmignore, bower.json and the CI config, and write down which directories hold .coffee sources, where compiled output goes, whether compiled files are committed, and what main points at. Run the existing test command and save its output as the baseline. Run decaffeinate on every .coffee file, sources and tests. For each file, list the DS suggestion codes decaffeinate printed and resolve each one or say why it stays. Check specifically: a top-level return or code that relied on the CoffeeScript function wrapper (restore a wrapper if the file can be loaded by a script tag, sets a window global or defines an AMD module), default arguments that must still apply to null, implicit returns in test callbacks, and Array.from around values already known to be arrays. Put the converted source where main points, delete the .coffee files and the generated copies, remove coffee-script or coffeescript and every script that calls coffee, and fix .npmignore or the files list so the package still contains what main needs. Before deleting the old compiled test file, run it against the converted library and report the result; then run the converted tests. Parse each converted library file as a classic script and as a CommonJS module and report any syntax error. Read the Node versions in the CI config and say which of them cannot parse the syntax decaffeinate emits; do not transpile, report it. Open a pull request with the baseline output, the output after, and the table of suggestion codes.",
  "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 deletes `src/JSOG.coffee` and `src-test/JSOGtest.coffee`, replaces `lib/JSOG.js` and `test/JSOGtest.js` with readable JavaScript that carries the original comments, and edits `package.json` so `test` is just `mocha`. Its description holds a table with one row per suggestion code and what was done about it, the baseline test output next to the output after, and the two parse checks on the library file: as a CommonJS module and as a classic script.

The reviewer reads the wrapper first, since that is the hand-written part, then the three export branches at the bottom of the file (`module.exports`, `window.JSOG` and the AMD `define`). They also read one finding the agent leaves alone. `.travis.yml` lists Node 0.12, 0.11 and 0.10, and the converted code uses `const`, arrow functions, template literals and computed property names, which those releases cannot parse. Raising the CI matrix, or adding a transpile step to keep old runtimes, changes what the library supports, so the pull request reports it and asks.

If the old compiled tests fail against the new library, the session says so and the pull request is opened as a draft with the failing output. A conversion that only passes its own converted tests has not shown that behaviour was kept.

## Run it on every repository that still compiles CoffeeScript

Small CoffeeScript packages tend to come in groups: a company wrote a dozen of them in the same two years and each has the same `coffee --compile` script. From a script on your server, list the repositories whose `package.json` names `coffee-script` or `coffeescript`, and send this body to `POST /o/{org}/sessions` once per repository with that repository in `resources`. Add a `request_id` that is a UUID v5 of the repository's full name, so running the script again returns the sessions it already started.

Every call answers `202` with the session at once. A run past the key's `max_concurrent` is created `queued` and starts when a slot frees, so the script needs no retry loop. Set a `webhook_url` on the key to receive `run.completed` for each run it started, then read the pull request from the session.

## Why run it on Rush?

The conversion tool is deterministic; the judgement is in what it flags, and that judgement needs evidence. In its sandbox the agent keeps the CoffeeScript compiler's output and the converted file side by side, runs the same tests against both, and parses the result the two ways a consumer can load it. Each of those commands and its output stays in the session's transcript, so a reviewer who doubts the wrapper can read the `SyntaxError` that led to it.

A laptop run of decaffeinate tends to stop at a green test command. Here the baseline is recorded before the first edit, the old tests are held against the new code, and the things the agent chose not to change are written down. Twelve packages converted in twelve sandboxes come back as twelve pull requests with the same table in each.

## Frequently asked questions

### Does decaffeinate produce code that behaves the same?

It aims to keep behaviour exactly, which is why its output is sometimes more defensive than a person would write: `Array.from` around loops, explicit `!= null` checks, a `return` before the last call in every function. Those are marked with DS codes so they can be cleaned up by someone who knows the types involved. The agent resolves each code and reruns the tests after.

### Why does my converted file fail in the browser with "Illegal return statement"?

The CoffeeScript compiler wrapped each file in a function, so a `return` at the top level was allowed. decaffeinate does not add that wrapper and flags the line as DS209. Wrap the file in a function yourself, or remove the `return` if nothing reads the value.

### Will it convert the tests too?

Yes, every `.coffee` file, tests included. Before the old compiled test file is deleted the agent runs it against the converted library, so the first proof does not depend on the converted tests being right.

### Does it move the project to ES modules or TypeScript at the same time?

No. The prompt keeps `require` and `module.exports` and changes one thing, the source language. A second run can take the JavaScript further once this pull request is merged; mixing both makes the diff impossible to review against the old output.

### What if a file does not convert?

decaffeinate stops with an error that names the line when it meets a construct it cannot translate safely. The agent reports the file and the message, converts the rest, and leaves that file and the compiler in place instead of rewriting it by hand without saying so.

## More jobs like this: Upgrade dependencies weekly

- [Migrate a Go Project From dep (Gopkg.toml) to Go Modules](https://getrush.ai/run/migrate-dep-to-go-modules/dep/)
- [Migrate From drf-yasg to drf-spectacular in Django REST Framework](https://getrush.ai/run/migrate-drf-yasg-to-drf-spectacular/drf-yasg/)
- [Migrate From faker to @faker-js/faker in a Node.js Project](https://getrush.ai/run/migrate-faker-to-faker-js/faker/)
- [Migrate From Flask-Cache to Flask-Caching](https://getrush.ai/run/migrate-flask-cache-to-flask-caching/flask-cache/)
- [Migrate From Flask-JWT to Flask-JWT-Extended](https://getrush.ai/run/migrate-flask-jwt-to-flask-jwt-extended/flask-jwt/)
- [Migrate From Flask-RESTPlus to Flask-RESTX](https://getrush.ai/run/migrate-flask-restplus-to-flask-restx/flask-restplus/)

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