barnes-node-ts-express-starter/README.md

A modern Node.js TypeScript Express starter template with essential development tooling

# Barnes Node.js TypeScript Express Starter

A modern, production-ready Node.js backend starter template with TypeScript, Express, and essential development tooling. Get up and running in seconds with a well-structured, scalable backend foundation.

## 🚀 Quick Start

Create a new backend project instantly using npx:

```bash
npx barnes-node-ts-express-starter
```

Follow the prompts to:
1. Enter your project name
2. Navigate to the created directory
3. Install dependencies
4. Start developing!

```bash
cd your-project-name
npm install
npm run dev
```

Your server will be running at `http://localhost:3001` 🎉

## ✨ Features

- **TypeScript**: Full TypeScript support with strict configuration
- **Express.js**: Fast, minimalist web framework
- **Hot Reload**: Automatic server restart on file changes with nodemon
- **Environment Management**: Flexible environment configuration
- **Modern ES Modules**: Uses ES6 import/export syntax
- **Health Check**: Built-in status endpoint for monitoring
- **Production Ready**: Includes build scripts and optimized configuration
- **Clean Architecture**: Well-organized project structure

## 📁 Project Structure

```
your-project/
├── src/
│   ├── app.ts              # Express app configuration
│   ├── server.ts           # Server entry point
│   ├── config/
│   │   └── env.ts          # Environment configuration
│   └── routes/
│       ├── index.ts        # Main router
│       └── status.ts       # Health check endpoint
├── dist/                   # Compiled JavaScript (after build)
├── nodemon.json           # Nodemon configuration for development
├── nodemon.local.json     # Nodemon configuration for local env
├── tsconfig.json          # TypeScript configuration
├── package.json           # Dependencies and scripts
└── README.md              # This file
```

## 🛠 Available Scripts

- **`npm run dev`** - Start development server with hot reload (NODE_ENV=development)
- **`npm run dev:local`** - Start development server in local mode (loads .env file)
- **`npm run build`** - Compile TypeScript to JavaScript
- **`npm start`** - Start production server from compiled code

## 🔧 Environment Configuration

The starter supports multiple environment modes:

### Development Mode
```bash
npm run dev
```
- Uses `NODE_ENV=development`
- No .env file loading (uses system environment variables)

### Local Mode
```bash
npm run dev:local
```
- Uses `NODE_ENV=local`
- Automatically loads `.env` file for local development
- Create a `.env` file in your project root:

```env
PORT=3001
APP_MESSAGE=Hello from local development!
```

### Production
```bash
npm run build
npm start
```
- Runs compiled JavaScript from `dist/` folder
- Uses production environment variables

## 📡 API Endpoints

### Health Check
- **GET** `/status` - Returns server health information

Example response:
```json
{
  "uptime": 123.456,
  "message": "OK",
  "timestamp": 1674567890123
}
```

## 🚀 Getting Started with Development

1. **Add new routes**: Create new route files in `src/routes/` and register them in `src/routes/index.ts`

2. **Environment variables**: Add your variables to the `.env` file for local development

3. **Middleware**: Add Express middleware in `src/app.ts`

4. **Configuration**: Modify environment loading in `src/config/env.ts`

## 📦 Dependencies

### Production Dependencies
- **express**: Fast, unopinionated web framework
- **dotenv**: Loads environment variables from .env file

### Development Dependencies
- **typescript**: TypeScript compiler
- **@types/express**: TypeScript definitions for Express
- **nodemon**: Monitors file changes and restarts server
- **tsx**: TypeScript execution engine
- **cross-env**: Cross-platform environment variable setting

## 🔄 Customization

### Adding Database Support
```bash
# Example: Adding MongoDB with Mongoose
npm install mongoose
npm install -D @types/mongoose
```

### Adding Authentication
```bash
# Example: Adding JWT authentication
npm install jsonwebtoken bcryptjs
npm install -D @types/jsonwebtoken @types/bcryptjs
```

### Adding Validation
```bash
# Example: Adding request validation
npm install joi
npm install -D @types/joi
```

## 📋 Best Practices Included

- **TypeScript strict mode** for better code quality
- **ES Modules** for modern JavaScript features
- **Modular routing** for scalable code organization
- **Environment-based configuration** for different deployment stages
- **Health check endpoint** for monitoring and load balancers
- **Development tooling** with hot reload and TypeScript watching

## 🤝 Contributing

This starter template is designed to be a solid foundation for Node.js backend projects. Feel free to customize it according to your needs!

## 📝 License

MIT License - feel free to use this starter for your projects!

---

**Happy coding!** 🎯

Built with ❤️ for rapid backend development