https://github.com/cristiancosta/node-ts-jwt
JWT authentication service made with Typescript, Node.js, Express and more.
https://github.com/cristiancosta/node-ts-jwt
bcryptjs eslint express husky jest jwt mysql nodejs prettier supertest swagger testcontainers typeorm typescript
Last synced: 5 months ago
JSON representation
JWT authentication service made with Typescript, Node.js, Express and more.
- Host: GitHub
- URL: https://github.com/cristiancosta/node-ts-jwt
- Owner: cristiancosta
- License: mit
- Created: 2025-06-25T16:14:52.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-08-26T11:55:12.000Z (10 months ago)
- Last Synced: 2025-08-26T13:19:05.633Z (10 months ago)
- Topics: bcryptjs, eslint, express, husky, jest, jwt, mysql, nodejs, prettier, supertest, swagger, testcontainers, typeorm, typescript
- Language: TypeScript
- Homepage:
- Size: 1.55 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Node TS JWT
## 🧰 Stack
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
[](https://expressjs.com/)
[](https://jwt.io/)
[](https://typeorm.io/)
[](https://www.mysql.com/)
[](https://swagger.io/)
[](https://jestjs.io/)
[](https://testcontainers.com/)
[](https://typicode.github.io/husky/)
[](https://github.com/visionmedia/supertest)
[](https://prettier.io/)
[](https://eslint.org/)
---
## 🔐 Introduction
This is a REST API built with **TypeScript**, **Node.js** and **Express** that implements secure authentication using **JSON Web Tokens (JWT)**. It's a great base for systems that require login, user management, and access control via tokens.
Features include:
- 🔒 Authentication with **Access Token** and **Refresh Token**.
- 📖 Interactive API documentation via **Swagger UI**.
- 🧪 Real **MySQL** integration testing using **Testcontainers**.
- ✨ **ESLint** + **Prettier** + **Husky** for code quality enforcement.
- 🔁 **GitHub Actions** for automated CI/CD.
---
## 📁 Project Structure
```
├── .github/
├── .husky/
├── .vscode/ # Debuggers and workspace configuration.
├── src/
| ├── controllers/ # Endpoint logic.
| ├── errors/ # Custom error classes.
| ├── middlewares/ # Auth, error handling, swagger auth.
| ├── models/ # Typeorm models.
| ├── repositories/ # Data access abstraction.
| ├── routes/ # Route definitions.
| ├── services/ # Business logic.
| ├── types/ # Data structure definitions.
| ├── utils/ # Reusable functions.
| ├── app.ts # Express app configuration.
| ├── configuration.ts # .env configuration entry point.
| ├── data-source.ts # Typeorm configuration.
| ├── server.ts # Entry point.
| └── swagger.ts # Swagger configuration.
├── test/ # Unit and integration tests using jest, supertest and testcontainers.
├── .gitignore # Default gitignore file provided by GitHub.
├── .prettierrc # Prettier configuration file.
├── eslint.config.mjs # ESLint configuration file.
├── jest.config.ts # Jest configuration file.
├── LICENSE # MIT License.
├── package-lock.json # Exact project dependencies tree.
├── package.json # Project dependencies, scripts and more stuff.
├── README.md # Current file.
├── tsconfig.eslint.json # ESLint typescript config file.
└── tsconfig.json # Project typescript config.
```
---
## 🚀 Quick Installation
```bash
git clone https://github.com/cristiancosta/node-ts-jwt.git
cd node-ts-jwt
npm install
```
Then create a `.env` file in the project root with the following content:
```env
DB_HOST=localhost
DB_USERNAME=root
DB_PASSWORD=root
DB_NAME=nodejwt
DB_PORT=3306
SERVER_PORT=8081
JWT_SECRET=mysecret
JWT_ACCESS_TOKEN_DURATION=2 hours
JWT_REFRESH_TOKEN_DURATION=2 days
SWAGGER_USERNAME=admin
SWAGGER_PASSWORD=admin
```
Make sure you have a MySQL database up and running. In my case, I use Docker since it's the easiest way:
```bash
$ docker run -p 3306:3306 -e MYSQL_ROOT_USER=root -e MYSQL_ROOT_PASSWORD=root -d mysql
```
Log into the container and create the database:
```bash
$ docker exec -it mysql -uroot -proot
$ CREATE DATABASE nodejwt;
```
Start the server:
```bash
npm start
```
📍 The API will be available at: `http://localhost:8081`
---
## 📚 Interactive Documentation
You can explore and test all endpoints using Swagger UI:
🔗 [http://localhost:8081/api-docs/](http://localhost:8081/api-docs/)
Basic Auth required:
- **Username:** `admin`
- **Password:** `admin`
You can change Swagger credentials on `.env` file.
---
## 🧪 Testing with Testcontainers
This project uses **Testcontainers** to spin up a real MySQL instance during tests. This ensures:
- A test environment **identical to production**.
- No fragile mocks.
- Automatic container cleanup.
Run tests:
```bash
npm test
```
---
## ✅ Husky + Pre-commit hooks
The project uses **Husky** to automatically run the following before each commit:
```bash
npx lint-staged # Runs ESLint + Prettier
```
---
## ⚙️ GitHub Actions CI
The project runs automated tests and perform building process on Node.js 20.x and 22.x via GitHub Actions.
---
## 🛠️ Useful Scripts
| Command | Description |
| ------------------ | ------------------------------------------------------------- |
| `npm start` | Starts the server with Nodemon |
| `npm test` | Runs all tests using Jest + Testcontainers |
| `npm run lint` | Lints the code using ESLint |
| `npm run lint:fix` | Lints and auto-fixes issues |
| `npm run format` | Formats code with Prettier |
| `npm run build` | Builds the project with tsc |
| `npm run serve` | Starts the server with Node (previous build script execution) |
---
## 🤝 Contributing
Contributions are welcome!
1. Fork the repo.
2. Create a new branch.
3. Submit a Pull Request.
4. Make sure lint and tests pass.
📩 For direct contact: **cristiancosta1991@gmail.com**
🌟 Found it useful? Give the project a ⭐ on GitHub!
[https://github.com/cristiancosta/node-ts-jwt](https://github.com/cristiancosta/node-ts-jwt)
---
## ☕ Donations
If you'd like to support this project, feel free to donate a coffee.
[](https://ko-fi.com/C0C81GYN0D)
---
## 📝 License
MIT © [Cristian Costa](mailto:cristiancosta1991@gmail.com)