edwinhern / express-typescript-2024

Express + TypeScript + Boilerplate for Web / API App

🚀 Express TypeScript Boilerplate 2024

🌟 Introduction

Welcome to the Express TypeScript Boilerplate 2024 – a streamlined, efficient, and scalable foundation for building powerful backend services. This boilerplate merges modern tools and practices in Express.js and TypeScript, enhancing productivity, code quality, and performance.

💡 Motivation and Intentions

Developed to streamline backend development, this boilerplate is your solution for:

• ✨ Reducing setup time for new projects.
• 📊 Ensuring code consistency and quality.
• ⚡ Facilitating rapid development with cutting-edge tools.
• 🛡️ Encouraging best practices in security, testing, and performance.

🚀 Features

• 📁 Modular Structure: Organized by feature for easy navigation and scalability.
• 💨 Faster Execution with tsx: Rapid TypeScript execution with esbuild, complemented by tsc for type checking.
• 🌐 Stable Node Environment: Latest LTS Node version in .nvmrc.
• 🔧 Simplified Environment Variables with Envalid: Centralized and easy-to-manage configuration.
• 🔗 Path Aliases: Cleaner code with shortcut imports.
• 🔄 Renovate Integration: Automatic updates for secure and up-to-date dependencies.
• 🔒 Security: Helmet for HTTP header security and CORS setup.
• 📊 Logging: Efficient logging with pino-http.
• 🧪 Comprehensive Testing: Robust setup with Vitest and Supertest.
• 🔑 Code Quality Assurance: Husky and lint-staged for consistent quality.
• ✅ Unified Code Style: Biomejs for a consistent coding standard.
• 📃 API Response Standardization: ServiceResponse class for consistent API responses.
• 🐳 Docker Support: Ready for containerization and deployment.
• 📝 Input Validation with Zod: Strongly typed request validation using Zod.
• 🧩 API Spec Generation: Automated OpenAPI specification generation from Zod schemas to ensure up-to-date and accurate API documentation.

🛠️ Getting Started

Step 1: 🚀 Initial Setup

• Clone the repository: git clone https://github.com/edwinhern/express-typescript-2024.git
• Navigate: cd express-typescript-2024
• Install dependencies: npm ci

Step 2: ⚙️ Environment Configuration

• Create .env: Copy .env.template to .env
• Update .env: Fill in necessary environment variables

Step 3: 🏃‍♂️ Running the Project

• Development Mode: npm run dev
• Building: npm run build
• Production Mode: Set .env to NODE_ENV="production" then npm run build && npm run start

🤝 Feedback and Contributions

We'd love to hear your feedback and suggestions for further improvements. Feel free to contribute and join us in making backend development cleaner and faster!

🎉 Happy coding!

express-typescript-2024's Issues

Help Wanted: Implementing JWT Authentication for API Routes

Overview

We are planning to integrate JWT-based authentication into our existing API. This feature aims to secure our routes while providing flexibility to exempt certain routes from requiring authentication. Additionally, we want to ensure that our Swagger documentation accurately reflects the authentication requirements for each route.

Requirements

• Implement JWT authentication middleware that can be easily applied to selected routes.
• Ensure a mechanism is in place to mark certain routes as public (no authentication required) while defaulting to private (authentication required).
• Update our Swagger/OpenAPI documentation to reflect the authentication status of each route, enhancing clarity for API consumers.

Proposed Solution

I propose the development of a reusable function or middleware that encapsulates the following functionalities:

• JWT Authentication: A middleware that validates JWT tokens for protected routes.
• Route Configuration: Enhance our route setup to include authentication requirements. This could be a flag or setting within the route's configuration.
• Swagger Documentation: Automatically update our OpenAPI documentation based on the route's authentication requirements.

Example Concept

Here's a conceptual approach to how we might define a route with this new system:

Contribution Guidelines

• Fork the repository and create a new branch for your feature.
• Write clean, readable, and well-documented code.
• Ensure that existing tests pass and write new tests as necessary to cover the authentication functionality.
• Update the README and any relevant documentation to reflect the changes.
• Submit a pull request with a clear description of the changes and any other relevant information.

