How To Set Up a New TypeScript Project

• Install TypeScript locally and initialize your project:
  Begin by installing TypeScript as a development dependency in your project using npm i typescript --save-dev. This ensures that everyone working on the project uses the same TypeScript version. Next, initialize your project with npx tsc --init, which creates a tsconfig.json file. This file is essential for configuring how TypeScript compiles your code and helps maintain consistency across different environments.

• Leverage tsconfig.json for precise compilation control:
  The tsconfig.json file is the heart of your TypeScript configuration. Here, you can specify important options such as rootDir (where your source files live), outDir (where compiled JavaScript will be output), strict (to enable strict type-checking for safer code), and esModuleInterop (to improve compatibility with CommonJS modules). Customizing these settings tailors the TypeScript compiler to your project’s structure and requirements.

• Compile efficiently with npx tsc and watch mode:
  To convert your TypeScript files into JavaScript, use the npx tsc command. For a smoother development experience, you can enable watch mode with npx tsc -w, which automatically recompiles your code whenever you save changes. This immediate feedback loop helps you catch errors early and speeds up your workflow, making development more productive and less error-prone.

• Integrate Google TypeScript Style (GTS) for robust linting and standards:
  By applying the Google TypeScript Style (GTS) package, you instantly add a comprehensive linting setup and a set of opinionated defaults to your project. GTS enforces best practices and code consistency, reducing the need for manual configuration. This allows you to focus on writing quality code while ensuring your project adheres to widely accepted TypeScript standards from the start.

Before you begin working through this tutorial, make sure you have the following in place:

• Node.js (latest version):
  Ensure that you have the most up-to-date version of Node.js installed on your computer. Node.js is the JavaScript runtime that TypeScript builds upon, and having the latest version will help you avoid compatibility issues and take advantage of the newest features. If you need guidance on installing Node.js or setting up your local development environment, refer to our comprehensive guide: How to Install Node.js and Create a Local Development Environment.

• Basic familiarity with npm (Node Package Manager):
  You should be comfortable using npm, which is included automatically when you install Node.js. npm is essential for managing project dependencies, installing packages, and running scripts in your TypeScript project. If you are new to npm or want to deepen your understanding, we recommend reading: How To Use Node.js Modules with npm and package.json.

Having these prerequisites in place will ensure a smooth experience as you follow along with the steps in this tutorial. If you are missing either of these, please take a moment to review the linked resources before proceeding.

If you want to bootstrap everything in one go, you can use this one-liner to set up your TypeScript starter project with common tools:

npm init -y && npm i -D typescript ts-node eslint prettier @types/node && npx tsc --init

This command will initialize a new TypeScript project, install TypeScript and supporting developer tools, and generate a tsconfig.json file. It’s a fast way to create a new TypeScript project without missing any essentials.

Here are some of the most commonly used options you can configure in your tsconfig.json:

These options form the backbone of most TypeScript project setups and can be customized based on your needs.

At a Glance — Step 1

# One-liner to initialize a new TypeScript project
mkdir typescript-project && cd typescript-project
npm i -D typescript
npx tsc --init

Detailed Explanation

1. Create and enter your project directory:

   mkdir typescript-project
   cd typescript-project
   

2. Install TypeScript as a development dependency:

   npm i -D typescript
   

   The --save-dev flag ensures TypeScript is only required for development.

3. Initialize your TypeScript project:

   npx tsc --init
   

   This creates a tsconfig.json file with default configuration.

Open tsconfig.json in your editor to review and customize options:

nano tsconfig.json

Most options are commented out by default. For example:

{
  "compilerOptions": {
    /* Visit https://aka.ms/tsconfig.json to read more about this file */
    // ... (lots of commented-out options)
  }
}

Adjust configuration as needed, such as setting "outDir": "./build" to control where compiled files go.

Note: Step 3 will later replace many configurations with opinionated defaults, but this setup gets you started quickly.

At a Glance — Step 2

# Create your main TypeScript file
echo "const world = 'world';

