Pegasus typescript template

Template for typescript, node.js projects in Pegasus. The template defines typescript settings, folder structure and testing setup.

TBD: to use on new project we could just copy the whole repo and "search and replace" typescript-template with the new projects name. - But maybe there is a cleaner method?

Setup

Set up your machine as described in dev-environment - setup.

Coding standards

Cases

For repositories, files and routes we use kebab-case. For variables and functions we use camelCase. For classes, types and interfaces we use PascalCase. For global constants we use SCREAMING_SNAKE_CASE.

Biome.js

Uses rules defined in biome.json for linting & formatting.

Husky

Uses git hooks to automatically lint & format on every commit. If you want to skip hooks to commit anything that's WIP, use the "-n" flag (--no-verify).

Run locally

Bare metal

We expect node.js v22. Run npm install before. Scripts that can be used bare metal:

npm run typecheck
npm run typecheck:dev
npm run test:unit

Docker

Option 1: run the app with dev-environment

Option 2: run the included test docker-compose:

Have docker and compose installed.
Create .env file in root of repo with content
```
ALICORN_NPM_TOKEN=<YOUR_TOKEN>
```
replace <YOUR_TOKEN> with an access token as described in dev-environment
Choose one of the Scripts to start docker compose:
- npm run test:docker (starts test:dev)
- npm run test:docker:sh (starts into interactive shell)

Inside the docker container you can also use following scripts:

npm run test (unit and integration tests)
npm run test:dev (watch and inspect/debug)
npm run test:integration
npm run coverage

Discussion points

src/global holds global plugins like redis currently
- was named src/plugins previously, but everything is a plugin in fastify, so too ambiguous in my opinion
- src/shared could be an alternative name like in vastproxy-ts
- other names?
Folderstructure is currently "by feature" and not "by type"
- I prefer "by feature"
- I know Philipp prefers "by type"
- see also: https://softwareengineering.stackexchange.com/questions/338597/folder-by-type-or-folder-by-feature
test naming scheme *.(unit|integration).test.ts
- could switch to *.test.(unit|integration).ts: test will stick together sorted alphabetically, but vscode default config would not detect them as test file.
- other naming other structure?
test location currently with source files
- alternative: rebuild src folder structure under test have tests there. Less clutter in src, but tests are more far away -> more cumbersome when doing changes where you have to adjust/add tests
integration tests use real redis, mongodb etc.
- that means integration tests can only be executed in docker-compose or other environments where real databases, etc. are configured
- we could instead always mock, so we could execute integration locally
  - more work
  - not testing the real thing

3.2 KiB Raw Blame History