TypeScript Project Setup: A Step-by-Step Guide (init)

By /

TypeScript Project Setup: A Step-by-Step Guide (init)

This guide provides a comprehensive, step-by-step walkthrough of setting up a new TypeScript project from scratch. We’ll cover initializing the project, configuring TypeScript, setting up linting and formatting, and explaining the role of essential files. This is your foundational guide to starting any TypeScript endeavor.

Prerequisites:

  • Node.js and npm (or yarn): Make sure you have Node.js (which includes npm) installed. You can download it from nodejs.org. Yarn is an alternative package manager and can be installed with npm install -g yarn. This guide will use npm, but you can easily adapt the commands to use yarn.
  • A Code Editor: VS Code is highly recommended, but any text editor will work. VS Code has excellent TypeScript support built-in.

Step 1: Create the Project Directory

First, create a new directory for your project and navigate into it using your terminal or command prompt:

bash
mkdir my-typescript-project
cd my-typescript-project

Replace my-typescript-project with your desired project name.

Step 2: Initialize a Node.js Project

Initialize a new Node.js project using npm init. This command creates a package.json file, which will hold metadata about your project and its dependencies.

bash
npm init -y

The -y flag automatically accepts all default options. You can omit it and answer the prompts if you want to customize the initial settings.

Step 3: Install TypeScript

Install TypeScript as a development dependency:

bash
npm install typescript --save-dev

The --save-dev flag adds TypeScript to the devDependencies section of your package.json. This indicates that TypeScript is only needed during development, not in production.

Step 4: Create a tsconfig.json File

The tsconfig.json file is the heart of your TypeScript configuration. It tells the TypeScript compiler how to compile your code. Create it with:

bash
npx tsc --init

This command generates a tsconfig.json file with many commented-out options. Let’s break down the most important ones and create a basic, functional configuration:

json
{
"compilerOptions": {
"target": "es2016", // Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019', 'ES2020', 'ES2021', or 'ESNEXT'.
"module": "commonjs", // Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', 'es2020', or 'ESNext'.
"strict": true, // Enable all strict type-checking options.
"esModuleInterop": true, // Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'.
"skipLibCheck": true, // Skip type checking of declaration files.
"forceConsistentCasingInFileNames": true, // Disallow inconsistently-cased references to the same file.
"outDir": "./dist", // Redirect output structure to the directory.
"rootDir": "./src", // Specify the root directory of input files. Use to control the output directory structure with --outDir.
"sourceMap": true // Generates corresponding '.map' file. Great for debugging.
},
"include": ["src/**/*"], // Specifies an array of filenames or patterns to include in the program.
"exclude": ["node_modules"] // Specifies an array of filenames or patterns that should be skipped when resolving include.
}

Explanation of Key Options:

  • target: Specifies the JavaScript version your TypeScript code will be compiled to. es2016 is a good, modern choice.
  • module: Defines how your modules will be structured (CommonJS is common for Node.js).
  • strict: Enables a set of strict type-checking rules, leading to more robust code. Highly recommended.
  • esModuleInterop: Helps with compatibility between different module systems.
  • skipLibCheck: Speeds up compilation by skipping type-checking of declaration files (usually in node_modules).
  • forceConsistentCasingInFileNames: Prevents errors caused by inconsistent casing in file names.
  • outDir: Where the compiled JavaScript files will be placed.
  • rootDir: The root of your TypeScript source files.
  • sourceMap: Generates source maps, which are crucial for debugging TypeScript code in the browser or Node.js. They map the compiled JavaScript back to your original TypeScript.
  • include: Specifies which files to include in the compilation. src/**/* means all files within the src directory and its subdirectories.
  • exclude: Specifies files or directories to exclude. We exclude node_modules because it contains third-party libraries.

Step 5: Create a Source Directory

Create a directory named src to hold your TypeScript source files:

bash
mkdir src

Step 6: Create Your First TypeScript File

Create a file named index.ts inside the src directory:

bash
touch src/index.ts

Add some simple TypeScript code to index.ts:

``typescript
// src/index.ts
function greet(name: string): string {
returnHello, ${name}!`;
}

console.log(greet(“World”));
“`

Step 7: Compile Your Code

Compile your TypeScript code using the TypeScript compiler:

bash
npx tsc

This will compile src/index.ts and output dist/index.js and dist/index.js.map (the source map) based on your tsconfig.json settings.

Step 8: Run Your Compiled Code

Run the compiled JavaScript code using Node.js:

bash
node dist/index.js

You should see “Hello, World!” printed in your terminal.

Step 9: (Optional but Recommended) Add Linting and Formatting (ESLint and Prettier)

Linting (ESLint) and formatting (Prettier) help maintain code quality and consistency.

  • Install Dependencies:

    bash
    npm install eslint prettier @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint-config-prettier --save-dev

  • Create .eslintrc.js:

    “`javascript
    // .eslintrc.js
    module.exports = {
    parser: ‘@typescript-eslint/parser’,
    plugins: [‘@typescript-eslint’],
    extends: [
    ‘eslint:recommended’,
    ‘plugin:@typescript-eslint/recommended’,
    ‘prettier’, // Make sure ‘prettier’ is last to override ESLint formatting rules
    ],
    rules: {
    // Add any custom rules here
    },
    };

    “`

  • Create .prettierrc.js (optional, for custom Prettier configuration):

    javascript
    // .prettierrc.js
    module.exports = {
    semi: true,
    trailingComma: 'all',
    singleQuote: true,
    printWidth: 80,
    tabWidth: 2,
    };
    You can adapt the rules inside this file to suit the code style you wish to follow.

  • Add scripts to package.json:

    json
    // package.json
    {
    "scripts": {
    "build": "tsc",
    "lint": "eslint . --ext .ts",
    "format": "prettier --write \"src/**/*.ts\"",
    "start": "node dist/index.js" // Add a convenient start script
    },
    // ... other configurations ...
    }
    * Run Linting and Formatting:

    • npm run lint: Checks your code for errors and style issues.
    • npm run format: Automatically formats your code.
    • npm run build: Build your TypeScript Code.
    • npm run start: A convenient way to build and run your code.

Step 10: (Optional) Set up a Watcher

To automatically recompile your code whenever you save a file, you can use the --watch flag with the TypeScript compiler:

bash
npx tsc --watch

Or, you can add a watch script to your package.json:

json
{
"scripts": {
"build": "tsc",
"watch": "tsc --watch",
"lint": "eslint . --ext .ts",
"format": "prettier --write \"src/**/*.ts\"",
"start": "node dist/index.js"
},
// ... other configurations
}

Now, running npm run watch will start the compiler in watch mode.

Conclusion:

This step-by-step guide provides a solid foundation for setting up a TypeScript project. You’ve learned how to initialize the project, configure TypeScript, set up linting and formatting, and compile your code. From here, you can expand your project by adding more files, libraries, and features. Remember to consult the official TypeScript documentation (https://www.typescriptlang.org/) and the documentation for ESLint and Prettier for more advanced configurations and options. Good luck!

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top