narra-express

Narra Express

Express.js MVC boilerplate with TypeScript, Authentication, and Database support

🚀 Quick Start

Create a new Narra Express app:

npx narra-express my-app
cd my-app
cp .env.example .env
# Edit .env with your credentials
npm run dev

Create a 256-bit key

This will be use in the .env file for the jwt tokens

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Generate three tokens using the command above. Copy the generate keys and update the following variables in the .env file:

• JW_ACCESS_SECRET
• JW_REFRESH_SECRET
• CSRF_JWT_SECRET

That's it! Your Express.js API with MVC structure is ready at http://localhost:3000

📖 Full Documentation

See Create Narra App Guide for detailed setup instructions and alternative installation methods.

Narra Express API

DATABASE

To setup database configuration

• Open the .env file in the root directory of the project.
• Locate the section labeled # Database Configuration.
• Update the following variables with your database details:
  • DB_HOST: Set this to your database host (e.g., localhost).
  • DB_USER: Set this to your database username (e.g., root).
  • DB_PASSWORD: Set this to your database password (e.g., your-database-password).
  • DB_NAME: Set this to your desired database name (e.g., your-database-name).
  • DB_PORT: Set this to your database port number (e.g., 3306 for MySQL).
• Save the .env file.

To create the database

• Ensure you have MySQL server running on your machine.
• Open a terminal and navigate to the root directory of the project.
• Run the following command to execute the database setup script:

  npm run setup-db
  

• The script will connect to the MySQL server and create the database specified in the .env file.

APPLICATION

To run the application

• Open a terminal and navigate to the root directory of the project.
• Install the project dependencies by running:

  npm install
  

• Start the application with the following command:

  npm run dev
  

• The server should now be running, and you can access it at http://localhost:3000 (or the port specified in your .env file).

To test the application

• Use a tool like Postman or cURL to send requests to the API endpoints.
• Refer to the API documentation for details on available endpoints and request formats.

AUTHENTICATION

This project uses JWT (JSON Web Tokens) for authentication.

• To access protected routes, you need to include a valid JWT in the Authorization header of your requests.
• The token should be in the format: Bearer <your-token-here>.
• You can generate a JWT using the /auth/login endpoint (if implemented) or through your own authentication mechanism.
• Ensure that the JWT secret key is set in the .env file under the JWT_SECRET variable.

(See auth.controller.ts, auth.middleware.ts, and auth.route.ts for reference)

MIDDLEWARE

This project uses middleware for various purposes, including validation, authentication, csrf, and rate limiting.

• Authentication Middleware: Protects routes by verifying JWT tokens.
• Validation Middleware: Validates request data against defined schemas.
• CSRF Middleware: Protects against Cross-Site Request Forgery attacks.
• Rate Limiting Middleware: Limits the number of requests from a single IP address to prevent abuse.
• You can find the middleware implementations in the src/middleware directory.

LOGGING

This project using a persistent logging mechanism with log rotation.

• Log files are stored in the logs directory at the root of the project.
• Log files are rotated daily, and old log files are retained for a configurable number of days (default is 60 days).
• You can configure the logging settings in the .env file.

To use the logging feature for testing purposes

• Start the application as described above.
• Send a GET request to the /example/logs endpoint:

  GET http://localhost:3000/example/logs
  

• This will trigger various log messages (info, warn, error, transaction, trace, fatal).
• Check the console output and the log files in the logs directory to see the generated log messages.

Versioning

Patch version

(updates 1.0.0 → 1.0.1)

npm version patch

Minor version

(updates 1.0.0 → 1.1.0)

npm version minor

Major version

(updates 1.0.0 → 2.0.0)

npm version major

TODO:

• IMPORTANT: make this app work in a 512mb and 0.5CPU environment
• Optimize database connections
• Optimize the logging feature
• Optimize the overall performance of the app
• Implement mailer service for email notifications
• Implement Queue system for background tasks

  // Log memory info on startup
  const mem = process.memoryUsage();
  log.info('Initial memory usage', {
    rss: `${Math.round(mem.rss / 1024 / 1024)}MB`,
    heapUsed: `${Math.round(mem.heapUsed / 1024 / 1024)}MB`,
    heapTotal: `${Math.round(mem.heapTotal / 1024 / 1024)}MB`,
  });