One of the most time-consuming tasks when starting a project from scratch is the creation of the initial scaffolding, the folder structure, the configuration of linters and formatters, the configuration of tests, etc. They are almost always the same tasks, changing certain details to adapt them to the team's development conventions. On the other hand, there are also common tasks in most projects, such as for example, authentication and/or authorization and user management, the definition of the OpenAPI specification, creation of a common logger, etc.
Because of this, I decided to create a base template of a REST API created with NodeJS, using Ts.ED as the base framework and TypeScript as the programming language. This template tries to follow the principles of Domain Driven Design and implements a Clean Architecture/Hexagonal Architecture to try to rely as little as possible on the infrastructure and the framework while keeping in mind at all times the language and the needs of the business logic.
📣 This is an opinionated template. The architecture of the code base and the configuration of the different tools used has been based on best practices and personal preferences.
🧰 Technologies and tools used
- Built using Typescript
- Built using Express Framework: Fast, unopinionated, minimalist web framework for node.
- Built using Prisma: Next-generation ORM for Node.js & TypeScript | PostgreSQL, MySQL, MariaDB, SQL Server, SQLite & MongoDB
- Built using Ts.ED: Ts.ED is a Node.js Framework on top of Express/Koa.js. Written in Typescript, it helps you build your server-side application easily and quickly. If you want to start a complete out-of-the-box project or fully customize it yourself, Ts.ED will guide you there! This framework is extremely powerful and easy to use. It is really worth it.
- JWT authentication and role-based authorization using custom middleware
- OpenAPI definition
- Fully configured logger with Winston and Morgan
- Unit, Integration, and E2E tests using Jest and Supertest
- Linting with ESLint
- Formatting with Prettier
- Spell check
- Git hooks with Husky and lint-staged
- Containerized using Docker and Docker Compose
- Path aliases support
- Commit messages must meet the format of the conventional commit
- GitHub Actions
- Makefile as the project entry point
- A lot of emojis 🛸
🚀 Quick start
-
Create a project from this template on GitHub or clone it directly
git clone https://github.com/borjapazr/express-typescript-skeleton.git
-
Install dependencies
npm install
-
Start and configure the database using
Prisma
make start/db # This step will create a Docker container with the database (MariaDB). It may take some time, so be patient before running the next command.
npm run prisma:generate
npm run prisma:migrate
npm run prisma:seed
-
Start project in development mode:
npm run dev
-
Open the following URL to interact with the API using Swagger UI:
http://localhost:5000/api/docs # Sample username and password: janedoe / 123456
-
Or, if you prefer, you can access the demo version.
https://express-typescript-skeleton.marsmachine.space/api/docs
# Sample username and password: janedoe / 123456
🤝 Contributing
Just fork and open a pull request. All contributions are welcome 🤗
GitHub repository: https://github.com/borjapazr/express-typescript-skeleton
Thank you for taking the time to read this post. You rock! 🤘