A boilerplate for building scalable applications with Express.js and TypeScript.
This boilerplate provides a strong foundation for building applications using Express.js and TypeScript. It follows best practices for code quality, structure, and development workflow. The repository also supports Docker and includes preconfigured Git workflows for streamlined project management.
Clone the repository:
git clone https://github.com/MKAbuMattar/express-boilerplate.git
cd express-boilerplate
Install dependencies:
pnpm install
Set up environment variables:
cp .env.example .env
To start the development server, run:
pnpm dev
The server will start on the port specified in your .env
file (default: 8080).
To build the project for production:
pnpm build
Then, to start the production server:
pnpm start
Using Docker helps maintain a consistent development environment across machines. To build and run the project using Docker, use the following commands:
docker-compose up -d --build
express-boilerplate/
├── .github/ # GitHub configurations for CI/CD and issue templates
├── .vscode/ # VSCode-specific settings for workspace
├── plugins/ # Custom plugins (e.g., Pino transports)
├── src/ # Core application source code
│ ├── api/ # API routes and controllers
│ ├── bin/ # Application entry point (startup scripts)
│ ├── configs/ # Configuration files for logger, environment, etc.
│ ├── docs/ # API documentation and OpenAPI specs
│ ├── libs/ # Reusable libraries
│ ├── middlewares/ # Custom middleware logic
│ ├── models/ # Data models and schemas
│ ├── schemas/ # Validation schemas
│ ├── utils/ # Utility functions for the app
│ ├── validations/ # Business logic validations
│ └── index.ts # Main server file
├── Dockerfile # Docker configuration
├── compose.yml # Docker Compose for multi-service applications
├── .env.example # Example environment variables
├── LICENSE # License file
├── package.json # Project metadata and scripts
├── tsconfig.json # TypeScript configuration
└── README.md # Project documentation
Testing is crucial to ensure code reliability and prevent regressions. This project uses Vitest for running unit and integration tests.
Unit Tests: Test individual units of code in isolation.
Integration Tests: Test the interaction between different units of code.
Test Files: Test files are located in the src
directory with the .test.ts
extension.
pnpm test
Coverage Reports: To generate a code coverage report:
pnpm test:cov
Watch Mode: To run tests in watch mode (ideal for active development):
pnpm test:dev
[!TIP] Focus on writing tests that verify the behavior of the code, not implementation details.
main
: Reflects the production-ready state of the source code.develop
: Contains the latest delivered changes for the next release.main
for each feature or bug fix.
feat/
, fix/
).develop
.develop
.develop
into main
.main
.This project adheres to Semantic Versioning and uses Conventional Commits to manage releases. Every commit message and version change should follow this standard:
PATCH
release) or a hotfix.
git commit -m "fix(api): fix health check route"
MINOR
release) or enhancement.
git commit -m "feat(api): add user route"
MAJOR
release) that require a manual update.
git commit -m "feat!(api): change user route to use UUID"
git commit -m "chore: update dependencies"
git commit -m "docs: update README"
git commit -m "ci: add GitHub Actions workflow"
GitHub environments empower you to manage deployment settings and configure workflows in GitHub Actions more effectively. This feature enhances the security, control, and visibility of your CI/CD pipeline. Below, you'll find a step-by-step guide to setting up environments and securely managing secrets, such as PAT_TOKEN
, for Docker image builds.
Using GitHub Environments offers several advantages:
Follow these steps to set up GitHub Environments for your project:
Navigate to Your Repository:
Access Environment Settings:
Create a New Environment:
development
, staging
, production
) to indicate its purpose.Add Secrets to Your Environment:
PAT_TOKEN
as the secret name and paste your Personal Access Token into the value field.To utilize the PAT_TOKEN
secret in your GitHub Actions workflow for building Docker images, reference the secret using the syntax shown in the example workflow below. You can find this configuration in your docker-image.yml file:
name: Docker Image CI
on:
push:
branches:
- main
pull_request:
branches:
- main
permissions:
contents: read
issues: write
pull-requests: write
jobs:
build:
runs-on: ubuntu-latest
environment: development # Specify the environment
steps:
- uses: actions/checkout@v4
# Log in to the GitHub Container Registry only on main branch pushes
- name: Login to GitHub Container Registry
if: github.ref == 'refs/heads/main'
uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.PAT_TOKEN }}
# Add additional steps here (e.g., building and pushing the Docker image)
By following these guidelines, you can establish a robust and secure CI/CD process that enhances your development workflow while maintaining best practices for managing sensitive information.
Before running the Docker container, ensure you're logged into the GitHub Container Registry (GHCR). Replace TOKEN
and USERNAME
with your GitHub Personal Access Token (PAT) and GitHub username, respectively:
echo <YOUR_PAT_TOKEN> | docker login ghcr.io -u <USERNAME> --password-stdin
<YOUR_PAT_TOKEN>
: Your GitHub Personal Access Token with access to the container registry.<USERNAME>
: Your GitHub username.You can create a GitHub PAT here, ensuring it has the read:packages
scope.
[!NOTE] This step is required to pull the Docker image from the GitHub Container Registry for private repositories.
Once logged in, run the Docker container using the following command. Be sure to replace the environment variables and image information with your specific values:
docker run -d -p 8080:8080 \
-e NODE_ENV="development" \
-e PORT="8080" \
-e HOST="localhost" \
-e CORS_WHITELIST="*" \
-e API_KEY="uk6XUcp7Hj6f4O+w6b<O" \
ghcr.io/<USERNAME>/<REPOSITORY_NAME>:<DIGEST>
-p 8080:8080
: Maps the container's internal port 8080
to port 8080
on your machine.-e NODE_ENV="development"
: Sets the NODE_ENV
environment variable to development
. Other options might be production
or staging
depending on your setup.-e PORT="8080"
: Specifies the port on which the app should run inside the container.-e HOST="localhost"
: Defines the host, typically localhost
for local development.-e CORS_WHITELIST="*"
: Allows all domains by using a wildcard for CORS. Adjust this according to your security needs.-e API_KEY="uk6XUcp7Hj6f4O+w6b<O"
: An API key required by your application. Replace with your actual key.ghcr.io/<USERNAME>/<REPOSITORY_NAME>:<DIGEST>
: Replace <USERNAME>
, <REPOSITORY_NAME>
, and <DIGEST>
with your GitHub username, the repository name, and the specific image digest or tag (e.g., latest
).docker run -d --network host \
-e NODE_ENV="production" \
-e PORT="8080" \
-e HOST="0.0.0.0" \
-e CORS_WHITELIST="https://example.com" \
-e API_KEY="superSecretAPIKey123" \
ghcr.io/mkabumattar/express-boilerplate:latest
To check if your container is running, you can use the following command:
docker ps
This will display a list of all active containers. You should see your container listed with the port mappings (8080:8080
in this case).
Contributions are welcome! Please follow the guidelines in CONTRIBUTING.md. If you don't have this file, consider creating one with instructions for how to fork the project, make changes, and submit pull requests.
Biome
configuration files..github
folder to ensure all necessary details are included when submitting a pull request.This project is licensed under the MIT License. See the LICENSE file for more details by @MKAbuMattar.