Tin - Express.js Project Generator

A modern command-line tool for quickly scaffolding Express.js applications with TypeScript or JavaScript

Generate complete project structures with authentication, MongoDB integration, and best practices ready to use!

Installation • Quick Start • Features • Documentation • Contributing

Tin is the fastest way to scaffold production-ready Express.js projects with TypeScript or JavaScript. Whether you're building RESTful APIs, web applications, or microservices, Tin provides everything you need to get up and running quickly with battle-tested patterns and practices.

✨ Features

🎯 Core Functionality

• ⚡ Generate Express.js REST APIs in one command
• 🔄 Choose TypeScript or JavaScript templates
• 🔒 Flexible Authentication Options:
  • 🔑 JWT Authentication (header-based)
  • 🍪 Cookie-based JWT for enhanced security
• 📦 MongoDB integration with Mongoose
• 📚 Swagger UI with OpenAPI documentation (optional, dark mode)

🛠️ Developer Experience

• 🐳 Optional Docker setup generation
• 🚀 Modular architecture with best practices
• 🛠️ Pre-configured development environment
• 📝 Error handling middleware ready to use
• 🔐 Auto-generated .env files with secure defaults

📦 Installation

Global Installation (Recommended)

npm install -g create-tin

Using npx (No Installation Required)

npx create-tin my-api-project

🚀 Quick Start

Create a New Project

# Using the installed package
create-tin my-api-project

# Or using npx
npx create-tin my-api-project

Interactive Setup Process:

1. Choose language (TypeScript or JavaScript)
2. Select authentication method (JWT or Cookie-based)
3. Initialize Git repository
4. Set the server port
5. Add Docker configuration

⚙️ Command Line Options

Usage: create-tin [options] [project-name]

Options:
  --ts            Generate a TypeScript project template
  --js            Generate a JavaScript project template
  --jwt           Use JWT-based authentication (tokens in Authorization header)
  --cookies       Use Cookie-based authentication (JWT stored in HTTP-only cookies)
  --git           Initialize a new Git repository
  --skip-git      Skip Git initialization
  --port <number> Set the server port (default: 3000)
  --docker        Include Docker configuration
  --skip-docker   Skip adding Docker configuration
  --swagger       Include Swagger UI with OpenAPI documentation (dark mode)
  --skip-swagger  Skip adding Swagger UI
  -h, --help      Display this help message

💡 Tip: Use the --swagger flag to automatically add API documentation with Swagger UI to your project. The documentation comes pre-configured with a dark mode theme and includes example endpoints for authentication.

💡 Example Usage

# Create a TypeScript project with JWT auth, Git and Docker configuration
create-tin my-ts-api --ts --jwt --git --docker

# Create a JavaScript project with cookie-based auth without Git and Docker
create-tin my-js-api --js --cookies --skip-git --skip-docker --port 5000

# Create a TypeScript project with JWT auth, Git, Docker and Swagger UI
create-tin api-docs --ts --jwt --git --docker --swagger

Using Swagger UI in Your Project

When you create a project with the --swagger flag, your API will automatically be configured with Swagger UI documentation. After starting your server, you can access the API documentation at:

http://localhost:PORT/api-docs

The documentation includes:

• Authentication endpoints (register, login)
• Interactive testing capabilities
• Request/response examples
• Dark mode UI for better readability
• Full-page responsive design

The Swagger UI integration is fully customizable:

• Edit the API specification in src/docs/openapi.yaml
• Customize the dark theme in src/styles/swagger-dark.css
• Configure Swagger UI options in src/config/swagger.ts (or .js)

📚 API Documentation with Swagger UI

If you choose to include Swagger UI when generating your project, your API will have built-in interactive documentation available at /api-docs.

Features

• Interactive API Explorer: Test your API endpoints directly from the browser
• Dark Mode UI: Modern interface with dark theme for better readability
• OpenAPI 3.0: Documentation follows OpenAPI 3.0 specification
• Authentication Documentation: Includes auth endpoints with request/response examples
• Fully Responsive: Works well on all screen sizes
• Customizable: Easy to modify the OpenAPI spec to match your API

How to Use

1. Start your server with npm run dev or npm start
2. Navigate to http://localhost:PORT/api-docs in your browser
3. Explore the interactive documentation
4. Test endpoints directly from the UI

