This post describes all the necessary steps to set up an Express.js server using Typescript. We’ll start our project from scratch, create an Express.js server using Vanilla Javascript, and then convert our project to support Typescript. Let’s dive in!
Technology stack used
npm–10.8.2node–20.15.1express.js–4.19.2typescript–5.5.3
Setting Up the Project with Express.js
In an empty folder of your choice, run the npm initializer with all default options selected by using the following command:
npm init --yes # or npm init -y
By using the --yes flag we ask npm to set the default answer to any question asked during setup. Remove the --yes flag to see the questions I am referring to.
We will be using a folder called server-project for this post. Running the previous command is the first step of our project, resulting in a package.json file with the following content:
{
"name": "server-project",
"version": "1.0.0",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC",
"description": ""
}
Now that we have initialized our project using npm let’s install Express.js:
npm install express@4.19.2
By doing so, Express.js will be added to the package.json file’s dependencies.
{
"name": "server-project",
"version": "1.0.0",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC",
"description": "",
"dependencies": {
"express": "^4.19.2"
}
}
The next step is to set up a basic server following Express’s documentation
Create a new file in your project folder, named index.js, and inside that file, add
const express = require('express');
const app = express();
const port = 3004;
app.get('/', (req, res) => {
res.send('Hello World!');
})
app.listen(port, () => {
console.log(`Example app listening on port ${port}`);
});
Excellent! Using node we get to see this baby up and running!
node index.jsExecuting this to your terminal will show you
Example app listening on port 3004Opening localhost:3004 to your browser, you will see our server’s response.
In any case, you get some kind of error like listen EADDRINUSE: address already in use :::3004 it means that you are running another application in the port 3004. To fix this, either change in the index.js file, this app’s port, to e.g 3001 or kill the other app you already are running on port 3004.
Installing Typescript
Now that we have successfully installed our Express.js server and we see that everything is working as expected, it’s time to add Typescript.
Kill the node script using Ctrl + C and install Typescript by running
npm install --save-dev typescript@5.5.3Typescript is stored as a development dependency because it is used only in the development phase of a project for transpiling TS code to Javascript. In production environments, browsers and servers are capable of interpreting and executing JavaScript, not Typescript code.
{
"name": "server-project",
"version": "1.0.0",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC",
"description": "",
"dependencies": {
"express": "^4.19.2"
},
"devDependencies": {
"typescript": "^5.5.3"
}
}
After installing Typescript to our project we need to initialize it by typing
npx tsc --init--init flag is used to initialize a TS project and create a tsconfig.json file with the default options set.
But what about tsc and npx? Where did these come from?
Understanding tsc and npx: Why do we use them?
tsc is the command line tool used by Typescript to compile code (tsc 👉 typescript compiler) into Javascript. It is a part of Typescript package, and it became available to our system when we installed Typescript.
npx on the other side is a package runner tool that came with npm. It was released from npm version 5.2.0. This tool is useful in cases where:
- We want to run a package without installing it
- We will be executing a package using different versions
- To avoid global installation of a package
Ok, sure, but in our case, since we have Typescript installed in our local project folder, and because of this, we also have tsc installed, then why not just use tsc --init? Right? Why do we want to use npx to run tsc?
Just using tsc might use a global version of Typescipt and not the local one
That question killed some of my brain cells 🧠 before figuring it out 😅. Just using tsc --init may use a global version of Typescript installed on your computer. Using npx tsc --init instead will make sure that you are using the local version of tsc package. This way, you will avoid any surprises because of different package versions. 🥳
After successfully executing npx tsc --init you will see a tsconfig.json file created with the following content
{
"compilerOptions": {
/* Visit https://aka.ms/tsconfig to read more about this file */
/* Projects */
// "incremental": true, /* Save .tsbuildinfo files to allow for incremental ompilation of projects. */
// "composite": true, /* Enable constraints that allow a TypeScript project to be used with project references. */
// "tsBuildInfoFile": "./.tsbuildinfo", /* Specify the path to .tsbuildinfo incremental compilation file. */
// "disableSourceOfProjectReferenceRedirect": true, /* Disable preferring source files instead of declaration files when referencing composite projects. */
// "disableSolutionSearching": true, /* Opt a project out of multi-project reference checking when editing. */
// "disableReferencedProjectLoad": true, /* Reduce the number of projects loaded automatically by TypeScript. */
/* Language and Environment */
"target": "es2016", /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
// "lib": [], /* Specify a set of bundled library declaration files that describe the target runtime environment. */
// "jsx": "preserve", /* Specify what JSX code is generated. */
// "experimentalDecorators": true, /* Enable experimental support for legacy experimental decorators. */
// "emitDecoratorMetadata": true, /* Emit design-type metadata for decorated declarations in source files. */
// "jsxFactory": "", /* Specify the JSX factory function used when targeting React JSX emit, e.g. 'React.createElement' or 'h'. */
// "jsxFragmentFactory": "", /* Specify the JSX Fragment reference used for fragments when targeting React JSX emit e.g. 'React.Fragment' or 'Fragment'. */
// "jsxImportSource": "", /* Specify module specifier used to import the JSX factory functions when using 'jsx: react-jsx*'. */
// "reactNamespace": "", /* Specify the object invoked for 'createElement'. This only applies when targeting 'react' JSX emit. */
// "noLib": true, /* Disable including any library files, including the default lib.d.ts. */
// "useDefineForClassFields": true, /* Emit ECMAScript-standard-compliant class fields. */
// "moduleDetection": "auto", /* Control what method is used to detect module-format JS files. */
/* Modules */
"module": "commonjs", /* Specify what module code is generated. */
// "rootDir": "./", /* Specify the root folder within your source files. */
// "moduleResolution": "node10", /* Specify how TypeScript looks up a file from a given module specifier. */
// "baseUrl": "./", /* Specify the base directory to resolve non-relative module names. */
// "paths": {}, /* Specify a set of entries that re-map imports to additional lookup locations. */
// "rootDirs": [], /* Allow multiple folders to be treated as one when resolving modules. */
// "typeRoots": [], /* Specify multiple folders that act like './node_modules/@types'. */
// "types": [], /* Specify type package names to be included without being referenced in a source file. */
// "allowUmdGlobalAccess": true, /* Allow accessing UMD globals from modules. */
// "moduleSuffixes": [], /* List of file name suffixes to search when resolving a module. */
// "allowImportingTsExtensions": true, /* Allow imports to include TypeScript file extensions. Requires '--moduleResolution bundler' and either '--noEmit' or '--emitDeclarationOnly' to be set. */
// "resolvePackageJsonExports": true, /* Use the package.json 'exports' field when resolving package imports. */
// "resolvePackageJsonImports": true, /* Use the package.json 'imports' field when resolving imports. */
// "customConditions": [], /* Conditions to set in addition to the resolver-specific defaults when resolving imports. */
// "resolveJsonModule": true, /* Enable importing .json files. */
// "allowArbitraryExtensions": true, /* Enable importing files with any extension, provided a declaration file is present. */
// "noResolve": true, /* Disallow 'import's, 'require's or '<reference>'s from expanding the number of files TypeScript should add to a project. */
/* JavaScript Support */
// "allowJs": true, /* Allow JavaScript files to be a part of your program. Use the 'checkJS' option to get errors from these files. */
// "checkJs": true, /* Enable error reporting in type-checked JavaScript files. */
// "maxNodeModuleJsDepth": 1, /* Specify the maximum folder depth used for checking JavaScript files from 'node_modules'. Only applicable with 'allowJs'. */
/* Emit */
// "declaration": true, /* Generate .d.ts files from TypeScript and JavaScript files in your project. */
// "declarationMap": true, /* Create sourcemaps for d.ts files. */
// "emitDeclarationOnly": true, /* Only output d.ts files and not JavaScript files. */
// "sourceMap": true, /* Create source map files for emitted JavaScript files. */
// "inlineSourceMap": true, /* Include sourcemap files inside the emitted JavaScript. */
// "outFile": "./", /* Specify a file that bundles all outputs into one JavaScript file. If 'declaration' is true, also designates a file that bundles all .d.ts output. */
// "outDir": "./", /* Specify an output folder for all emitted files. */
// "removeComments": true, /* Disable emitting comments. */
// "noEmit": true, /* Disable emitting files from a compilation. */
// "importHelpers": true, /* Allow importing helper functions from tslib once per project, instead of including them per-file. */
// "downlevelIteration": true, /* Emit more compliant, but verbose and less performant JavaScript for iteration. */
// "sourceRoot": "", /* Specify the root path for debuggers to find the reference source code. */
// "mapRoot": "", /* Specify the location where debugger should locate map files instead of generated locations. */
// "inlineSources": true, /* Include source code in the sourcemaps inside the emitted JavaScript. */
// "emitBOM": true, /* Emit a UTF-8 Byte Order Mark (BOM) in the beginning of output files. */
// "newLine": "crlf", /* Set the newline character for emitting files. */
// "stripInternal": true, /* Disable emitting declarations that have '@internal' in their JSDoc comments. */
// "noEmitHelpers": true, /* Disable generating custom helper functions like '__extends' in compiled output. */
// "noEmitOnError": true, /* Disable emitting files if any type checking errors are reported. */
// "preserveConstEnums": true, /* Disable erasing 'const enum' declarations in generated code. */
// "declarationDir": "./", /* Specify the output directory for generated declaration files. */
/* Interop Constraints */
// "isolatedModules": true, /* Ensure that each file can be safely transpiled without relying on other imports. */
// "verbatimModuleSyntax": true, /* Do not transform or elide any imports or exports not marked as type-only, ensuring they are written in the output file's format based on the 'module' setting. */
// "isolatedDeclarations": true, /* Require sufficient annotation on exports so other tools can trivially generate declaration files. */
// "allowSyntheticDefaultImports": true, /* Allow 'import x from y' when a module doesn't have a default export. */
"esModuleInterop": true, /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
// "preserveSymlinks": true, /* Disable resolving symlinks to their realpath. This correlates to the same flag in node. */
"forceConsistentCasingInFileNames": true, /* Ensure that casing is correct in imports. */
/* Type Checking */
"strict": true, /* Enable all strict type-checking options. */
// "noImplicitAny": true, /* Enable error reporting for expressions and declarations with an implied 'any' type. */
// "strictNullChecks": true, /* When type checking, take into account 'null' and 'undefined'. */
// "strictFunctionTypes": true, /* When assigning functions, check to ensure parameters and the return values are subtype-compatible. */
// "strictBindCallApply": true, /* Check that the arguments for 'bind', 'call', and 'apply' methods match the original function. */
// "strictPropertyInitialization": true, /* Check for class properties that are declared but not set in the constructor. */
// "noImplicitThis": true, /* Enable error reporting when 'this' is given the type 'any'. */
// "useUnknownInCatchVariables": true, /* Default catch clause variables as 'unknown' instead of 'any'. */
// "alwaysStrict": true, /* Ensure 'use strict' is always emitted. */
// "noUnusedLocals": true, /* Enable error reporting when local variables aren't read. */
// "noUnusedParameters": true, /* Raise an error when a function parameter isn't read. */
// "exactOptionalPropertyTypes": true, /* Interpret optional property types as written, rather than adding 'undefined'. */
// "noImplicitReturns": true, /* Enable error reporting for codepaths that do not explicitly return in a function. */
// "noFallthroughCasesInSwitch": true, /* Enable error reporting for fallthrough cases in switch statements. */
// "noUncheckedIndexedAccess": true, /* Add 'undefined' to a type when accessed using an index. */
// "noImplicitOverride": true, /* Ensure overriding members in derived classes are marked with an override modifier. */
// "noPropertyAccessFromIndexSignature": true, /* Enforces using indexed accessors for keys declared using an indexed type. */
// "allowUnusedLabels": true, /* Disable error reporting for unused labels. */
// "allowUnreachableCode": true, /* Disable error reporting for unreachable code. */
/* Completeness */
// "skipDefaultLibCheck": true, /* Skip type checking .d.ts files that are included with TypeScript. */
"skipLibCheck": true /* Skip type checking all .d.ts files. */
}
}
Refactoring JavaScript to TypeScript
Now that we have successfully installed and initialized Typescript we need to start writing some Typescript to have fun.
First of all let’s rename our index.js file to index.ts. If we don’t do that and we run our tsc compiler we will see an error
error TS18003: No inputs were found in config file 'server-project/tsconfig.json'. Specified 'include' paths were '["**/*"]' and 'exclude' paths were '[]'.
because we have no .ts files in our project.
Make sense right? After all we need at least .ts one file to start our TS journey. Ok now that we have renamed it, lets, out of curiosity, run npx tsc and see what happens. By running this command, I get the following errors
index.ts:1:17 - error TS2580: Cannot find name 'require'. Do you need to install type definitions for node? Try `npm i --save-dev @types/node`.
1 const express = require('express');
~~~~~~~
index.ts:6:15 - error TS7006: Parameter 'req' implicitly has an 'any' type.
6 app.get('/', (req, res) => {
~~~
index.ts:6:20 - error TS7006: Parameter 'res' implicitly has an 'any' type.
6 app.get('/', (req, res) => {
~~~
It seems the compiler is unable to successfully convert our .ts file to .js due to three issues. We need to address these issues one at a time. A guide is available that describes each error in detail, including their causes and solutions. Feel free to check it out if you want to learn more.
After dealing with all the necessary problems, the updated .ts file should look something like
import express, { Express, Request, Response } from 'express';
const app: Express = express();
const port = 3004;
app.get('/', (req: Request, res: Response) => {
res.send('Hello World!');
})
app.listen(port, () => {
console.log(`Example app listening on port ${port}`);
});
Now that we have everything fixed let’s run npx tsc to see if there is anything left. Running this command showed nothing in my terminal. Which is a good sign. To see the compilation results though, I need to make two small tweaks.
Configure TypeScript to create a new folder for all compiled files by using the outDir compiler option.
{
"compilerOptions": {
// ....
"outDir": "./dist",
// Specify an output folder for all emitted files.
}
}
Rename the package.json main file and add a compilation Script
{
"name": "server-project",
"version": "1.0.0",
"main": "dist/index.js",
"scripts": {
"start": "npx tsc && node dist/index.js",
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC",
"description": "",
"dependencies": {
"express": "^4.19.2"
},
"devDependencies": {
"@types/express": "^4.17.21",
"@types/node": "^22.1.0",
"typescript": "^5.5.4"
}
}
Superb! Now we have everything we need. What’s next? A victory dance! When you run npm start, your terminal will display “Example app listening on port 3004,” which means we did it!
Example app listening on port 3004
