Node API Skeleton

This is a repository meant to serve as a starting point if you want to start a TypeScript express API project with some common features already set up and best practices.

Status

Table of contents

1. Features
2. Folder structure
3. How to use
4. Docker
5. Linting
6. Testing
7. Coveralls

⚙️ Features

• Express
• TypeScript
• ts-node-dev
• Jest
• Cors
• Morgan
• Helmet
• Supertest
• ESLint
• Prettier
• Husky
• Github Actions
• Docker
• Open API

🔝

🗂️ Folder structure

.
├── .github/
│   └── workflows/
│       ├── ci.yml          # Continuous integration workflow
│       ├── coveralls.yml   # Coveralls workflow
│       ├── lint.yml        # Linting workflow
│       └── test.yml        # Testing workflow
├── .husky/                 # Husky configuration
│   ├── pre-commit          # Pre-commit hook    
│   └── pre-push            # Pre-push hook
├── coverage/               # Coverage report generated by Jest (folder is ignored by git)
├── dist/                   # Transpiler files (folder is ignored by git)
├── src/
│   ├── controllers/        # Controllers define functions that respond to various http requests
│   │   └── ...
│   ├── models/             # Models define the structure
│   │   └── ...
│   ├── routes/             # Routes define the endpoints of the API
│   │   ├── index.ts        # Index file that generates the prefix of the routes and imports all the routes
│   │   └── ...
│   ├── tools/              # Tools are used to generate the Open API documentation and health check
│   │   └── ...
│   ├── utils/              # Functions that are used in multiple places
│   │   └── ...
│   ├── app.ts              # Express app with middlewares and routes
│   ├── config.ts           # Configuration file
│   └── server.ts           # Server file that starts the app
├── test/
│   ├── __mocks__/          # Mocks for tests
│   └── ...                 # Tests
└── ...

🔝

💪 How to use

You can use this repository as a template by clicking on the Use this template button on the top right of the repository page and select the Create a new repository option. This will create a new repository with the same files and history as this one.

# Install dependencies
npm install

# Set up environment variables and fill in the values
cp .env.example .env
code .env # or vim or whatever you prefer

# Set up coveralls repo token
cp .coveralls.example .coveralls.yml
code .coveralls.yml # or vim or whatever you prefer

# Run the development server
npm run dev

# Production build
npm run build

# Run the production server
npm start

🔝

🐳 Docker

# Build the image
docker build -t {{some-name}} .

# Run the container
docker run -p 3000:3000 {{some-name}}

🔝

🔦 Linting

# Run Linter
npm run lint

# Run Formatter
npm run lint:fix

The linter will run automatically before every commit using Husky.

🔝

👾 Testing

# Run tests
npm run test

# Run tests and generate coverage report
npm run test:coverage

# Run coverage and send report to Coveralls
npm run test:coveralls

🔝

📊 Coveralls

If you have a coveralls account, and you have the project synchronized with coveralls, you can use it to generate the jest coverage and send it to coveralls.

The coverage report is generated by Jest and sent to Coveralls but first you need the repo_token variable in your .coveralls.yml file. The coverage report is generated automatically when you push to the repository, only if you have a coveralls repo token set up and a coveralls profile linked to your github account.

In case you do not want to use Coveralls, you must do the following:

• Delete the coveralls.yml github action workflow file from the .github/workflows folder.
• Remove the coveralls.example file from the root of the project.
  • Remove the .coveralls.yml file if you have already created it.
• Remove the test:coveralls script from the package.json file.
  • Remove the coveralls package if you have already installed it.

🔝