On this page

Hands‑On Exercise: Migrate a Small JS Module to TypeScript

Enrico Hochkoeppler Profile

By Enrico Hochkoeppler

Web Developer & TutoriaLibre Founder

We’ll start with a small JavaScript module that processes user data.

It’s intentionally messy—just like real legacy code.


Step 1 — Start With a Plain JavaScript Module​

userUtils.js​


function normalizeUser(user) {

  return {

    id: user.id,

    name: user.name.trim(),

    email: user.email.toLowerCase(),

  };

}



function isValidEmail(email) {

  return email.includes("@");

}



module.exports = {

  normalizeUser,

  isValidEmail,

};

This module:

We’ll migrate it safely.


Step 2 — Enable JS Support in TypeScript​

Install TypeScript:


npm install --save-dev typescript @types/node

Initialize:


npx tsc --init

Update tsconfig.json:


{

  "compilerOptions": {

    "allowJs": true,

    "checkJs": false,

    "outDir": "dist"

  },

  "include": ["src"]

}

This allows TypeScript to compile JS files without type‑checking them yet.


Step 3 — Add JSDoc Types (No Renaming Yet)​

Before converting to .ts, we add types using JSDoc.

This gives us type safety inside JavaScript.

Modify:

userUtils.js​


/**

 * @typedef {Object} User

 * @property {string} id

 * @property {string} name

 * @property {string} email

 */



/**

 * @param {User} user

 * @returns {User}

 */

function normalizeUser(user) {

  return {

    id: user.id,

    name: user.name.trim(),

    email: user.email.toLowerCase(),

  };

}



/**

 * @param {string} email

 * @returns {boolean}

 */

function isValidEmail(email) {

  return email.includes("@");

}



module.exports = {

  normalizeUser,

  isValidEmail,

};

Now TypeScript understands:

This is a zero‑friction improvement.


Step 4 — Turn on checkJs to Type‑Check JS Files​

Update tsconfig.json:


"checkJs": true

Now TypeScript will catch errors in .js files.

Example error caught​

If someone calls:


normalizeUser(123);

TypeScript will warn:


Argument of type 'number' is not assignable to parameter of type 'User'.

We’ve improved safety without renaming anything.


Step 5 — Convert the File to TypeScript​

Rename:


userUtils.js → userUtils.ts

The JSDoc types still work, but now we can replace them with real TypeScript types.


Step 6 — Replace JSDoc with TypeScript Types​

userUtils.ts​


export type User = {

  id: string;

  name: string;

  email: string;

};



export function normalizeUser(user: User): User {

  return {

    id: user.id,

    name: user.name.trim(),

    email: user.email.toLowerCase(),

  };

}



export function isValidEmail(email: string): boolean {

  return email.includes("@");

}

We now have:


Step 7 — Update Imports in Other Files​

If another JS file imports this module:


const { normalizeUser } = require("./userUtils");

It still works because TypeScript emits CommonJS by default.

If using ES modules:


import { normalizeUser } from "./userUtils.js";

Everything remains compatible.


Step 8 — Compile and Run​

Compile:


npx tsc

Run:


node dist/userUtils.js

You’ve migrated a JS module to TS with:


Step 9 — Optional: Increase Strictness Later​

Once the project stabilizes, enable:


"strict": true

Or incrementally:

This tightens type safety without overwhelming the migration.


What You Learned​

This hands‑on exercise demonstrates a realistic, low‑friction migration path:

1. Start with JS​

2. Add JSDoc types​

3. Enable checkJs​

4. Rename to .ts​

5. Replace JSDoc with TS types​

This is exactly how real teams migrate large JavaScript codebases safely and incrementally.

Found this helpful? Share the knowledge...

... or support this project to keep it alive!

Buy Me a Coffee

Previous

Handling 'any' in Legacy Code

Next

Advanced TypeScript