A progressive Node.js framework for building efficient and scalable server-side applications.

Description

Nest framework TypeScript starter repository.

Item Management System (XYRIC)

This repository contains a NestJS backend for an Item Management System using MikroORM and PostgreSQL. This README provides step-by-step baby steps to get the project running locally on Windows PowerShell, how to run migrations and seeders, and troubleshooting tips.

Table of contents

• Project overview
• Prerequisites
• Quick start (PowerShell)
• Environment variables
• Scripts (npm)
• Migrations (MikroORM)
• Seeders
• Building for production
• Common troubleshooting
• Contributing
• License

Project overview

Backend built with:

• NestJS (TypeScript)
• MikroORM (PostgreSQL)
• Swagger for API docs

The MikroORM configuration lives at src/mikro-orm.config.ts. Migrations and seeders are configured to run from dist/ in production, and from src/ during development when using TypeScript paths.

Prerequisites

• Node.js (16+ recommended)
• npm (or yarn) — this README uses npm commands
• PostgreSQL database
• PowerShell (you're using Windows PowerShell by default)

Quick start (PowerShell)

1. Clone repository

git clone <your-repo-url>
cd item-managment-system

2. Install dependencies

npm install

3. Create .env from template and fill values

Create a file named .env in the project root with the following keys (example values):

# application
PORT=3000

# database
DB_NAME=xyric_db
DB_USERNAME=postgres
DB_PASSWORD=postgres
DB_PORT=5432
HOST=localhost

4. Start the app in development mode

npm run start:dev

Open http://localhost:3000/v1/api (or replace 3000 with your PORT) to reach the API. Swagger UI is available at /api (e.g. http://localhost:3000/api).

Environment variables

• PORT - port used by the server (default in .env example is 3000)
• DB_NAME - Postgres database name
• DB_USERNAME - Postgres user
• DB_PASSWORD - Postgres password
• DB_PORT - Postgres port (usually 5432)
• HOST - Postgres host

Keep secrets out of source control. Use a .env.local or environment secrets in CI/CD.

Scripts (npm)

Key scripts in package.json:

• npm run start — start production server (expects dist/ compiled files)
• npm run start:dev — run NestJS in watch mode (development)
• npm run build — compile TypeScript
• npm run lint / npm run lint:fix — linting
• npm run migration:create — create a migration file
• npm run migration:up — apply pending migrations
• npm run migration:down — revert last migration
• npm run migration:list — list migrations
• npm run seed:run — run seeders
• npm run seed:create — create a seeder

Note: when passing arguments to npm scripts, use -- to forward arguments. Example:

# create migration named CreateItemsTable
npm run migration:create -- -n CreateItemsTable

# create a seeder named MySeeder
npm run seed:create -- -n MySeeder

Migrations (MikroORM)

This project uses MikroORM migrations. Two common flows:

Option A — Build then run migrations (recommended for production):

npm run build
npm run migration:up

Option B — Run migrations directly in development with ts-node (if you have ts-node registered in your CLI settings):

# forward args to the CLI
npm run migration:create -- -n AddNewColumnToItems
npm run migration:up

Important notes:

• The mikro-orm CLI reads mikro-orm.config.ts from src/ (this project kept its config at src/mikro-orm.config.ts). If the CLI cannot find the config, ensure your current working directory is the project root.
• Generated migration files will appear under src/database/migrations (TypeScript) and dist/database/migrations (compiled JS).

Seeders

Seeders are found in src/database/seeders and configured in src/mikro-orm.config.ts.

Create a new seeder:

npm run seed:create -- -n ItemSeeder

Run seeders:

npm run build
npm run seed:run

If you prefer running seeders during development without building, ensure your seeder class and the mikro-orm CLI are able to load TypeScript seeder files.

Building for production

1. Build the app

npm run build

2. Run migrations (on the compiled dist/ code)

npm run migration:up

3. Start the server

npm run start:prod

Common troubleshooting

• Error: Missing PORT or DB environment variables

  • Ensure .env exists and values are set. Restart terminal if you changed system env variables.

• MikroORM cannot find config or entities

  • Make sure src/mikro-orm.config.ts exists and paths in entities/entitiesTs match your project structure.
  • When running migration commands without building, confirm the CLI can load TypeScript config (sometimes you need ts-node/register). Building then running migrations is the simplest option.

• TypeScript compile errors when starting

  • Run npm run build to view compile-time errors. Fix types or missing imports the compiler highlights.

• Port already in use

  • Either choose a different PORT in .env or stop the process using that port.

• nest command not found / script fails

  • Ensure devDependencies are installed. If using global Nest CLI, npm i -g @nestjs/cli (optional).

If you still see an error when running npm run start:dev, copy the terminal stack trace and open an issue or paste it here for help — include the first 20 lines of the error and the file/line the stack points to.

Contributing

• Make a fork and open a pull request
• Keep commits small and focused
• Run npm run lint and npm run test before submitting

License

This repository uses the license in package.json (UNLICENSED). Change this file if you intend to open-source the project.

---

If you'd like, I can also:

• add a .env.example file to the repo with the variables shown above
• add a tiny Makefile/PowerShell script to simplify build/migrate/seed steps
• run the project in the terminal to capture the original startup error you reported

Tell me which of the extras you'd like me to do next.