npm package: @patdevng/simple-template
Description: CLI tool to scaffold production-ready TypeScript APIs with Bun/Node compatibility, OpenAPI, and Zod validation
Author: Patrick Okuns
Latest version: 1.0.0

# @patdevng/simple-template

> A CLI tool to scaffold production-ready TypeScript APIs with Bun/Node compatibility, OpenAPI documentation, and Zod validation

## Features

- 🚀 Interactive CLI with beautiful prompts
- ⚡ Bun-first with Node.js compatibility
- 📝 OpenAPI 3.0 documentation (auto-generated from Zod schemas)
- ✅ Type-safe request/response validation with Zod
- 🔐 Optional JWT authentication
- 🗄️ Optional MongoDB integration
- 📦 Example CRUD resource
- 🐳 Docker support
- 🎨 Beautiful error handling

## Installation

```bash
# Using npm
npm install -g @patdevng/simple-template

# Using yarn
yarn global add @patdevng/simple-template

# Using pnpm
pnpm add -g @patdevng/simple-template
```

## Quick Start

```bash
# Interactive mode
npx @patdevng/simple-template

# With project name
npx @patdevng/simple-template my-api

# Or if installed globally
simple-template my-api
```

## Interactive Prompts

The CLI will guide you through:

1. **Project name** - Name of your project
2. **Description** - Brief description
3. **Runtime** - Choose Bun (recommended), Node.js, or Both
4. **Features** - Select optional features:
   - MongoDB integration
   - JWT Authentication
   - Example CRUD resource (users)
5. **Package manager** - npm, yarn, pnpm, or bun
6. **Git init** - Initialize git repository
7. **Install deps** - Install dependencies automatically

## Generated Project Structure

```
my-api/
├── src/
│   ├── index.ts           # Application entry point
│   ├── server.ts          # Express server setup
│   ├── env.ts             # Zod-validated environment
│   ├── error.ts           # Custom error classes
│   ├── logger.ts          # Pino logger
│   ├── db.ts              # MongoDB connection (optional)
│   ├── http/
│   │   ├── api.ts         # Route registration
│   │   ├── openapi.ts     # OpenAPI registry
│   │   ├── middleware/    # Express middleware
│   │   └── resources/     # API endpoints
│   ├── app/               # Business logic (if example enabled)
│   ├── models/            # Database models (if MongoDB enabled)
│   └── types/             # Shared Zod schemas
├── package.json
├── tsconfig.json
├── .env.example
├── Dockerfile             # If Bun runtime selected
└── README.md
```

## Example Generated API

Once you've generated a project, you'll have these endpoints:

### Health Check
```bash
GET /api/v1/health
```

### OpenAPI Documentation
```bash
GET /api/v1/openapi.json
```

### Users CRUD (if example enabled)
```bash
GET    /api/v1/users        # List users
GET    /api/v1/users/{id}   # Get user
POST   /api/v1/users        # Create user
PUT    /api/v1/users/{id}   # Update user
DELETE /api/v1/users/{id}   # Delete user
```

## Why simple-template?

### Zod-First Architecture
- **Single Source of Truth**: Your Zod schemas define validation, TypeScript types, AND OpenAPI documentation
- **No Duplication**: Write your schema once, use it everywhere
- **Type Safety**: Compile-time and runtime validation

### Route Constructor Pattern
Inspired by production-grade APIs, featuring declarative route definitions:

```typescript
route({
  category: 'Users',
  method: 'post',
  path: '/users',
  summary: 'Create a new user',
  request: {
    body: CreateUserRequest,  // Zod schema
  },
  responses: {
    201: {
      description: 'Created user',
      schema: User,  // Zod schema
    },
  },
  handler: createUserHandler,
});
```

### Production-Ready Out of the Box
- ✅ Request validation with detailed error messages
- ✅ Structured error handling
- ✅ Request/response logging
- ✅ Environment variable validation
- ✅ OpenAPI documentation
- ✅ Docker support

## Development

### Building from source

```bash
git clone https://github.com/patrickokuns/simple-template.git
cd simple-template
npm install
npm run build
```

### Test locally

```bash
# Link the package locally
npm link

# Use it
simple-template test-project
```

## Architecture Patterns

Generated projects follow these proven patterns:

- **Route Constructor Pattern**: Declarative route definitions with automatic OpenAPI registration
- **Zod-First Approach**: Single source of truth for validation, types, and API docs
- **Feature-Based Structure**: Group related files by feature/resource
- **Middleware Composition**: Reusable middleware for validation, auth, error handling
- **Environment Validation**: Zod-validated env vars at startup
- **Layered Architecture**: HTTP layer → Business logic → Data access

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Issues

Found a bug or have a feature request? Please open an issue on [GitHub](https://github.com/patrickokuns/simple-template/issues).