Skip to content
Stackyard

Contribute to Stackyard

Rules

Section titled “Rules”
  • One container. No extra services, no database.
  • No runtime dependencies. The frontend has no framework and no build step.
  • Server code is CommonJS. Frontend code is ES modules.

Open an issue first if a change needs a dependency or a build step.

Run locally

Section titled “Run locally”

Run the working tree with Docker Compose 2.23 or later:

docker compose -f docker-compose.dev.yml watch

It serves http://127.0.0.1:8701. A saved file reaches the container within a few seconds. A change under api/src or ui/widgets restarts it. A change to the Dockerfile, nginx or supervisord config rebuilds the image. Data is kept in .dev/.

Without Docker, start the API with npm start in api/, setting CONFIG_PATH, ICONS_PATH and WIDGETS_PATH=../ui/widgets. Serve ui/ with any server that proxies /api/ and /health to 127.0.0.1:3000, as nginx/dashboard.conf does.

Tests

Section titled “Tests”

A behaviour change ships with its tests. A bug fix ships with a test that fails without it.

cd api && npm test
cd ui/test && node --test

Playwright specs in e2e/ run against BASE_URL, default http://127.0.0.1:8730.

Pull request checks

Section titled “Pull request checks”

The checks CI runs are listed in CONTRIBUTING.md.

  • Do not edit CHANGELOG.md. List user-visible changes in the pull request description under Changelog, as - lines below a Keep a Changelog heading such as ### Fixed. Merging adds them to [Unreleased].
  • Write ?v=1 on new /css/ and /js/ imports. The release sets the real hash.
  • A new ui/js module needs two entries in tsconfig.frontend.json: the path and its ?v=* form.
  • Run Biome through npm run lint. A bare npx biome runs an unrelated package.