create-nest-template-malahimdev/README.md

Scaffolds a NestJS template with Swagger, global pipes, exception filters, MongoDB connection and response helpers.

# create-nest-template-malahimdev 🚀

Scaffolds a **NestJS backend template** with built-in best practices and sensible defaults.

**Includes:**

* Swagger (light `/docs` and dark `/docsdark`) with Bearer auth support
* Global validation pipes (whitelist, transform, forbidNonWhitelisted)
* Global exception handling with standardized response helpers
* MongoDB connection boilerplate
* Example public / protected / hidden endpoints and a DTO-based POST

---

## Features

* Quick project scaffold for NestJS backends
* Ready-to-use helpers for success and error responses
* Swagger UI with light/dark themes and Bearer token configured
* Example `JwtAuthGuard` usage for protected routes
* Hidden endpoints excluded from Swagger using `@ApiExcludeEndpoint()`

---

## Installation (recommended)

Use `npx` to scaffold a new project:

```bash
npx create-nest-template-malahimdev my-new-backend
# or (force latest)
npx -y create-nest-template-malahimdev@latest my-new-backend
```

---

## Getting started

1. Move into your project folder:

```bash
cd my-new-backend
```

2. Install dependencies:

```bash
npm install
```

3. Create a `.env` file in the project root and add these variables (example):

```env
# .env
PORT=3000
MONGO_URI=mongodb://localhost:27017/mydb
# optional: used by JWT guard if included
JWT_SECRET=your_jwt_secret_here
```

* `PORT` → defaults to `3000` if not set
* `MONGO_URI` → defaults to local MongoDB instance if not set

4. Run the app in development mode:

```bash
npm run start:dev
```

> Common npm scripts included in the template (example):
>
> ```json
> {
>   "scripts": {
>     "start": "nest start",
>     "start:dev": "nest start --watch",
>     "build": "nest build"
>   }
> }
> ```

---

## API Endpoints (examples)

| Method |         Endpoint | Description                             | Auth | Swagger Visible |
| ------ | ---------------: | --------------------------------------- | :--: | :-------------: |
| GET    |              `/` | Health check / root                     |   ❌  |        ✅        |
| GET    |    `/public-api` | Example public API                      |   ❌  |        ✅        |
| GET    | `/protected-api` | Example protected API (JWT required)    |   ✅  |        ✅        |
| GET    |    `/hidden-api` | Hidden endpoint (excluded from Swagger) |   ❌  |        🚫       |
| POST   |   `/create-item` | Example POST with DTO validation        |   ❌  |        ✅        |

---

## Swagger docs

* Light theme → `http://localhost:3000/docs`
* Dark theme → `http://localhost:3000/docsdark`

Both include Bearer token configuration so you can paste a JWT and test protected endpoints.

---

## Response helpers

**Success response** helper usage:

```ts
successResponse('Message here', { data: { /* payload */ } });
```

**Error responses** (these throw appropriate Nest exceptions):

```ts
errorResponse.badRequest(['Invalid input']);
errorResponse.unauthorized(['You must login first']);
errorResponse.internal();
```

`errorResponse` produces standardized error objects and throws the correct HTTP exception.

---

## How routes are organized (example)

The template ships with a simple example controller that demonstrates:

* a public route
* a protected route guarded with `JwtAuthGuard` and annotated with `@ApiBearerAuth()`
* a hidden route annotated with `@ApiExcludeEndpoint()`
* a POST endpoint using DTO validation

This is a good starting point — replace or extend controllers, modules, and guards as your app grows.

---

## Should I include auth in the template?

This template includes a ready-to-wire `JwtAuthGuard` and Swagger Bearer setup. The guard itself can be disabled or removed if you prefer a minimal scaffold. Including an auth guard is helpful for developers who want a secure template out of the box; you can keep it optional by documenting how to enable/replace it (e.g. wire your own auth service and set `JWT_SECRET`).

---

## Contributing

Feel free to open an issue or submit a PR to add improvements (scripts, CI, more templates, extra integrations).

---

## Author

**Malahim Haseeb**
📧 [me@malahim.dev](mailto:me@malahim.dev)
🌐 [malahim.dev](https://malahim.dev)

---

## License

MIT © 2025 Malahim Haseeb