Discussion

I'm open to ideas on how best to implement this feature and would love to collaborate with anyone interested in contributing. If you have experience with JWT authentication or have suggestions on improving this proposal, please feel free to share your thoughts or submit a pull request.

cannot access your website

express.hernandezserver.com/

Error Run : npm run dev

Error that i facing was :

❯ npm run dev

> [email protected] dev
> tsx watch --clear-screen=false src/index.ts | pino-pretty

================================
 Invalid environment variables:
    COMMON_RATE_LIMIT_MAX_REQUESTS: Invalid number input: ""20" # Max number of requests per window per IP"
    COMMON_RATE_LIMIT_WINDOW_MS: Invalid number input: ""1000" # Window size for rate limiting (ms)"
    HOST: Invalid host (domain or ip): ""localhost"       # Hostname for the server"
    NODE_ENV: Value ""development" # Options: 'development', 'production'" not in choices [development,production,test]
    PORT: Invalid port input: ""8080"            # The port your server will listen on"
================================

 Exiting with error code 1

Recommendation - use envalid

Great template!

I recommend letting envalid handle envirment sanitation and validation.

https://www.npmjs.com/package/envalid

Would be happy to apply & refactor if you interested to explore further.

Protect route with auth middleware

Hi.

Greate boilerplate. You can add a auth middleware to protect some route. I have an implementation in mind. Can submit a PR if you are not already working on it.

Request is not typed

request with type Request in route's controller is not strictly-typed to zod schema

Not compiling TS with `npm run dev`

It looks like that the TS code is not being recompiled when there's a change.
Did I miss something?

Here's my workaround:

    "dev": "tsc-watch --noClear --onSuccess \"tsx ./dist/index.js\"",

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• chore(deps): lock file maintenance

Detected dependencies

dockerfile

Dockerfile

• node 22.5-slim

github-actions

.github/workflows/build.yml

• actions/checkout v4
• actions/setup-node v4

.github/workflows/code-quality.yml

• actions/checkout v4
• biomejs/setup-biome v2

.github/workflows/docker-image.yml

• actions/checkout v4
• docker/login-action v3

.github/workflows/test.yml

• actions/checkout v4
• actions/setup-node v4

npm

package.json

• @asteasolutions/zod-to-openapi ^7.0.0
• cors ^2.8.5
• dotenv ^16.4.5
• envalid ^8.0.0
• express ^4.19.2
• express-rate-limit ^7.2.0
• helmet ^7.1.0
• http-status-codes ^2.3.0
• pino-http ^10.0.0
• swagger-ui-express ^5.0.0
• zod ^3.22.4
• @biomejs/biome 1.8.3
• @types/cors ^2.8.17
• @types/express ^4.17.21
• @types/supertest ^6.0.2
• @types/swagger-ui-express ^4.1.6
• husky ^9.0.11
• lint-staged ^15.2.2
• pino-pretty ^11.0.0
• rimraf ^6.0.0
• supertest ^7.0.0
• tsup ^8.0.2
• tsx ^4.7.2
• typescript ^5.4.4
• vite-tsconfig-paths ^4.3.2
• vitest ^2.0.0

nvm

.nvmrc

• node 22.5.1

regex

biome.json

• @biomejs/biome 1.8.3

---

• Check this box to trigger a request for Renovate to run again on this repository

Hanging forever when calling urls that doesn't exist

I have tried to fix it, but no luck yet.

Not able to crate post method with schema validation.

Not able to crate post method.

Please provide one example of post, put method with schema validation.

how to enable debugging with Code for mac

help would be appreciated

Thank you!

Your project is a breathe of fresh air. Thank you for not over-complicating the functionality - it's just right! Appreciated

Unable to send post requests

There seems to be code missing for adding post requests. I have tried for several hours to send a post request but I am getting undefined bodies etc.

One of the missing peaces for sure was :

app.use(express.json());
app.use(express.urlencoded())

but that didnt help. It just removed one problem.