{"id":25860083,"url":"https://github.com/hanlunwang/express-backend-template","last_synced_at":"2026-01-24T20:54:42.454Z","repository":{"id":280025475,"uuid":"940686052","full_name":"HanlunWang/express-backend-template","owner":"HanlunWang","description":"A robust Express.js backend template with enterprise-grade features, designed for scalable and maintainable Node.js applications.","archived":false,"fork":false,"pushed_at":"2025-02-28T21:17:15.000Z","size":105,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-28T22:59:53.377Z","etag":null,"topics":["backend","expressjs","javascript","nodejs","template","typescript"],"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/HanlunWang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-28T16:01:24.000Z","updated_at":"2025-02-28T21:17:19.000Z","dependencies_parsed_at":"2025-02-28T23:00:52.090Z","dependency_job_id":"06c84ee1-9c2a-4d7c-a439-a42cb35ce858","html_url":"https://github.com/HanlunWang/express-backend-template","commit_stats":null,"previous_names":["hanlunwang/express-backend-template"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HanlunWang%2Fexpress-backend-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HanlunWang%2Fexpress-backend-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HanlunWang%2Fexpress-backend-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HanlunWang%2Fexpress-backend-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HanlunWang","download_url":"https://codeload.github.com/HanlunWang/express-backend-template/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241430317,"owners_count":19961635,"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","expressjs","javascript","nodejs","template","typescript"],"created_at":"2025-03-01T21:53:16.227Z","updated_at":"2026-01-24T20:54:42.417Z","avatar_url":"https://github.com/HanlunWang.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 Express Backend Template\n\nA robust Express.js backend template with enterprise-grade features, designed for scalable and maintainable Node.js applications.\n\n![Node.js](https://img.shields.io/badge/Node.js-v14+-green.svg)\n![Express](https://img.shields.io/badge/Express-v4-blue.svg)\n![TypeScript](https://img.shields.io/badge/TypeScript-v4-blue.svg)\n![License](https://img.shields.io/badge/License-MIT-yellow.svg)\n\n## ✨ Features\n\n- **🔷 TypeScript** - Write type-safe code with enhanced developer experience and fewer runtime errors\n- **🔐 Authentication System** - Secure JWT-based authentication with role-based access control (RBAC)\n- **📚 API Documentation** - Automatic Swagger documentation generation for your API endpoints\n- **🔧 Environment Configuration** - Seamless switching between development, testing, and production environments\n- **🐳 Docker Support** - Optimized multi-stage Docker builds for both development and production\n- **☁️ AWS Deployment** - Ready-to-use CloudFormation template for AWS ECS Fargate deployment\n- **🧪 Testing** - Comprehensive Jest setup for unit and integration testing\n- **📝 Logging** - Structured logging with Winston for better debugging and monitoring\n- **🛡️ Error Handling** - Robust centralized error handling middleware\n- **✅ Code Quality** - Enforced code standards with ESLint and Prettier configuration\n\n## 🚦 Getting Started\n\n### Prerequisites\n\nBefore you begin, ensure you have the following installed:\n\n- **Node.js** (v14 or higher)\n- **npm** or **yarn** package manager\n- **MongoDB** (local installation or MongoDB Atlas account)\n- **Docker** (optional, for containerized development/deployment)\n\n### 📥 Installation\n\n1. **Clone the repository:**\n\n```bash\ngit clone https://github.com/HanlunWang/express-backend-template.git\ncd express-backend-template\n```\n\n2. **Install dependencies:**\n\n```bash\nnpm install\n# or with yarn\nyarn install\n```\n\n3. **Set up environment variables:**\n\n```bash\ncp .env.example .env\n```\n\n4. **Configure your environment:**\n   Open the `.env` file in your favorite editor and update the configuration values:\n   - Database connection string\n   - JWT secret key\n   - API port\n   - Logging levels\n   - Other application-specific settings\n\n### 🏃‍♂️ Running the Application\n\n#### Development Mode (with hot-reloading)\n\n```bash\nnpm run dev\n# or with yarn\nyarn dev\n```\n\n#### Production Mode\n\n```bash\nnpm run build\nnpm start\n# or with yarn\nyarn build\nyarn start\n```\n\n## 🐳 Docker Setup\n\nThis project features a sophisticated multi-stage Docker build process that optimizes both development and production environments.\n\n### Docker Commands\n\n```bash\n# Start development environment with hot-reloading\nnpm run docker:dev\n\n# Start production environment\nnpm run docker:prod\n\n# Build development Docker image\nnpm run docker:dev:build\n\n# Build production Docker image\nnpm run docker:prod:build\n\n# Stop all running containers\nnpm run docker:stop\n\n# Clean up containers, networks, and volumes\nnpm run docker:clean\n```\n\n### 🔄 Docker Environment Configuration\n\nThe Docker setup ensures consistent environments across all stages of development:\n\n- **🛠️ Development Environment:**\n\n  - Uses nodemon for automatic server restarts\n  - Mounts source code as a volume for real-time code changes\n  - Includes development dependencies for better debugging\n\n- **🏭 Production Environment:**\n  - Uses compiled JavaScript code for optimal performance\n  - Minimizes image size by excluding development dependencies\n  - Implements proper Node.js best practices for containers\n\n### Docker Compose Services\n\nThe project includes a comprehensive `docker-compose.yml` with the following services:\n\n- **app-dev**: Development environment with hot-reloading capability\n- **app-prod**: Production-optimized environment\n- **mongo**: MongoDB database service with persistent data storage\n\n## 📚 API Documentation\n\nThe application automatically generates comprehensive API documentation using Swagger UI.\n\nOnce the application is running, access the interactive API documentation at:\n\n```\nhttp://localhost:3000/api-docs\n```\n\nThis documentation includes:\n\n- Detailed endpoint descriptions\n- Request/response schemas\n- Authentication requirements\n- Interactive API testing capability\n\n## 📁 Project Structure\n\n```\n.\n├── src/                      # Source code directory\n│   ├── config/               # Configuration files and environment setup\n│   ├── controllers/          # Request handlers and business logic\n│   ├── middleware/           # Express middleware components\n│   ├── models/               # Mongoose data models\n│   ├── routes/               # API route definitions\n│   ├── utils/                # Utility functions and helpers\n│   ├── __tests__/            # Test files\n│   └── index.ts              # Application entry point\n├── aws/                      # AWS deployment configuration files\n├── dist/                     # Compiled JavaScript output\n├── logs/                     # Application log files\n├── .env.example              # Example environment variables template\n├── .eslintrc.js              # ESLint configuration\n├── .prettierrc               # Prettier code formatting rules\n├── docker-compose.yml        # Docker Compose service definitions\n├── Dockerfile                # Multi-stage Docker build configuration\n├── .dockerignore             # Files excluded from Docker context\n├── jest.config.js            # Jest testing framework configuration\n├── package.json              # Project dependencies and scripts\n├── tsconfig.json             # TypeScript compiler configuration\n└── README.md                 # Project documentation\n```\n\n## 🧪 Testing\n\nThe project includes a comprehensive testing setup using Jest:\n\n```bash\n# Run all tests\nnpm test\n\n# Run tests with coverage report\nnpm test -- --coverage\n\n# Run tests in watch mode during development\nnpm test -- --watch\n```\n\nThe testing framework supports:\n\n- Unit tests for individual functions and components\n- Integration tests for API endpoints\n- Mock services for external dependencies\n- Code coverage reporting\n\n## 🚢 Deployment\n\n### 🐳 Docker Deployment\n\nFor production deployment using Docker:\n\n1. **Build the production image:**\n\n```bash\nnpm run docker:prod:build\n```\n\n2. **Run the production container:**\n\n```bash\nnpm run docker:prod\n```\n\nThis setup is ideal for deploying to any Docker-compatible hosting service, including:\n\n- Digital Ocean\n- Heroku\n- Google Cloud Run\n- Azure Container Instances\n\n### ☁️ AWS Deployment\n\nThe project includes ready-to-use AWS CloudFormation templates for deploying to AWS ECS Fargate:\n\n1. **Package the CloudFormation template:**\n\n```bash\naws cloudformation package \\\n  --template-file aws/cloudformation.yml \\\n  --s3-bucket your-deployment-bucket \\\n  --output-template-file packaged-template.yml\n```\n\n2. **Deploy the CloudFormation stack:**\n\n```bash\naws cloudformation deploy \\\n  --template-file packaged-template.yml \\\n  --stack-name express-backend \\\n  --parameter-overrides \\\n    Environment=prod \\\n    MongoDBUri=your-mongodb-uri \\\n    JwtSecret=your-jwt-secret \\\n  --capabilities CAPABILITY_IAM\n```\n\nThe AWS deployment includes:\n\n- Auto-scaling configuration\n- Load balancing\n- Secure environment variable management\n- CloudWatch logging integration\n- IAM role configuration\n\n## 🔄 Environment Consistency\n\nThis project is meticulously designed to ensure consistency between development and production environments:\n\n1. **🐳 Docker Multi-stage Builds**: The Dockerfile uses multi-stage builds to create optimized images for both development and production while maintaining consistency.\n\n2. **🔐 Environment Variables**: Environment variables are managed consistently across all environments using dotenv.\n\n3. **📂 Volume Mounting**: In development, source code is mounted as a volume for hot-reloading without rebuilding the container.\n\n4. **📦 Dependency Management**: Dependencies are installed consistently in all environments with package.json and yarn.lock/package-lock.json.\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## 📬 Contact\n\nHave questions or suggestions? Feel free to open an issue or reach out to the maintainers.\n\n---\n\n⭐ **Star this repository if you find it useful!** ⭐\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhanlunwang%2Fexpress-backend-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhanlunwang%2Fexpress-backend-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhanlunwang%2Fexpress-backend-template/lists"}