Express Application Framework

📚 English Documentation

A powerful Laravel-style application framework for Express.js with built-in security, rate limiting, compression, and middleware management.

🎯 Features

• 🔒 Security First: Integrated Helmet.js for HTTP header protection
• ⚡ Performance: Built-in gzip compression for optimized responses
• 🛡️ Rate Limiting: DDoS protection with configurable rate limits
• 🌍 CORS Support: Flexible cross-origin resource sharing configuration
• 📦 Body Parsing: Configurable JSON and URL-encoded body size limits
• 🔑 Environment Management: Automatic .env file loading
• ⚙️ Static Files: Serve public assets automatically
• 💪 Type-Safe: Full TypeScript support with strict mode
• 🏥 Health Checks: Built-in health check endpoint
• 🎨 Extensible: Laravel-style callback pattern for app customization

📦 Installation

npm install express-application-framework express

⚙️ Configuration

Create a .env file in your project root:

NODE_ENV=development
PORT=3000

🚀 Quick Start

import { Application } from 'express-application-framework';
import path from 'path';

// Create application
const app = Application({
    root: path.resolve(process.cwd()),
    callback: (app) => {
        // Add your routes here
        app.get('/', (req, res) => {
            res.json({ message: 'Hello World!' });
        });
        return app;
    }
});

// Start server
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
    console.log(`Server running on port ${PORT}`);
});

🔧 Configuration Options

interface ApplicationType {
    // Required: Project root directory
    root: string;

    // Required: Callback to customize the app
    callback: (app: Express) => Express;

    // Optional: Body parser limits
    config?: {
        jsonLimit?: string;        // Default: "1mb"
        urlencodedLimit?: string;  // Default: "5mb"
    };

    // Optional: Rate limiting config
    rateLimit?: Partial<Options>;

    // Optional: CORS options
    cors?: CorsOptions;

    // Optional: Port number (metadata)
    port?: number;

    // Optional: Server URL (metadata)
    url?: string;
}

📝 Examples

Custom Rate Limiting

const app = Application({
    root: process.cwd(),
    rateLimit: {
        windowMs: 15 * 60 * 1000, // 15 minutes
        max: 100,                  // Limit each IP to 100 requests per windowMs
        message: { status: false, error: 'Too many requests' }
    },
    callback: (app) => {
        app.get('/data', (req, res) => {
            res.json({ data: 'example' });
        });
        return app;
    }
});

CORS Configuration

const app = Application({
    root: process.cwd(),
    cors: {
        origin: 'https://example.com',
        credentials: true,
        methods: ['GET', 'POST', 'PUT', 'DELETE']
    },
    callback: (app) => app
});

Custom Body Limits

const app = Application({
    root: process.cwd(),
    config: {
        jsonLimit: '10mb',
        urlencodedLimit: '50mb'
    },
    callback: (app) => app
});

🏥 Health Check Endpoint

The framework automatically provides a health check endpoint:

GET /health

Response:
{ "status": "ok" }

📂 Project Structure

project/
├── src/
│   ├── Application.ts       # Factory function
│   ├── index.ts             # Entry point
│   └── @types/
│       └── index.d.ts       # Type definitions
├── public/                  # Static files
├── .env                     # Environment variables
├── package.json
└── tsconfig.json

🔐 Security Features

• Helmet.js: Protects against XSS, clickjacking, MIME sniffing
• CORS: Configurable cross-origin request handling
• Rate Limiting: Prevents DDoS and brute force attacks
• Compression: Reduces payload size for better security
• Proxy Trust: Correctly identifies client IP behind reverse proxies

📋 Middleware Stack

The application applies middleware in this order:

1. Proxy trust configuration
2. Helmet security headers
3. CORS handling
4. Gzip compression
5. Rate limiting
6. Cookie parsing
7. JSON body parsing
8. URL-encoded body parsing
9. Static file serving
10. Health check endpoint
11. User-defined routes (via callback)

🤝 Contributing

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

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

Md Atikul Islam - @mdatikulislamfr