Setting Up Next.js with TypeScript from Scratch

The Next.js TypeScript setup is quick because the support is built in. create-next-app enables TypeScript by default, and a plain JavaScript project needs only a rename and a dev-server run to get types, a tsconfig, and a generated declaration file. This guide covers the generated files and how to type the config.

For a new project, the scaffolder already ships TypeScript, so you can skip straight to writing typed code. To add TypeScript to an existing project, rename a file and restart the server:

bash

mv app/page.js app/page.tsx
npm run dev

On the next run, Next.js installs TypeScript and the React type packages, then writes a tsconfig.json with recommended options. That is the whole setup for a simple project.

What tsconfig.json contains

The generated tsconfig enables strict checking and modern module resolution, with a few options doing most of the work. The important ones look like this:

json

{
  "compilerOptions": {
    "strict": true,
    "jsx": "react-jsx",
    "moduleResolution": "bundler",
    "paths": { "@/*": ["./*"] }
  }
}

The strict flag turns on the full set of type checks. The jsx option tells the compiler to compile JSX with the automatic runtime, so components do not need a React import just to use JSX. The paths entry wires up the default import alias, and Next.js also sets noEmit and incremental, which keep checking fast while the build handles compilation.

The generated type file

Next.js creates next-env.d.ts in the project root. It references Next.js types so the compiler understands image imports and framework-specific types.

The file is managed by Next.js, so do not edit it, and add it to .gitignore. It must stay in the tsconfig include array, which create-next-app sets up automatically.

Type the config file

A next.config.ts file can import the NextConfig type to get autocomplete and checking for every option:

typescript

// next.config.ts
import type { NextConfig } from 'next';
 
const nextConfig: NextConfig = {
  typedRoutes: true,
};
 
export default nextConfig;

The typedRoutes option makes Next.js generate link types so invalid hrefs fail in the editor, and it also types navigation calls such as router.push. The NextConfig type flags misspelled config keys before the server starts.

The editor experience

Next.js ships a TypeScript plugin that adds editor hints for segment configs, client hooks, and server directives. In VS Code, open the command palette, choose TypeScript: Select TypeScript Version, and pick Use Workspace Version to activate it. The plugin warns when a client hook such as useState appears in a file without the use client directive.

Check types before shipping

The production build fails when type errors are present. To check types without a full build, run:

bash

next typegen && tsc --noEmit

This generates route types and then runs the TypeScript compiler over the project.

For the config in depth, read next.config.ts Explained: Structure and Type Safety. To type page props and route parameters, read Typing Page Props, Params, and Search Params.