Moving a small JavaScript project to TypeScript

A small JavaScript project is a useful place to begin with TypeScript. You already know what the code should do, and you can convert one part at a time. A model can help explain unfamiliar errors and suggest types, while you stay responsible for checking that the program still behaves as expected.

The aim is to make assumptions visible: which values a function accepts, what it returns, and where information might be missing.

§ Start with a working baseline

Before changing files, save the current state in version control. Run the project’s existing checks and try its main user flows. If something already fails, record that first. This gives you a way to distinguish an existing problem from one introduced during the migration.

Choose a small, self-contained file for the first conversion. A utility that formats a date or calculates a total is easier to review than an application entry point with many dependencies.

Give the model that file, its callers, and any relevant tests. Include the package configuration so it can see how the project runs. Leave credentials and private customer data out of the conversation.

§ Ask for a narrow change

A useful first request is: Convert this file to TypeScript without changing its runtime behavior. Explain the types you add, identify assumptions you cannot verify, and leave unrelated cleanup for later.

This keeps the task concrete. A migration becomes harder to assess when a model also renames functions, reorganizes folders, or changes error handling.

If you use a coding assistant, Vana API provides access to models such as Claude Sonnet 5.5 through an endpoint compatible with OpenAI, Anthropic Messages, and Gemini native protocols. It works with tools including Claude Code and Codex. Configure your chosen tool for Vana API, then use it to work through one file at a time.

§ Let JavaScript and TypeScript coexist

You do not need to rename every file at once. TypeScript supports gradual adoption through a configuration file called tsconfig.json. Its allowJs option lets JavaScript files participate in the project alongside TypeScript files. The separate checkJs option enables type checking inside JavaScript files.

Ask the model to explain a minimal configuration for your existing framework and build tool. Some projects already include TypeScript support; others need an additional compilation step. Renaming a file alone does not guarantee that your current runtime can execute it.

Enable strict checking for the TypeScript code from the start where practical. If that exposes too much work immediately, keep the migration scope small instead of accepting a broad rewrite.

§ Understand the types being added

TypeScript can infer many types from the code. A variable initialized with a string usually needs no extra annotation. Explicit types are especially useful at function boundaries and where data enters the application.

• Function inputs: Which arguments are required, and which may be omitted?
• Missing values: Can a lookup return undefined, or an API field contain null?
• Shared objects: Do several functions use the same customer or order structure?
• External data: What evidence shows that a response actually matches the expected shape?

Be cautious when the model uses any or a type assertion to silence an error. The any type disables useful checking for that value. An assertion tells the compiler to trust a claim; it does not verify the data.

TypeScript types do not validate incoming JSON at runtime. Data from an API, a form, or a stored file may still need explicit validation.

§ Check each conversion before continuing

After each file, run the type checker, relevant tests, and the application’s normal build. Review the diff for behavior changes. Passing a type check is useful evidence, but it does not prove that calculations, network requests, or user interactions remain correct.

Ask the model to explain each remaining error before proposing a fix. Commit a working conversion, then move to the next file. Small commits give you clear review points and an easy way back.

To try this workflow, create a Vana API account. Usage is billed per actual token with no monthly fee, so you can begin with one file and assess the result before expanding the migration.