Skip to content

Home

Jump to bottom
aquie00tt edited this page Oct 20, 2024 · 2 revisions

Home

Welcome to the Express TypeScript Starter Kit! This project provides a boilerplate for developing APIs using Express.js with TypeScript. This wiki contains documentation for project structure, setup instructions, usage, and more.

1. Project Structure

Here is an overview of the project’s folder structure, along with explanations for each directory.

express-typescript-starter-kit/
│
├── src/                         # Main application source code
│   ├── controllers/              # Controllers handling API logic
│   ├── middlewares/              # Middleware for handling requests and errors
│   ├── routes/                   # API route definitions
│   ├── db/                       # Database-related files
│   │   └── models/               # Database models (e.g., MongoDB schemas)
│   ├── errors/                   # Custom error classes
│   ├── types/                    # TypeScript type definitions and interfaces
│   ├── utils/                    # Utility functions (e.g., configuration, helpers)
│   ├── app.ts                    # Main Express app setup
│   └── server.ts                 # Server startup logic
│
├── tests/                        # Unit and integration test files
│
├── .eslintrc.js                  # ESLint configuration
├── .prettierrc                   # Prettier configuration
├── jest.config.js                # Jest test configuration
├── package.json                  # Project dependencies and scripts
└── tsconfig.json                 # TypeScript configuration

1.1 src/ Directory

  • controllers/: Handles logic for processing incoming API requests and returning responses.
  • middlewares/: Holds middleware for handling request flow, validation, and error handling.
  • routes/: Defines API endpoints and links them with the appropriate controllers.
  • db/models/: Contains database models, including MongoDB schemas and other database-related objects.
  • errors/: Contains custom error classes for handling specific application errors.
  • types/: Defines shared TypeScript types and interfaces used across the app.
  • utils/: Stores utility functions for handling tasks like configuration, logging, and helpers.
  • app.ts: Sets up the Express app, applies middleware, and configures the main application logic.
  • server.ts: Starts the server, defines the port, and logs the startup information.

2. Setup

This section explains how to set up and run the project on your local machine.

2.1 Prerequisites

You will need the following software to run the project:

2.2 Step-by-Step Setup

1. Clone the repository:

git clone https://github.com/aquie00tt/express-typescript-starter-kit.git
cd express-typescript-starter-kit

2. Install dependencies:

npm install
# or
yarn install

3. Set up environment variables:
Copy the .env.sample file and rename it to .env.(development | production | test) Adjust the values according to your configuration.

4. Run MongoDB:
Ensure MongoDB is running. You can use a local MongoDB instance or MongoDB Atlas.

5. Run the application:

npm run dev

6. Run tests:

npm test

3. Usage

3.1 Basic API Endpoints

Here are some basic API endpoints available in the project:

  • POST /api/v1/auth/register: Register a new user
  • POST /api/v1/auth/#: Log in a user
  • GET /api/v1/users/me: Get the current user’s profile (authentication required)

** 3.2 Authentication** The app uses JWT (JSON Web Token) for authentication. Provide a valid JWT token in the Authorization header for protected routes:

Authorization: Bearer <your-token>

4. Testing

Tests are written using Jest. Unit and integration tests are located in the tests directory.

  • Run tests:
npm test

You can add more tests as needed in the tests/ directory for new routes, models, and controllers.

5. Contributing

If you’d like to contribute to this project, follow these steps:

  1. Fork the repository: Create your own fork of this repository.
  2. Create a new branch:
git checkout -b feature/your-feature
  1. Make your changes and test thoroughly.
  2. Submit a pull request: Open a pull request describing the changes made and why they’re beneficial.
Clone this wiki locally