39 lines
3.5 KiB
Markdown
39 lines
3.5 KiB
Markdown
# Repository Guidelines
|
||
|
||
## Project Structure & Module Organization
|
||
- `src/` holds the React client: `index.js` bootstraps the app, `PickupConfigEditor.js` manages form logic, and sibling files (`App.js`, `*.css`, `*.test.js`) live beside their concerns for easy discovery.
|
||
- `public/` contains the static shell served during development; only add files that must be copied verbatim into the build output.
|
||
- `server.js` is the Express + MQTT bridge that serves the built client, exposes `/api/iobroker/pickup-config`, and persists data to `config/pickup-config.json`.
|
||
- `config/` stores generated runtime state. Keep it writable but untracked so local credentials never leak.
|
||
- `build/` is created by `npm run build` and shipped by the Express server or Docker image; never edit files here manually.
|
||
- `docker-compose.yml`, `Dockerfile`, and `rebuildContainer.sh` encapsulate deployment; update them when server ports, env vars, or base images change.
|
||
|
||
## Build, Test, and Development Commands
|
||
- `npm install` – restore dependencies in `package.json`.
|
||
- `npm start` – launch the CRA dev server on port 3000 with live reload.
|
||
- `npm run build` – emit the production bundle into `build/`; run before `node server.js` or container builds.
|
||
- `npm test` – run React Testing Library suites in watch mode; append `-- --watch=false` in CI.
|
||
- `node server.js` – serve the prebuilt UI, REST API, and MQTT sync using values from `.env` (e.g., `MQTT_BROKER`, `MQTT_TOPIC`, `MQTT_USER`, `MQTT_PASSWORD`).
|
||
- `docker-compose up --build` – rebuild and start the containerized service, syncing the bundled UI and server.
|
||
|
||
## Coding Style & Naming Conventions
|
||
- Use 2-space indentation and Standard/Prettier-compatible formatting; rely on the CRA ESLint config (`react-app`, `react-app/jest`) for feedback.
|
||
- Favor functional React components with PascalCase filenames (`PickupConfigEditor.js`) and camelCase props/state keys.
|
||
- Keep config schema fields (e.g., `desiredWeekday`, `onlyNotify`) camelCase across client, API payloads, and MQTT messages.
|
||
- Prefer descriptive folder-local CSS files rather than global selectors; co-locate assets next to their component whenever possible.
|
||
|
||
## Testing Guidelines
|
||
- React Testing Library + Jest underpin `App.test.js`; add `<Component>.test.js` files alongside components to exercise rendering, validation, and MQTT payload shaping.
|
||
- Initialize helpers inside `setupTests.js` to keep suites lean.
|
||
- Aim for meaningful edge cases (blank config, duplicate IDs, toggling `onlyNotify`). Pull requests should demonstrate passing `npm test` output or CI logs.
|
||
|
||
## Commit & Pull Request Guidelines
|
||
- Follow conventional commits (e.g., `feat: add mqtt auth fields`, `fix: debounce config saves`) and keep subjects ≤72 characters.
|
||
- After every change, refresh `.commitmessage` with the final commit text and ensure it is staged (e.g., `git add -f .commitmessage`) so tooling can reuse it automatically.
|
||
- Reference issues or MQTT topics impacted inside the body, and describe user-visible changes plus verification steps.
|
||
- PRs must include: summary of API/UI changes, screenshots or JSON samples when modifying config shape, notes on new env vars, and confirmation that `npm test` and `npm run build` succeed.
|
||
|
||
## Security & Configuration Tips
|
||
- Store secrets in `.env`, not in version control; provide `.env.example` updates when new variables (ports, credentials) are introduced.
|
||
- The server writes to `config/pickup-config.json`; ensure the directory exists and has the correct permissions before deploying or running containers.
|