Scaffolding

✨ This workspace has been generated by Nx, a Smart, fast and extensible build system. ✨

Setup

Clone this repo and run yarn at the root to install this project's dependencies.

You can optionally install nx globally with npm install -g nx - if you don't, you'll just need to prefix the commands below with npx (e.g. npx nx serve frontend).

Database Setup

This project uses PostgreSQL. You'll need a running Postgres instance before starting the backend.

Option A — Docker (recommended for local dev):

docker run --name scaffolding-db \
-e POSTGRES_USER=postgres \
-e POSTGRES_PASSWORD=postgres \
-e POSTGRES_DB=[DB NAME HERE] \
-p 5432:5432 \
-d postgres:15

Option B — pgAdmin / existing Postgres install:

Create a new database (e.g. jumpstart) through pgAdmin or psql.

Configure connection strings:

Copy example.env to .env and fill in your credentials:

cp example.env .env

NX_DB_HOST=localhostNX_DB_PORT=5432NX_DB_USERNAME=postgresNX_DB_PASSWORD=postgresNX_DB_DATABASE=[DB NAME HERE]

Run migrations:

yarn migration:run

To generate a new migration after changing entities:

name=your_migration_name yarn migration:generate

Windows users: The name=... syntax above only works on Mac/Linux. On Windows, run set name=your_migration_name && yarn migration:generate in Command Prompt, or $env:name="your_migration_name"; yarn migration:generate in PowerShell.

To revert the most recent migration:

yarn migration:revert

Start the app

To start the development server run nx serve frontend. Open your browser and navigate to http://localhost:4200/. Happy coding!

Running tasks

To run just the frontend (port 4200):

nx serve frontend

To run just the backend (port 3000):

nx serve backend

To run both the frontend and backend with one command:

nx run-many -t serve -p frontend backend

Swagger

The backend can expose Swagger UI (built from an OpenAPI document via @nestjs/swagger) so you can browse and try HTTP routes without reading controller code first.

Turn it on: In .env at the repo root (copy from example.env), set SWAGGER_ENABLED=true. Restart the backend (nx serve backend), then open http://localhost:3000/api for the UI.

Turn it off: Unset SWAGGER_ENABLED or set it to false.

TL TODOS:

1. In apps/backend/src/main.ts, replace [YOUR_APP_NAME] and other [TL] strings, adjust .addTag() entries to match your controllers,
2. Add @ApiBearerAuth() onto the controller or handler for specifically protected routes. addBearerAuth() only states that the application supports authentication via HTTP Bearer in the Authorization header, it doesn't mark specific routes as protected. Learn more

Decorators to know as you add routes! (import from @nestjs/swagger):

• @ApiProperty() / @ApiPropertyOptional(): on top of DTO fields
• @ApiTags('Name'): on top of controllers to tag them to specific tags/features
• @ApiHeader({name: '...', description: '...'}): on top of individual methods or controllers to define custom headers that are expected as part of the requests to those methods/controllers
• @ApiResponse({ status: '...', description: '...' }): to define a custom HTTP response.
  • Prebuilt helpers (fixed status in the spec): @ApiOkResponse (200), @ApiCreatedResponse (201), @ApiNotFoundResponse (404), additional @Api*Response shortcuts

More Decorators.

Other commands

Run git submodule update --remote to pull the latest changes from the component library

When cloning the repo, make sure to add the --recurse-modules flag to also clone the component library submodule (e.g. git clone --recurse-submodules https://github.com/Code-4-Community/scaffolding.git for the scaffolding repo)