Customization

• The OpenAPI specification file is located at src/docs/openapi.yaml
• CSS styling can be customized in src/styles/swagger-dark.css
• Configure Swagger UI options in src/config/swagger.ts (or swagger.js)

Example Screenshot

📁 Generated Project Structure

my-api-project/
├── src/
│   ├── config/
│   │   ├── db.ts
│   │   └── swagger.ts (if Swagger UI option selected)
│   ├── controllers/
│   │   └── authController.ts
│   ├── middlewares/
│   │   ├── errorHandler.ts
│   │   └── verifyToken.ts
│   ├── models/
│   │   └── userModel.ts
│   ├── docs/
│   │   └── openapi.yaml (if Swagger UI option selected)
│   ├── styles/
│   │   └── swagger-dark.css (if Swagger UI option selected)
│   ├── routes/
│   │   └── authRoutes.ts
│   ├── types/
│   │   ├── constants.ts
│   │   └── index.d.ts
│   └── index.ts
├── .env
├── .env.example
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md

my-api-project/
├── src/
│   ├── config/
│   │   ├── db.js
│   │   └── swagger.js (if Swagger UI option selected)
│   ├── controllers/
│   │   └── authController.js
│   ├── middlewares/
│   │   ├── errorHandler.js
│   │   └── verifyToken.js
│   ├── models/
│   │   └── userModel.js
│   ├── docs/
│   │   └── openapi.yaml (if Swagger UI option selected)
│   ├── styles/
│   │   └── swagger-dark.css (if Swagger UI option selected)
│   ├── routes/
│   │   └── authRoutes.js
│   └── index.js
├── .env
├── .env.example
├── .gitignore
├── package.json
└── README.md

🐳 Docker Support

When Docker configuration is enabled, the following files are generated:

| File | Description | |---------|-------------| | Dockerfile | Optimized multi-stage build | | docker-compose.yml | Docker Compose setup | | .dockerignore | Ignores unnecessary files |

🎯 Getting Started With Generated Projects

After generating your project:

# Navigate to your project directory
cd my-api-project

# Install dependencies
npm install

# Start the development server
npm run dev

🌟 Features of Generated Projects

🏗️ Express.js REST API
Clean architecture structure ready to use

🔐 Authentication Options
Choose between:

• JWT Authentication - Traditional token-based auth via headers
• Cookie-based JWT - Enhanced security with HTTP-only cookies

📊 MongoDB Integration
Complete setup with Mongoose ODM

📚 API Documentation

• Swagger UI Integration - Interactive API explorer
• Dark Mode Interface - Modern and readable design
• OpenAPI 3.0 - Comprehensive API specification
• Pre-configured Auth Routes - Ready to test and extend

🔧 Environment Variables

• Auto-generated .env - Ready to use with secure JWT secrets
• Context-aware configuration - Adapts to Docker, Swagger, and port settings
• .env.example included - Template for deployment reference

⚠️ Error Handling
Professional middleware implementation

📘 TypeScript Support
Type definitions (TypeScript template only)

⚡ Requirements

🤔 Why Choose Tin?

• Fast Development Start: Get a fully configured Express.js project in seconds
• Production Ready: Templates follow industry best practices and security standards
• Flexibility: Use either TypeScript or JavaScript based on your preference
• Modern Stack: Uses the latest stable versions of Node.js, Express, and MongoDB
• Docker Integration: Optional containerization with Docker and Docker Compose
• Complete Authentication: JWT authentication system ready to use
• Active Maintenance: Regular updates and security patches

🔄 Comparison with Alternatives

| Feature | Tin | Express Generator | Create React App | |---------|-----|-------------------|-----------------| | TypeScript Support | ✅ | ❌ | ✅ | | JWT Authentication | ✅ | ❌ | ❌ | | Cookie-based Auth | ✅ | ❌ | ❌ | | MongoDB Integration | ✅ | ❌ | ❌ | | Swagger UI / API Docs | ✅ | ❌ | ❌ | | Dark Mode UI | ✅ | ❌ | ❌ | | Docker Support | ✅ | ❌ | ❌ | | Interactive CLI | ✅ | ❌ | ✅ | | Git Integration | ✅ | ❌ | ✅ |

📄 License

This project is licensed under the ISC License.