A complete template for building RESTful API services with Express (Node.js) and TypeScript
- Express for rapid Node.js web app development
- TypeScript for type checking and other tooling for JavaScript
- Express Handlebars for view rendering
- Dotenv for storing app configuration in the environment
- Prettier for enforcing consistent code style
- ESLint for linting, i.e., spotting problematic patterns in the TS codebase
- Jest for testing the TS codebase
- SuperTest for HTTP integration tests
This project also includes some initial configuration for the included tooling along with some example code.
This project uses Yarn instead of npm to manage dependencies and run package scripts. To install Yarn, first make sure you have npm installed; npm comes bundled with Node.js when you install it on your system.
Once npm is installed, run the following to install Yarn:
npm install --global yarnTo clone the repo, run the following on your system:
git clone https://github.com/magic-ike/express-ts-boilerplate
cd express-ts-boilerplate
yarnRun the following to serve the app locally in development mode:
yarn devHere, you're using Yarn to run the dev script defined in the package.json file. Refer to the Scripts section to view the full list of package scripts available out of the box.
First, remember to configure the package.json file for your new project.
Then, if necessary, create a .env file at the root of the project to declare, as key-value pairs, any environment varables your app will need to run. As you update your .env file, your .env.example file should also be updated to look the same but with placeholder values (e.g., XXX) substituted for the real values. Also, remember to never commit the .env file to version control (the file will already be included in the project's .gitignore file, which will prevent this from happening).
Before adding your own code, refer to the Project Structure section as it explains which code should go where.
| Script | Description |
|---|---|
start |
serves the app in production mode (from the dist/ folder); will throw an error if the dist/ folder doesn't exist, which is usually due to the app not yet being transpiled with the build script |
dev |
serves the app in development mode (from the src/ folder) |
build |
transpiles the app from the src/ folder to the dist/ folder (specifically, it transpiles the TypeScript files to ES2016 files then copies over the rest of the files) |
lint |
lints all the TypeScript files in the project |
lint:fix |
lints all the TypeScript files in the project and automatically fixes issues wherever possible |
test |
runs all the tests in the project |
test:coverage |
runs all the tests in the project and collects and reports all the test coverage information in the output |
This project's structure is based on the Model-view–controller (MVC) design pattern. This pattern was chosen because it makes it easy to separate the responsibilities of the different parts of the app, thus making the project easier to maintain as it scales.
| File/folder | Responsibility |
|---|---|
| dist/ | should contain the production build (the transpiled source code) of the app; the contents of this folder are generated by the build script and you should never edit them directly |
| src/ | should contain the source code of the project which you will be editing directly |
| src/@types/ | should contain any custom TypeScript type definitions |
| src/config/ | should contain the app configuration loaded from the environment variables, such as API keys and database connection strings |
| src/controllers/ | should contain the controllers; the controllers get incoming requests from the routes, interact with the models to process and retrieve data, render and serve the views, and serve all other HTTP responses |
| src/interfaces/ | should contain any custom TypeScript interfaces |
| src/middleware/ | should contain any custom middleware; middleware is used to preprocess incoming requests |
| src/models/ | should contain any models; the models represent the data in a database and implement all the business logic for handling this data |
| src/public/ | should contain the static files served by the app such as style sheets, images, and JavaScript files |
| src/routes/ | should contain the routes; the routes receive incoming requests and pass them along to the controllers |
| src/utils/ | should contain any utility code that should be shared across the app |
| src/views/ | should contain the views, which get rendered by the controllers |
| tests/ | should contain the tests you'll write for your code |
| .env | should be the file where you declare environment variables for storing app configuration; you'll be creating this file yourself and it should never be committed to version control |
| .env.example | should be the file where you use placeholder values to indicate the environment variables declared in .env without actually redeclaring them and committing them to version control |
| misc | most of the other files in the root directory of the project are related to project configuration (different from app configuration) and will already have some initial setup; you'll most likely be changing this configuration as your project evolves |