How to Set Up a Next.js Project With TypeScript From Scratch?

Introduction

If you want to build modern, fast, and SEO-friendly web applications, Next.js with TypeScript is one of the best combinations available today.

Next.js provides powerful features like server-side rendering, static site generation, and routing out of the box. TypeScript adds type safety, better developer experience, and fewer runtime errors.

In this step-by-step guide, you will learn how to set up a Next.js project with TypeScript from scratch in a simple and practical way.

Why Use Next.js With TypeScript?

Before we start, let’s understand why this combination is so popular among developers.

Better code quality with type safety
Improved developer experience with auto-completion
Easier debugging and fewer bugs
Built-in SEO optimization features
Scalable and maintainable project structure

Prerequisites

Before setting up the project, make sure you have the following installed:

Node.js (recommended latest LTS version)
npm or yarn
Basic knowledge of JavaScript and React

You can check your Node.js version using:

node -v

Step 1: Create a Next.js App With TypeScript

The easiest way to create a Next.js project with TypeScript is by using the official create-next-app tool.

Run the following command:

npx create-next-app@latest my-next-app --typescript

This command will:

Create a new Next.js project
Automatically configure TypeScript
Set up folder structure
Install required dependencies

Step 2: Navigate to Your Project

Move into your project folder:

cd my-next-app

Step 3: Understand the Project Structure

After setup, your project will look like this:

my-next-app/
  app/
  pages/
  public/
  styles/
  tsconfig.json
  package.json

Important Files Explained

app/ or pages/ → Handles routing
public/ → Static assets like images
styles/ → CSS files
tsconfig.json → TypeScript configuration

Step 4: Run the Development Server

Start your project using:

npm run dev

Now open your browser and visit:

http://localhost:3000

You will see your Next.js app running.

Step 5: Create Your First TypeScript Page

Let’s create a simple page using TypeScript.

Inside the pages folder, create a file:

pages/home.tsx

Now add the following code:

import React from "react";

type Props = {
  name: string;
};

const Home = ({ name }: Props) => {
  return <h1>Hello, {name}! Welcome to Next.js with TypeScript</h1>;
};

export default Home;

Step 6: Add Types to API Routes

Next.js also supports API routes. You can use TypeScript for them as well.

Create a file:

pages/api/hello.ts

Add the following code:

import type { NextApiRequest, NextApiResponse } from "next";

type Data = {
  message: string;
};

export default function handler(
  req: NextApiRequest,
  res: NextApiResponse<Data>
) {
  res.status(200).json({ message: "Hello from API" });
}

Step 7: Customize TypeScript Configuration

Next.js automatically creates a tsconfig.json file.

You can customize it based on your needs.

Example:

{
  "compilerOptions": {
    "target": "es6",
    "lib": ["dom", "dom.iterable", "esnext"],
    "strict": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true
  }
}

Important Options

strict → Enables strict type checking
moduleResolution → Helps resolve modules properly
resolveJsonModule → Allows importing JSON files

Step 8: Add ESLint and Formatting (Optional but Recommended)

Next.js comes with ESLint pre-configured.

Run:

npm run lint

You can also add Prettier for formatting consistency.

Step 9: Build for Production

To create an optimized production build:

npm run build

Then run:

npm start

Best Practices for Next.js With TypeScript

1. Use Types for Props and State

Always define types for better readability and maintainability.

2. Keep Types in Separate Files

Create a types folder to manage reusable types.

3. Enable Strict Mode

This helps catch bugs early.

4. Use Interface or Type Alias Properly

Use interface for object structures
Use type for complex types

5. Avoid Any Type

Using any defeats the purpose of TypeScript.

Common Mistakes to Avoid

Not enabling strict mode
Overusing any type
Ignoring TypeScript errors
Mixing JavaScript and TypeScript files unnecessarily

Conclusion

Setting up a Next.js project with TypeScript is simple and highly beneficial for modern web development.

With just a few commands, you get a powerful setup that supports scalability, performance, and better code quality.

By following the steps in this guide, you can quickly start building professional, SEO-friendly web applications using Next.js and TypeScript.

Start experimenting with components, APIs, and routing to fully understand the power of this stack.