A really simple boilerplate to build a REST API with authentication written in TypeScript and using Docker, Express, TypeORM and Passport
_{Made with ❤️ by Alex Le Boucher and contributors}

The main goal of this boilerplate is to setup an Express REST API and add common features like Docker containerization, database connection, authentication, error handling, etc.

Some basic routes for authentication and user creation are already implemented. They can be used to quickly start your project. More info about what is already implemented here.

End-to-end tests are already implemented. The code coverage is 100%.

Packages are frequently upgraded. You can easily see the packages version status here.

• Docker containerization to easily run your code anywhere and don't have to install tools like PostgreSQL on your computer.
• Authentication with Passport.
• Authentication session thanks to express-session and connect-pg-simple.
• Simplified Database Query managed by TypeORM.
• Simple but clear Structure with different layers like routes, controllers, entities, utils, middlewares, config, etc.
• Object-oriented database model with TypeORM entities.
• Integrated Testing Tool with Jest.
• E2E API Testing thanks to Supertest.
• Tests utils already implemented to simplify tests creation.
• Routes protection with custom middlewares.
• Exception Handling using http-errors.
• Basic Security Features with Helmet and cors.
• Configurated Code Linter with ESLint and common rules.
• Helpful logger with morgan.
• Migration generation based on entity changes thanks to TypeORM.
• Validation utils thanks to Validator.
• Transactions control with TypeORM.
• Entity events with TypeORM subscribers.

• Getting Started
• Scripts
• API Routes
• Project Structure
• Environment Variables
• Authentication
• Migrations
• Subscribers
• E2E Tests
• Logging
• Existing routes
• Common Errors
• Clean Github Templates and Workflows
• Upcoming Features
• Further Documentations
• Contributing
• License

You need to set up your development environment before you can do anything.

• on OSX use homebrew brew install node
• on Windows use chocolatey choco install nodejs

• Install Docker Desktop
• Run Docker Desktop

git clone https://github.com/jessyefuster/kraft
cd kraft
npm i

rm -rf .git (or rd /s /q .git on Windows) deletes the git info of the branch like history.

• on OSX run cp .env.example .env
• on Windows run copy .env.example .env

npm run docker:up
npm run dev

This starts a local server using nodemon, which will watch for any file changes and will restart the server according to these changes. The server will be running on http://0.0.0.0:8000 (or http://localhost:8000).

To test the server, you can query http://localhost:8000/api/health using Postman or just copy it in the address bar in your browser. If the server is running, you should receive Server is up! as response.

To create the user database table, you must run the migration. Run npm run migration:run to run the migration and create the table.

The project contains Github templates and workflows. If you don't want to keep them, you can easily delete them by following this section.

⚠️ Except Docker scripts, all the scripts must be executed in the api container shell.

• Run npm run docker:up to start the containers defined in docker-compose.yml. It automatically opens a shell in the api container. In this shell, you can run other scrips like npm run dev.
• Run docker:down to stop the running containers.
• Run docker:shell to open a shell in api container.
• Run docker:build to build an image of your API.

• Install all dependencies with npm run install.

• Run npm run dev to start nodemon with ts-node, to serve the app.
• By default, the server will be running on http://0.0.0.0:8000 (or http://localhost:8000).

• Run npm run build to build the project. The compiled files will be placed in build/.
• Run npm run start to run compiled project.
• Run npm run type-check to run type checking.

• Run npm run migration:run to run non-executed migrations.
• Run npm run migration:generate MigrationName to generate a migration based on entities changes.
• Run npm run migration:create MigrationName to create a empty migration.
• Run npm run migration:revert to revert the last migration. If you want to revert multiple migrations, you can run this command several times.

• Run code quality analysis using npm run lint. This runs ESLint and displays warning and errors.
• You can also use npm run lint:fix to run ESLint and fix fixable warning and errors.

• Run tests using npm run test.
• Run tests with coverage using npm run test:coverage.

The route prefix is /api by default, but you can change this in the .env file.

Passport.js is used to handle authentication. This is a flexible and modular authentication middleware that allows you to easily add new authentication strategies like login with Facebook, Google, Github, etc.

The Passport configuration and functions are located in src/config/passport.ts.

The serializeUser defines what data are saved in request session, generally we save the user id. The deserializeUser allows getting the whole user object and assigning it in req.user, so you can easily get the authenticated user with req.user. You don't need to explicitly call deserializeUser before calling req.user.

You can find the Passport docs here.

To protect a route, you can use auth middlewares located in src/middlewares/auth.ts.

To check if a user is authenticated before accessing a route, use isAuthenticated:

router.route('/logout').post(isAuthenticated, AuthController.logout);

To check if a user is not authenticated before accessing a route, use isUnauthenticated:

router.route('/login').post(isUnauthenticated, AuthController.login);

Thanks to TypeORM, you can easily manage your migrations. The executed migrations are stored in a table which allows TypeORM to know which migrations must be executed but also to revert migrations if you need.

⚠️ The migrations scripts must be executed in the api container shell.

To create a migration, run npm run migration:create MigrationName. It will create an empty migration in src/migrations. The migration file have two functions : up and down. up is executed when you run the migration. down is executed when you revert the migration.

To generate a migration based on entities' changes, run npm run migration:generate MigrationName, it will create a migration in src/migrations. The migration is automatically generated based on your entities compared to your actual database.

