136 lines
3.7 KiB
Markdown
136 lines
3.7 KiB
Markdown
# Development guide
|
|
|
|
## Prerequisites
|
|
|
|
- **Node.js** ≥ 24
|
|
- **pnpm** ≥ 10 (`npm install -g pnpm@10`)
|
|
- **Docker** (for local infrastructure)
|
|
|
|
## Local setup
|
|
|
|
```bash
|
|
# 1. Clone the repository
|
|
git clone git@git.mifi.dev:mifi-ventures/dwellops-platform.git
|
|
cd dwellops-platform
|
|
|
|
# 2. Copy environment files
|
|
cp .env.example .env
|
|
cp apps/api/.env.example apps/api/.env
|
|
cp apps/web/.env.example apps/web/.env
|
|
|
|
# 3. Start local services (Postgres + Mailpit)
|
|
docker compose up -d
|
|
|
|
# 4. Install all workspace dependencies
|
|
pnpm install
|
|
|
|
# 5. Generate Prisma client
|
|
pnpm db:generate
|
|
|
|
# 6. Run initial migration
|
|
pnpm db:migrate:dev
|
|
|
|
# 7. (Optional) Seed with dev data
|
|
pnpm db:seed
|
|
|
|
# 8. Start dev servers
|
|
pnpm dev
|
|
```
|
|
|
|
## Dev Container (VS Code / GitHub Codespaces)
|
|
|
|
Open the repository in VS Code and click **Reopen in Container** when prompted,
|
|
or run the command palette → `Dev Containers: Reopen in Container`.
|
|
|
|
The container starts Postgres and Mailpit via Docker Compose.
|
|
On first create, `pnpm install` and `pnpm db:generate` run automatically.
|
|
|
|
All ports are forwarded: see `.devcontainer/devcontainer.json` for the full list.
|
|
|
|
## Running tests
|
|
|
|
```bash
|
|
# Unit + integration tests (all workspaces)
|
|
pnpm test
|
|
|
|
# Watch mode
|
|
pnpm --filter @dwellops/api test:watch
|
|
pnpm --filter @dwellops/web test:watch
|
|
|
|
# End-to-end tests (requires the web app to be running)
|
|
pnpm test:e2e
|
|
|
|
# Coverage report
|
|
pnpm --filter @dwellops/api test -- --coverage
|
|
```
|
|
|
|
## Storybook
|
|
|
|
```bash
|
|
# Run Storybook for the web app (includes packages/ui stories)
|
|
pnpm --filter @dwellops/web storybook
|
|
|
|
# Run Storybook for the UI package standalone
|
|
pnpm --filter @dwellops/ui storybook
|
|
```
|
|
|
|
## Database operations
|
|
|
|
```bash
|
|
pnpm db:generate # Re-generate Prisma client after schema changes
|
|
pnpm db:migrate:dev # Create and apply a migration (dev only)
|
|
pnpm db:migrate # Deploy pending migrations (CI/production)
|
|
pnpm db:push # Push schema changes without a migration (prototype only)
|
|
pnpm db:studio # Open Prisma Studio in the browser
|
|
pnpm db:seed # Seed the database with dev data
|
|
```
|
|
|
|
## i18n
|
|
|
|
```bash
|
|
# Aggregate component translations.json files into messages/<locale>.json
|
|
pnpm i18n:aggregate
|
|
```
|
|
|
|
Add new strings by editing `translations.json` files alongside components,
|
|
then running `pnpm i18n:aggregate`. Never hand-edit `messages/en.json`
|
|
for component-specific strings.
|
|
|
|
## Code quality
|
|
|
|
```bash
|
|
pnpm lint # ESLint + Stylelint
|
|
pnpm lint:fix # Auto-fix lint issues
|
|
pnpm typecheck # TypeScript across all workspaces
|
|
pnpm format # Prettier
|
|
pnpm format:check # Check formatting without writing
|
|
```
|
|
|
|
Pre-commit hooks run lint-staged automatically.
|
|
|
|
## Adding a new package
|
|
|
|
1. Create `packages/<name>/` with `package.json`, `tsconfig.json`, and `src/index.ts`.
|
|
2. Name the package `@dwellops/<name>`.
|
|
3. Extend `@dwellops/config/tsconfig/base.json` (or `node.json` / `react-library.json`).
|
|
4. Add a `workspace:*` reference in any consumer's `package.json`.
|
|
5. Add to root `tsconfig.json` references.
|
|
6. Run `pnpm install`.
|
|
|
|
## Adding a new route in apps/api
|
|
|
|
1. Create `src/modules/<feature>/<feature>.routes.ts`.
|
|
2. Implement thin route handlers — call services for business logic.
|
|
3. Register the routes in `src/app.ts`.
|
|
4. Write `<feature>.test.ts` alongside the routes.
|
|
5. Update Swagger schemas as part of the change.
|
|
|
|
## Adding a new page in apps/web
|
|
|
|
1. Create `src/app/[locale]/<path>/page.tsx` — thin page that delegates to a view.
|
|
2. Create `src/views/<FeatureName>View/` with the view component.
|
|
3. Create any new components in `src/components/` or `src/widgets/`.
|
|
4. Add translations to `translations.json` alongside each component.
|
|
5. Run `pnpm i18n:aggregate`.
|
|
6. Add Storybook stories for any new components/widgets.
|