{"id":22726873,"url":"https://github.com/svendotdev/node-backend-boilerplate","last_synced_at":"2026-04-09T12:02:33.866Z","repository":{"id":285163127,"uuid":"893266959","full_name":"SecretariatV/node-backend-boilerplate","owner":"SecretariatV","description":null,"archived":false,"fork":false,"pushed_at":"2025-02-15T20:36:54.000Z","size":140,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-30T00:15:27.733Z","etag":null,"topics":["backend","boilerplate","cookie","error-handling","eslint","express","google-authentication","logging","mongodb","node","passport","phone-authentication","prettier","smtp","swagger","twilio","typescript","winston"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SecretariatV.png","metadata":{},"created_at":"2024-11-24T00:57:46.000Z","updated_at":"2025-03-04T19:11:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/SecretariatV/node-backend-boilerplate","commit_stats":null,"previous_names":["secretariatv/node-backend-boilerplate"],"tags_count":null,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SecretariatV%2Fnode-backend-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SecretariatV%2Fnode-backend-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SecretariatV%2Fnode-backend-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SecretariatV%2Fnode-backend-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SecretariatV","download_url":"https://codeload.github.com/SecretariatV/node-backend-boilerplate/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246258874,"owners_count":20748573,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backend","boilerplate","cookie","error-handling","eslint","express","google-authentication","logging","mongodb","node","passport","phone-authentication","prettier","smtp","swagger","twilio","typescript","winston"],"created_at":"2024-12-10T17:07:17.532Z","updated_at":"2025-12-30T20:04:08.013Z","avatar_url":"https://github.com/SecretariatV.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# **Node backend boilerplate**\n\n[![Node.js Version](https://img.shields.io/badge/Node.js-%3E=20.17.0-brightgreen)](https://nodejs.org/) [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n## **Description**\n\nA comprehensive and professional Node.js backend boilerplate designed for building scalable and maintainable applications. This boilerplate features Google Authentication, Phone Code Authentication, logging, testing, and Git hooks for ensuring high code quality.\n\n---\n\n## **Table of Contents**\n\n1. [Features](#features)\n2. [Tech Stack](#tech-stack)\n3. [To-Do List](#to-do-list)\n4. [Getting Started](#getting-started)\n5. [Project Structure](#project-structure)\n6. [Authentication Setup](#authentication-setup)\n7. [Code Quality Automation](#code-quality-automation)\n8. [Configuration](#configuration)\n9. [Testing](#testing)\n10. [Contributing](#contributing)\n11. [License](#license)\n12. [Author](#author)\n\n---\n\n## **Features**\n\n- 🌟 **Modern technologies**: Node.js, TypeScript, Express.js\n- 🔒 **Authentication**:\n  - Google OAuth2 using Passport.js\n  - Local Email Authentication with JWT and password hashing\n  - Phone Code Authentication using Twilio\n- 📜 **Logging**: Integrated with Winston for structured loggin\n- 🛡️ **Security**: Helmet, CORS, and rate limiting for secure APIs\n- 🧪 **Testing**: Preconfigured with Vitest for unit and integration testing\n- 🚀 **Code Quality**:\n  - **Husky** for Git hooks\n  - **ESLint** and **Prettier** for linting and formatting\n- 📁 **Clean Folder Structure**: Scalable, modular, and maintainable folder structure\n- 🌐 **API Documentation**: Integrated Swagger UI for auto-generated, interactive API docs\n- ⚡ **Performance Optimization**: Follows best practices for fast API responses\n\n---\n\n## **Tech Stack**\n\n- **Node.js** (v20 or higher)\n- **Express.js**\n- **TypeScript**\n- **MongoDB** (or any other DB of your choice)\n- **Passport.js** (Google Authentication)\n- **Twilio** (Phone Code Authentication)\n- **Google SMTP** (Email Verification)\n- **Vitest** for testing\n- **Winston** for logging\n- **Husky** for Git hooks\n\n---\n\n## **To-Do List**\n\n### **Core Features**\n\n- [x] **Environment Setup**: Centralized environment variable configuration\n- [x] **Google Authentication**: OAuth 2.0 integration\n- [x] **Local Email Authentication**: JWT-based email and password login\n- [x] **Email Verification**: Google SMTL integration\n- [ ] **Phone Code Authentication**: Twilio-based OTP verification\n- [x] **Logging**: Winston for error and activity tracking\n- [x] **Error Handling**: Centralized error handling mechanism\n- [ ] **Testing Framework**: Vitest for reliable unit and integration testing\n- [ ] **Communicate with fe using session**: Implement session-based communication with `express-session`\n- [ ] **API Documentation**: Add Swagger UI\n\n### **Enhancements**\n\n- [ ] **Role-based Access Control**: RBAC for admin and user permissions\n- [ ] **API Rate Limiting**: Prevent abuse using `express-rate-limit`\n- [ ] **File Upload Support**: Enable file uploads with Multer\n- [ ] **Docker Support**: Containerize the application for deployment\n- [ ] **CI/CD Pipeline**: Automate testing and deployment with GitHub Actions\n- [x] **Custom Middleware**: Add reusable middleware for authentication and error handling\n\n---\n\n## **Getting Started**\n\n### **Prerequisites**\n\n1. Install [Node.js](https://nodejs.org/) (\u003e= 20.0.0)\n2. Install [MongoDB](https://www.mongodb.com/) or configure your preferred database.\n3. Set up a Google OAuth2 application via [Google Cloud Console](https://console.cloud.google.com/).\n4. Create a Twilio account and configure the messaging service.\n\n### **Installation**\n\n1. Clone the repository:\n   ```\n   git clone https://github.com/secretariatv/node-backend-boilerplate.git\n   cd node-backend-boilerplate\n   ```\n2. Install dependencies:\n   ```bash\n   pnpm i\n   ```\n3. Configure environment variables:\n\n   - Copy `.env.example` to `.env` and set up your values:\n     ```bash\n     cp .env.example .env\n     ```\n\n### **Run the Application**\n\n- Development mode:\n  ```bash\n  pnpm dev\n  ```\n- Production mode:\n  ```bash\n  pnpm start\n  ```\n\n---\n\n## **Project Structure**\n\n```plaintext\nnode-backend-boilerplate/\n├── src/\n├── ├── config/         # Configuration files (env, database, etc.)\n├── ├── controllers/    # Request handlers\n├── ├── middleware/     # Custom middleware\n├── ├── models/         # Database models\n├── ├── routes/         # API routes\n├── ├── services/       # Business logic and reusable services\n├── ├── utils/          # Utility functions\n├── ├── tests/          # Unit and integration tests\n├── ├── app.ts          # Express app setup\n├── ├── server.ts       # Entry point\n├── .env.example        # Example environment variables\n├── .eslint.config.mjs  # ESLint configuration\n├── .prettierrc         # Prettier configuration\n├── package.json        # Project metadata and dependencies\n├── vitest.config.ts    # Vitest configuration\n├── tsconfig.json       # TypeScript configuration\n├── README.md           # Documentation\n```\n\n---\n\n## **Authentication Setup**\n\n### **Google Authentication**\n\n1. **Set Up Google OAuth2 application**\n\n- Go to the [Google Cloud Console](https://console.cloud.google.com/).\n- Create a new project and enable the \"OAuth2.0 API\".\n- Set up an OAuth consent screen and create credentials for a Web Application.\n- Add authorized redirect URIs (e.g., `http://localhost:5000/auth/google/callback`).\n\n2. **Environment Variables**\n   Update your `.env` file with the following variables:\n\n   ```plaintext\n   GOOGLE_CLIENT_ID=\u003cYour Google Client ID\u003e\n   GOOGLE_CLIENT_SECRET=\u003cYour Google Client Secret\u003e\n   GOOGLE_CALLBACK_URL=http://localhost:5000/auth/google/callback\n   ```\n\n### **Phone Code Authentication**\n\n1. **Set Up Twilio Account**\n\n- Go to the [Twilio Console](https://www.twilio.com).\n- Create a Messaging Service and note the SID.\n\n2. **Environment Variables**\n   Update your `.env` file with the following variables:\n   ```plaintext\n   TWILIO_ACCOUNT_SID=\u003cYour Twilio Account SID\u003e\n   TWILIO_AUTH_TOKEN=\u003cYour Twilio Auth Token\u003e\n   TWILIO_PHONE_NUMBER=\u003cYour Twilio Phone Number\u003e\n   ```\n\n---\n\n## **Code Quality Automation**\n\nThis project uses **Husky** for Git hooks to enforce code quality ahd testing:\n\n```bash\npnpm test:style\n```\n\n### **Scripts**\n\n- `lint`: Runs ESLint\n- `format`: Runs Prettier\n\n---\n\n## **Configuration**\n\nRefer to `.env.example` for the full list of required environment variables.\n\n---\n\n## **Testing**\n\n- Run all tests:\n\n  ```bash\n  pnpm test\n  ```\n\n- Generate coverage report:\n\n  ```bash\n  pnpm test:coverage\n  ```\n\n---\n\n## **Contributing**\n\nWelcoome contributions! Please follow these steps:\n\n1. Fork the repository.\n2. Create a new feature branch:\n\n```bash\ngit checkout -b feature/your-feature-name\n```\n\n3. Commit your changes.\n4. Push the branch:\n\n```bash\ngit push origin feature/your-feature-name\n```\n\n5. Open a pull request.\n\n---\n\n### **License**\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n---\n\n### **Author**\n\n- **Name**: Oliver Boucher\n- **Email**: [Gmail](mailto:joshua.lee.f25@gmail.com)\n- **Portfolio**: [Portfolio]()\n- **GitHub**: [Github](https://github.com/secretariatv)\n- **Twitter**: [Twitter](https://x.com/ovb_corder)\n\nFeel free to reach out for any questions or feedback about this project!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsvendotdev%2Fnode-backend-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsvendotdev%2Fnode-backend-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsvendotdev%2Fnode-backend-boilerplate/lists"}