For example, you can try by adding a property firstName in the User entity:

@Column({ nullable: false, length: 20 })
firstName!: string;

Then, run npm run migration:generate AddFirstNameInUser, it will automatically generate a migration to create the new column.

To run the migrations that have not been executed yet, run npm run migration:run.

You can revert the last executed migration by running npm run migration:revert. If you want to revert multiple migrations, you can run this command several times.

Subscribers allow us to listen entity events like insert, update, delete, etc and execute a method before or after the event. They are defined in src/subscribers.

By default, a subscriber listens to all the entities but it's a good practice to listen to one entity by subscriber. To do that, use the function listenTo() and return the entity you want to listen with this subscriber.

The subscribers functions take 1 parameter called event. In this object, you can find several properties like the concerned entity, the connection object, the query runner or the manager.

If you need to query the database in a subscriber function, use the event manager or event query runner. Otherwise, it will not include the data not commited yet.

The subscribers functions can be async.

You can find more info about subscribers here.

End-to-end testing is a methodology used to test the functionality and performance of an application under product-like circumstances and data to replicate live settings. The goal is to simulate what a real user scenario looks like from start to finish.

In this project, Jest and supertest are used for the E2E tests.

They are located in __tests__/e2e/.

The actual coverage is 100%.

You can run the tests by running npm run test in the api container shell.

If you want to see the tests' coverage, you can run npm run test:coverage.

If you want to run only one test file, you can add the name or path of the file after the command. For example, use npm run test auth to run only the auth tests.

To create new tests, you can add tests in an existing test file or create a new test file.

Before all your tests, you need to create the test server:

let server: Server;

beforeAll(async() => {
    server = await createTestServer();
});

And after all your tests, you must close the database connection and the test server:

afterAll(async () => {
    await closeDatabase();
    server.close();
})

Then, you can create a test suite by using describe function.

It is strongly recommended to clean the database after each test to prevent data issues and duplicates:

afterEach(async () => {
    await clearDatabase();
});

Then, you can create a test by using test function.

To test a route, you need to use supertest:

const res = await request(server).get('/api/auth/authenticated');

To test a route as an authenticated user, use the createAuthenticatedAgent function:

const agent = await createAuthenticatedAgent(server);
const res = await agent.get('/api/auth/authenticated');

Agents allow maintaining a session between multiple requests.

To check values, you must use expect function:

expect(res.statusCode).toEqual(200);

You can find more info about Jest here.

You can find more info about supertest here.

Some utils have been created to easily create new tests. They are located in __tests__/utils/.

This function creates a test server. You can change the port, prevent the database connection or override Express.

This function closes the database connection.

This function clears the database data.

This function creates an authenticated agent. Agents allow maintaining a session between multiple requests. You can customize agent user information.

This function creates a user and inserts it in the database. You can customize the user information.

To log HTTP requests, we use the express middleware morgan. You can easily configure it by passing a predifined format as parameter in src/config/express.ts.

Example:

app.use(morgan('short'));

Some basic routes are already implemented. Feel free to use, update or delete them at your conveniance.

You can create a user by using the POST route /api/users. The query body must contain a username, an email and a password. The username must contain at least 5 characters, the email must be valid and the password must contain at least 8 characters. The user's password is encrypted.

You can login by using the POST route /api/auth/login. The query body must contain a login and a password. The login can be the email or the username of the user.
You can access this route only if you are unauthenticated.

You can logout with the POST route /api/auth/logout. You can access this route only if you are authenticated.

You can get your authentication status by using the GET route /api/auth/authenticated. If you're authenticated, it will send You are authenticated as response. Otherwise, it will send You are not authenticated.

If you encounter an error when running npm run docker:up, make sure Docker Desktop is running.

If you encounter an error when running a script, make sure you ran the script in the api container shell.

If you don't want to keep the issue templates, you can delete the folder ISSUE_TEMPLATE in .github folder.

If you don't want to keep the Pull Request template, you can delete the file pull_request_templace.md in .github folder.

There are 3 workflows:

1. The workflow pull-request concerns the pull requests. It checks linting, build, runs E2E tests and sends the coverage to Codecov. If you don't want to keep it, you can delete the file pull-request.yml in the folder workflows in .github.

2. The workflow main-tests is triggered when code is merged or pushed on main. It runs the E2E tests and sends the coverage to Codecov. It has coverage for the main branch. If you don't want to keep it, you can delete the file merge-main.yml in the folder workflows.

If you want to keep the tests on pull request but don't want to use Codecov, you can delete merge-main.yml and only delete the 4 last lines in pull-request.yml. You can also delete codecov.yml. Its only goal is to fail the Pull Request tests if the code coverage is not 100%.
But if you want to use CodeCov, the only thing you need to do is set your CODECOV_TOKEN in you github secrets.

3. The workflow main is triggered when something is merged or pulled on main. It builds the project and its primary goal is to check if main is building. If you don't want to keep it, you can delete the file main.yml in the folder workflows.

This repository contains CONTRIBUTING, CODE_OF_CONDUCT and LICENSE files, you can delete them too.

You can see the upcoming or in progress features here.

Anyone and everyone is welcome to contribute.

If you want to propose new features, fix a bug or improve the README, don't hesitate to open a pull request. If your changes concern new feature or bugfix, please open an issue before.

However, if you decide to get involved, please take a moment to review the guidelines.

MIT