How to Add TypeScript to Existing Next.js Project

It is becoming increasingly common to use TypeScript with JavaScript frameworks such as React, Vue or Express. I have my personal website built on Next.js which is a framework for building React applications with nice features such as server-side rendering, automatic code splitting, and optimized performance. One of my 2023 resolutions was to work more with TypeScript, so I decided to add it to my current website and document the whole process.

Note: It is possible to add TypeScript during the initialization phase of the project, but this article is intended for those who already have Next.js projects and want to add TypeScript to them.

To Add Typescript to an Existing Next.js Project, You Can Follow These Steps:

Step 1 of 7

Install the necessary dependencies by running the following command in your project's root directory:

npm install -D typescript @types/react @types/react-dom @types/node

This will install the TypeScript compiler and the necessary type definitions for React and Node.js.

Step 2 of 7

Rename the existing jsconfig.json to tsconfig.json, or create a new tsconfig.json if the former file does not exist. Now we need to update the contents of the file to include TypeScript-specific configuration options. Merge your configuration with the code below if required:

{
  "compilerOptions": {
    "target": "es5",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "baseUrl": ".",
    "paths": {
      "@/components/*": ["components/*"],
      "@/pages/*": ["pages/*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
  "exclude": ["node_modules"]
}

Step 3 of 7

Update next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  i18n: {
    defaultLocale: 'en',
    locales: ['en'],
  },
  reactStrictMode: true,
};

module.exports = nextConfig;

Step 4 of 7

Rename any existing .js files to .ts or .tsx, depending on whether the file contains JSX or not. For example, if you have a file called pages/index.js, rename it to pages/index.tsx.

You can also rename your existing directories such as `pages` or `components` to `pages-old` and `components-old` and create new empty directories with TypeScript files in case you need to reference the original files later.

Step 5/7

Update any files that import other files to use the .ts or .tsx extension. For example, if you have a file called index.ts that imports a file called header.js, update the import statement in index.ts to use the .ts or .tsx extension like so: import Header from './header.tsx';

Step 6 of 7

Covert your JavaScript code into TypeScript code. Here is an example of how to convert pages/_app.js to pages/_app.tsx

import 'normalize.css';
import '@/styles/index.scss';

function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />;
}

export default MyApp;

import 'normalize.css';
import '@/styles/index.scss';

import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />;
}

Step 7 of 7

Restart your development server by running npm run dev, and your TypeScript code should now be compiled and running alongside your React code.

Note: you may need to adjust some of these steps depending on the specific structure of your project. However, these steps should be a good starting point for most projects.

The end, I hope this information was helpful, stay tuned for more content :)