Blog made using Nestjs + Mikro-orm codebase(backend) containing real world examples (CRUD, auth (password based and oauth), advanced patterns, etc) and batteries included and ever-evolving
NOTE: Starting April 18,2022 , the repo has ditched most promises for observables. You can check the latest promised
version code at
commit
More on why observables are better than promises can be
read here
npx degit rubiin/ultimate-nest my-nest-app # or use the "Use this template" button
cd my-nest-app
pnpm install
cp env/.env.sample env/.env.dev
Then start the backing services, run migrations, seed and start the app. The full walkthrough is in
docs/getting-started.md.
Once running, Swagger is at http://localhost:3000/doc and the metrics dashboard at
http://localhost:3000/stats, which asks for SWAGGER_USER and SWAGGER_PASSWORD from the env file.
Scripts
Every script needs NODE_ENV (dev, prod, test or stage), which selects env/.env.<NODE_ENV>.
Command
What
pnpm start:dev
Start in watch mode
pnpm build / pnpm start:prod
Compile to dist/, run the build
pnpm start:hmr
Start with hot module replacement
pnpm test / pnpm test:cov
Unit specs, with coverage
pnpm test:e2e
E2E specs in test/, needs the services running
pnpm lint / pnpm format:check
oxlint and oxfmt
pnpm orm migration:create
Generate a migration from entity changes
pnpm orm migration:up / :down
Apply or roll back migrations
pnpm orm seeder:run
Run the seeders in src/common/database/seeders
The ORM CLI reads compiled entities from dist/, so run pnpm build first. justfile wraps these, for
example just migrate, just seed and just encryption. Run just to list them.
Configuration
Each integration has its own file in src/lib/config/configs with a Zod schema and a registerAs block, and
src/lib/config/config.module.ts loads them. Every variable is validated at startup, and the app refuses to
boot on a missing or malformed one. env/.env.sample lists every variable with a working local value, and
env/.env.<NODE_ENV> is the copy you run against. A blank value is not the same as an absent one: optional
integrations (Stripe, Sentry, Twilio, Minio, S3) reject a blank so a half-configured integration fails loudly
instead of silently doing nothing.
To drop an integration you do not need (for example Redis or Twilio), remove its config from
config.module.ts, its schema from config.validation.ts, and its variables from your env file. See
docs/config.md.
Project structure
ultimate-nest
├── env Env files: .env.sample (committed template), .env.<NODE_ENV> (yours, copy of it)
├── migrations MikroORM migrations
├── docs Guides, start with getting-started.md
├── test End to end specs
├── src
│ ├── main.ts Entry point
│ ├── common Shared code: database base classes, decorators, guards, pipes, DTOs, types
│ ├── entities MikroORM entities
│ ├── lib Standalone modules: config, mail, i18n, jwt, cache, casl, rabbit, ...
│ ├── modules Feature modules: auth, user, post, newsletter, chat, ...
│ ├── resources Static files: i18n, mail templates
│ └── _mocks_ Shared mocks for unit tests
└── dist Build output
A feature module in src/modules/<name> holds its controller, service, module, dto folder and colocated
*.spec.ts files.
Authentication
The API uses JSON Web Tokens. Send the access token on each request in the header
Authorization: Bearer <token>. Refresh tokens are single-use and rotated on POST /v1/auth/token/refresh,
and GET /v1/auth/sessions lists the devices a user is logged in on.
Deployment
scripts/deploy.sh drives the local stack in docker-compose.dev.yml: the app plus Postgres, Redis,
RabbitMQ and Mailpit. The app container builds, migrates and seeds itself on boot. ENV picks the env
file, dev by default.
./scripts/deploy.sh # start the stack, reusing the image already built
./scripts/deploy.sh build # rebuild the image, then start the stack detached
./scripts/deploy.sh logs # follow the build, migrate and seed output
./scripts/deploy.sh down # stop the stack, keeping the volumes
The source is baked into the image rather than mounted, so a code change needs build.
./scripts/deploy.sh services starts only the backing services, for running the app on the host.
docker-compose.yml is the production-style stack (Traefik, TLS, pgAdmin). It runs the dev image with
the source mounted and no migrate step, so it is not production ready.
