Codex in the Terminal: JavaScript to TypeScript

Codex in the Terminal: JavaScript to TypeScript

A JavaScript-to-TypeScript migration gets risky when file renames, module changes, and behavior fixes land together. Codex can accelerate that mess, or help keep it small. The difference is the workflow. Here is a side-by-side migration plan: manual editing on one side, Codex-assisted changes on the other, with identical acceptance checks.

Assume a small CommonJS Node project: source in src, JavaScript tests using node --test, and an entry point at src/index.js. Adapt the commands if your project uses a bundler, ESM, or another test runner. This is a worked plan, not a measured benchmark.

Step 1: Record the JavaScript Baseline Before Codex Edits

Create a branch with git switch -c migrate/typescript. Run npm test and record the result. Check the package.json scripts, Node version, module format, and every place tests import source files. Commit unrelated work first.

• Manual path: Inspect imports and scripts yourself before choosing migration boundaries.
• Codex path: Ask for a repository inventory without changing any files.

My first prompt would be: Inspect package.json, source imports, and test entry points. Propose a staged TypeScript migration that preserves CommonJS behavior. Identify build and runtime risks. Do not edit files yet.

Read the plan. If Codex proposes converting the project to ESM, reject that extra scope. Changing languages does not require changing module systems.

Step 2: Add TypeScript Without Renaming Every File

Install tooling with npm install --save-dev typescript @types/node. Set target to ES2022, module and moduleResolution to NodeNext, allowJs to true, checkJs to false, strict to true, rootDir to src, and outDir to dist. Include src/**/* and exclude dist and node_modules. Keep package.json explicitly CommonJS.

• Manual path: Write the configuration and connect the build scripts yourself.
• Codex path: Request only configuration changes, then inspect the resulting diff.

Add build as tsc and typecheck as tsc --noEmit. Make start run node dist/index.js. For this example, point test imports at dist instead of src, and make test run npm run build followed by node --test. Ignore dist in Git. Now both migrated and unmigrated source files have one runtime path.

Run npm run typecheck and npm test before renaming anything. This separates build-pipeline mistakes from typing mistakes.

Step 3: Convert One Leaf Module With Codex

Pick a utility with few dependencies, such as src/parse-port.js. Rename it to parse-port.ts and describe its real contract: accepted strings, missing values, valid ranges, and thrown errors. Preserve its CommonJS interface rather than introducing ESM exports accidentally.

• Manual path: Add parameter and return types while tracing callers yourself.
• Codex path: Supply the contract and request one narrowly scoped patch.

Use a prompt like: Migrate only parse-port and its necessary import wiring. Preserve runtime behavior and the existing export shape. Do not add any, suppression comments, or new dependencies. Explain ambiguous inputs before choosing their types.

Run npm run typecheck and npm test. Inspect git diff, including tests. A green test suite is less convincing if the agent quietly weakened assertions.

Step 4: Migrate Callers and Validate External Data

Move outward through callers in small batches. At HTTP, JSON, environment-variable, and filesystem boundaries, use unknown until validation establishes a type. A type assertion does not validate incoming data. Keep schema-library adoption separate unless the project already uses one.

• Manual path: Compiler errors become your checklist for updating dependent modules.
• Codex path: Let the agent explain errors before applying targeted repairs.

Ask Codex to distinguish missing annotations from genuine behavioral uncertainty. Review every assertion, non-null assertion, and newly optional property. Rebuild from a clean dist directory so stale JavaScript cannot hide a missing output file. Commit each passing batch.

Step 5: Compare Codex Review Effort and Token Spend

Manual migration gives direct control but involves repetitive edits. Codex reduces that repetition while adding review work. Compare total time through passing tests, not just typing time.

If you route Codex through Fluxo, one key and the base URL https://api.fluxorelay.com cover Claude, GPT, Gemini, DeepSeek, Kimi, GLM, Qwen, Grok, and more. It works with Claude Code, Codex, Gemini CLI, and any OpenAI SDK. You could compare GPT-6.1 Sol on a migration patch with Claude Sonnet 5.5 reviewing the diff, where your client supports model selection.

Fluxo bills real tokens, including cache reads and writes, with no monthly fee. Small prompts and bounded diffs make spending easier to inspect. If that fits your terminal workflow, consider creating a Fluxo account. Users also earn a referral share when people they invite pay.

The TypeScript Migration Verdict: Codex Edits, You Approve

Choose Codex-assisted migration for repetitive, well-tested modules; choose manual investigation for unclear contracts and runtime boundaries. After the final rename, disable allowJs, clean dist, rebuild, typecheck, and test. Codex wins as a constrained patch author, not as an unchecked migration owner.