export function hello(who: string = world): string {
  return \`Hello \${who}!\`;
}
" > index.ts

# Compile TypeScript project
npx tsc

Further Explanation

1. Write your TypeScript code in index.ts:

   typescript-project/index.ts

   const world = 'world';
   
   export function hello(who: string = world): string {
     return `Hello ${who}!`;
      }
   

2. Compile your code:

   npx tsc
   

   This generates compiled JavaScript in the build folder (if outDir is set).

Project structure after compilation

typescript-project/
├── build/
│   ├── index.js
│   └── index.js.map
├── index.ts
└── tsconfig.json

View the compiled output

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.hello = void 0;
const world = 'world';
function hello(who = world) {
    return `Hello ${who}!`;
}
exports.hello = hello;

Run the compiled code with Node

node build/index.js

Expected output

(no output, unless you invoke the function; add below for demo)

To get output, update your index.ts with:

console.log(hello());

Then recompile and run:

npx tsc
node build/index.js

Expected output:

Hello world!

Watch mode for automatic compilation

npx tsc -w

This recompiles your code on every save.

At a Glance — Step 3

# Install Google TypeScript Style (GTS)
npm install --save-dev gts

# Initialize GTS in your project
npx gts init

# Compile and check for lint errors
npm run compile
npm run check

Example: Linting Error and Fix

Bad Code (with lint error):

function sayhi(name:string){console.log('Hi, '+name)}

Run lint check:

npm run check

Output

index.ts:1:10: Missing space before function parentheses.
index.ts:1:20: Missing space after colon.
index.ts:1:47: Missing semicolon.
Found 3 errors.

Corrected code

function sayHi(name: string) {
  console.log('Hi, ' + name);
}

Explanation

GTS provides a style guide, linter, and code corrector in one. It bootstraps your project with opinionated defaults, including a tsconfig.json, ESLint config, and npm scripts:

• npm run compile — Compile your TypeScript code.
• npm run check — Check for lint/style errors.
• npm run fix — Auto-fix lint problems.

To customize rules, extend the ESLint config:

---
extends:
  - './node_modules/gts'

Key tsconfig.json settings

{
  "compilerOptions": {
    "rootDir": "./src",
    "outDir": "./build",
    "strict": true,
    "esModuleInterop": true,
    "module": "nodenext",
    "moduleResolution": "node",
    "skipLibCheck": true,
    "noUncheckedIndexedAccess": true
  }
}

tsconfig.json Rationale

• module: "nodenext" vs commonjs:
  Use "nodenext" for projects targeting ES modules in Node.js (Node 16+). Use "commonjs" for classic Node.js projects or older compatibility.
• moduleResolution: "node" vs "bundler":
  "node" mimics Node.js resolution logic, best for server-side and most projects.
  "bundler" is for front-end projects using tools like Vite or Webpack, which handle resolution differently.
• skipLibCheck:
  Set to true to speed up builds by skipping type checks on libraries in node_modules.
• noUncheckedIndexedAccess:
  Enforces safer access to arrays and objects by making index access return possibly undefined unless checked.

General Best Practices

• Organize source code in src/, output in build/ or dist/.
• Use camelCase for variables/functions, PascalCase for classes/types.
• Always enable "strict": true for robust type-checking.
• Use interfaces/types for clear object and function signatures.

TypeScript is commonly used in these scenarios:

Node.js and Express apps

Quickstart (Express)

npm i express @types/express @types/node

Installs Express plus TypeScript typings for Express and Node so the compiler recognizes framework APIs and Node globals during development.

// index.ts
import express from 'express';
const app = express();
app.get('/', (req, res) => res.send('Hello from Express + TypeScript!'));
app.listen(3000, () => console.log('Server running on http://localhost:3000'));

This defines a minimal HTTP server that handles GET / and listens on port 3000.

• Add to package.json:

"scripts": {
  "dev": "ts-node index.ts"
}

This dev script runs the app with ts-node, so you can iterate without a separate build step.

• Run the server:

npx ts-node index.ts
# or
npm run dev

If you see an “address already in use” error, change app.listen(3000) to another free port (for example, 3001) and rerun.

• Visit http://localhost:3000 to see the output. You should see “Hello from Express + TypeScript!” in your browser.

React applications

Quickstart (React)

npx create-react-app my-app --template typescript
# or with Vite:
npm create vite@latest my-app -- --template react-ts

Typed props example

type GreetingProps = { name: string };
const Greeting: React.FC<GreetingProps> = ({ name }) => (
  <div>Hello, {name}!</div>
);

Library/Package development

• Set "declaration": true in tsconfig.json to generate .d.ts files for consumers.

When setting up or working with TypeScript, beginners often run into a few common issues. Here are some errors you might encounter and how to fix them:

• Cannot find name ‘require’: This happens if you try to use require in a TypeScript file without Node.js types. Fix it by installing @types/node and ensuring "moduleResolution": "node" is set in your tsconfig.json.
• Unexpected token ‘export’: This occurs if your compiled JavaScript is using ES modules but Node.js expects CommonJS. Fix by setting "module": "commonjs" in tsconfig.json or running Node with --experimental-modules.
• Missing @types/node: If you see missing type errors for Node.js globals, install them with npm i -D @types/node.
• esModuleInterop issues: If imports don’t work as expected (for example with default vs. named imports), enable "esModuleInterop": true in your tsconfig.json.
• ts-node runtime errors: If ts-node fails with type errors, make sure your tsconfig.json is configured correctly, that you have the right version of TypeScript, and try running with npx ts-node --transpile-only if you only want to bypass type checking at runtime.

How do I initialize a TypeScript project?

You can initialize a new TypeScript project with:

npm init -y
npm i -D typescript
npx tsc --init

What is the purpose of tsconfig.json?

tsconfig.json configures how TypeScript compiles your code—options like target JavaScript version, module system, root directory, and output directory.

Do I need to install TypeScript globally or locally?

Installing locally (npm i -D typescript) is recommended so all team members use the same version. You can install globally if you need tsc everywhere.

How do I run TypeScript code without compiling every time?

Use ts-node, which runs .ts files directly:

npx ts-node index.ts

What’s the difference between tsc and ts-node?

• tsc: Compiles TypeScript into JavaScript files.
• ts-node: Runs TypeScript files directly without creating separate .js outputs.

Can I use TypeScript with frameworks like React or Express?

Yes. For React, you can scaffold a new project with:

npx create-react-app my-app --template typescript

For Express, install @types/express and use TypeScript for type safety in backend development.

Beyond traditional TypeScript projects, you can also use TypeScript to build powerful servers that interact directly with LLMs using the Model Context Protocol (MCP) TypeScript SDK. MCP is a standardized way to expose resources, tools, and prompts so that AI systems can consume them reliably.

Overview

The MCP TypeScript SDK makes it easy to:

• Create MCP servers that expose data as Resources
• Register Tools that perform actions or computations
• Define reusable Prompts for LLM workflows
• Use transports like stdio or Streamable HTTP to communicate with clients

This allows you to build TypeScript-powered servers that securely provide functionality to LLM-based applications.

Installation

Install the MCP SDK via npm:

npm install @modelcontextprotocol/sdk

Requires Node.js v18 or higher.

Quickstart Example

Here’s a simple MCP server that provides a calculator tool and a dynamic greeting resource:

import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

// Create an MCP server
const server = new McpServer({
    name: 'demo-server',
    version: '1.0.0'
});

// Register an addition tool
server.registerTool(
    'add',
    {
        title: 'Addition Tool',
        description: 'Add two numbers',
        inputSchema: { a: z.number(), b: z.number() }
    },
    async ({ a, b }) => ({
        content: [{ type: 'text', text: String(a + b) }]
    })
);

// Register a dynamic greeting resource
server.registerResource(
    'greeting',
    new ResourceTemplate('greeting://{name}', { list: undefined }),
    {
        title: 'Greeting Resource',
        description: 'Dynamic greeting generator'
    },
    async (uri, { name }) => ({
        contents: [
            {
                uri: uri.href,
                text: `Hello, ${name}!`
            }
        ]
    })
);

// Start transport via stdio
const transport = new StdioServerTransport();
await server.connect(transport);

Run and verify

npx ts-node server.ts

Expected output:

MCP server started and listening for requests via stdio...

Why Use MCP?

MCP treats servers like APIs for LLMs:

• Resources - Provide context or data (similar to GET endpoints).
• Tools - Perform actions (similar to POST endpoints).
• Prompts - Reusable templates for structured LLM interactions.

This approach lets you build AI-powered applications in TypeScript that are composable, testable, and standards-compliant.

For further documentation, see the official MCP docs and the TypeScript SDK repository.

This guide showed how to set up a new TypeScript project, configure tsconfig.json with modern best practices, compile and run code, and enforce code standards with Google TypeScript Style (GTS). You also learned how to structure Node.js/Express and React projects with TypeScript, and how to build an MCP server.

TypeScript’s adoption is growing rapidly (2024 Stack Overflow Developer Survey), and it is increasingly common in large-scale and AI-assisted development.

Continue learning:

• How to work with TypeScript in Visual Studio Code
• How to use TypeScript with React
• How to Use Classes in TypeScript
• How to Create Custom Types in TypeScript
• How to Use Interfaces in TypeScript

For more details on configuration, see the TypeScript tsconfig.json documentation.