|
| 1 | +# MikroORM: Getting started |
| 2 | + |
| 3 | +Read the full text on https://mikro-orm.io/docs/guide. |
| 4 | + |
| 5 | +## Introduction |
| 6 | + |
| 7 | +MikroORM is a TypeScript ORM for Node.js based on Data Mapper, Unit of Work, and Identity Map patterns. In this guide, you will learn what those words mean, how to set up a simple API project, how to test it, and many more. |
| 8 | + |
| 9 | +[This Getting Started Guide](https://mikro-orm.io/docs/guide) was written as a step-by-step tutorial, accompanied by working StackBlitz examples and a [GitHub repository with the final project](https://github.com/mikro-orm/guide). It will show you how to create a production-ready application from scratch, all the way down to a docker image you can deploy wherever you want. |
| 10 | + |
| 11 | +## The Stack |
| 12 | + |
| 13 | +The goal of this guide is to show off the most important features of MikroORM as well as some of the more niche ones. It will walk you through creating a simple API for a blog, with the following technologies: |
| 14 | + |
| 15 | +- [MikroORM](https://mikro-orm.io) with SQLite driver |
| 16 | +- [Fastify](https://www.fastify.io) as the web framework |
| 17 | +- [Vitest](https://vitest.dev) for testing |
| 18 | +- ECMAScript modules |
| 19 | +- JWT authentication |
| 20 | +- reflection via [ts-morph](https://ts-morph.com) |
| 21 | + |
| 22 | +## What are we building? |
| 23 | + |
| 24 | +We already mentioned what technologies will be used, and now more about the project. It will be a simple API for a blog, with authentication, publishing, and commenting. For that, we will use four regular entities: `User`, `Article`, `Comment`, and `Tag`. Later on, we will add one more entity, `ArticleListing`, a virtual entity represented by an SQL expression rather than a database table. |
| 25 | + |
| 26 | +And the API routes description: |
| 27 | + |
| 28 | +| Method | URL | Description | |
| 29 | +|----------|--------------------------|-----------------------------------| |
| 30 | +| `POST` | `/user/sign-up` | Register new user | |
| 31 | +| `POST` | `/user/sign-in` | Login existing user | |
| 32 | +| `GET` | `/user/profile` | Get your full profile info | |
| 33 | +| `PATCH` | `/user/profile` | Modify your profile | |
| 34 | +| `POST` | `/article` | Create new article | |
| 35 | +| `GET` | `/article` | List existing articles | |
| 36 | +| `GET` | `/article/:slug` | Get article detail | |
| 37 | +| `PATCH` | `/article/:slug` | Modify existing article | |
| 38 | +| `DELETE` | `/article/:slug` | Delete existing article | |
| 39 | +| `POST` | `/article/:slug/comment` | Post comment for existing article | |
| 40 | + |
| 41 | +The code will be structured into self-contained modules: `user`, `article`, and `common` (for shared helpers). |
| 42 | + |
| 43 | +The app will be using Node.js 20, TypeScript 5.2, and we will build it using a modern stack with ECMAScript modules enabled. |
| 44 | + |
| 45 | +## What will we cover |
| 46 | + |
| 47 | +Here is (an incomplete) list of features you will try going through this guide. |
| 48 | + |
| 49 | +- creating an app from scratch with TypeScript setup |
| 50 | +- folder-based discovery, ts-morph reflection, ES modules |
| 51 | +- request context management via middleware/fastify hook |
| 52 | +- entity relations, advanced entity definition (e.g. lazy scalar properties) |
| 53 | +- advanced type safety (e.g. `OptionalProps`, `Reference` wrapper and `Loaded` type) |
| 54 | +- events, including advanced use cases like soft-delete via `onFlush` event |
| 55 | +- basic testing via vitest |
| 56 | +- custom repositories |
| 57 | +- virtual entities |
| 58 | +- serialization |
| 59 | +- embeddables |
| 60 | + |
0 commit comments