Adding TypeScript to the Project

In the previous sections, we looked at the dictionary app. In this section and the ones after it, we will convert our JavaScript code to TypeScript, so we get static type checking and better editor support.

JavaScript does not check types. A type error shows up when the code runs, which makes some bugs harder to catch during development. TypeScript adds optional static types to JavaScript, so we can catch those errors at compile time, and we get better tooling and code organization along with them.

Installing TypeScript

First, we need to install TypeScript as a development dependency in our project:

pnpm install typescript --save-dev

We add typescript as a development dependency because we only need it while developing, to compile TypeScript code into JavaScript. The compiled JavaScript code is bundled and served to the client in production.

Configuring TypeScript

Next, we need to create a tsconfig.json file in the root of our project. This file defines the TypeScript compiler options and project settings. Run the following command to generate a basic tsconfig.json file:

npx tsc --init

Overwrite the generated file with the following content:

{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "module": "ESNext",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "skipLibCheck": true,

    /* Bundler mode */
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,

    /* Linting */
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true
  },
  "include": ["src"]
}

These are the recommended settings for a TypeScript project using a bundler like Vite. Let’s go through some of the key settings:

  • target: Specifies the ECMAScript target version for the compiled JavaScript code.
  • module: Specifies the module system to use (ESNext for Vite).
  • lib: Specifies the libraries to include when compiling the TypeScript code.
  • moduleResolution: Specifies the module resolution strategy for TypeScript.
  • strict: Enables strict type checking options.
  • noUnusedLocals, noUnusedParameters: Ensures that all declared variables and parameters are used.
  • noFallthroughCasesInSwitch: Prevents fallthrough cases in switch statements.
  • include: Specifies the folders to include when compiling the TypeScript code.

Updating the package.json Scripts

Next, we need to update the package.json scripts to use TypeScript for building the project. Update the scripts section in package.json as follows:

  {
    "scripts": {
-     "build": "vite build",
+     "build": "tsc && vite build",
    }
  }

Notice that we updated the build script to compile TypeScript code using the TypeScript compiler (tsc) before building the project with Vite.

We do not need to change the dev script because Vite handles the compilation of TypeScript code during development.

Change the File Extensions to .ts

Now that we have set up TypeScript in our project, we need to rename our JavaScript files to TypeScript files by changing the file extensions from .js to .ts. In our case, there is only a src/main.js file, which we will rename to src/main.ts.

mv src/main.js src/main.ts

TypeScript is a superset of JavaScript, so technically, valid JavaScript code is also valid TypeScript code. However, TypeScript adds features that JavaScript does not have, like static typing, interfaces, and type annotations, and we can use them in our code.

At the moment, if you open the src/main.ts file in VSCode, you might see some TypeScript errors due to the lack of type annotations and TypeScript-specific syntax. Do not worry; we will address these errors shortly.

Since we renamed src/main.js to src/main.ts, we need to update the src/index.html file to point to the new TypeScript file:

- <script type="module" src="./main.js"></script>
+ <script type="module" src="./main.ts"></script>

Similarly, we should update the prettier command in package.json to target TypeScript files:

- "format": "prettier --write \"src/**/*.js\" --config \".prettierrc.json\""
+ "format": "prettier --write \"src/**/*.ts\" --config \".prettierrc.json\""

Running the Project

Now that we have set up TypeScript in our project, we can run the project using the following command:

pnpm dev

Open the browser and navigate to http://localhost:5173 to see the Dictionary App running. You should see the same functionality as before, but now the project is using TypeScript.

Building the Project

To build the project for production, run the following command:

pnpm build

This command compiles the TypeScript code to JavaScript and bundles the project for production. The output will be available in the dist directory. However, since we have not added any TypeScript-specific code yet, tsc will report many errors. These errors appear because we configured TypeScript to be strict in our tsconfig.json file, and our source code does not yet meet those strict requirements. We will address these errors in the upcoming tasks.

Let’s add a script to package.json to perform type checking without emitting any files:

  {
    "scripts": {
+     "type-check": "tsc --noEmit",
    }
  }

Now, you can run the type-checking script using the following command:

pnpm type-check

You should see the same errors that were reported during the build process.

Note that running the project in development mode (pnpm dev) does not require type-checking because Vite transpiles TypeScript without performing type checks. However, you should run the type-checking script before building the project for production to catch any type errors early.

Checkpoint: Commit your progress.

git add .
git commit -m "dictionary-01: Add TypeScript configuration"
git push