Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
129 lines (85 loc) · 4.37 KB

CONTRIBUTING.md

File metadata and controls

129 lines (85 loc) · 4.37 KB

Contributing

Thanks for your interest in contributing — this file explains how to work with the frontend (static site) and the Cloudflare Worker backend in this repository.

Project layout (short):

  • index.html, app.js, styles.css — frontend static UI and preview.
  • data/ — device and country presets (devices.js, countries.js).
  • worker/ — Cloudflare Worker source and config (wrangler.toml, package.json, src/).

Quick start — clone & branch

  1. Fork the repo on GitHub and clone your fork locally.
  2. Create a branch with a descriptive name, e.g. feat/add-device-preset or fix/svg-rendering.
git checkout -b feat/your-feature

Running the frontend (local)

The frontend is a static site — no build step required. Two quick options:

  • Open index.html in your browser.
  • Or run a simple static server from the project root:
# using npm package 'serve' (install globally or use npx)
npx serve .
# open http://localhost:3000

The UI loads presets from data/devices.js and data/countries.js.

Running the backend (Cloudflare Worker)

The worker lives in the worker/ folder and uses Cloudflare Wrangler. The worker code sends back SVG/PNG images generated by worker/src/*.js and uses @resvg/resvg-wasm for rasterization.

Prerequisites:

  • Node.js and npm
  • Cloudflare Wrangler CLI (npm install -g wrangler) or use npx wrangler

Typical workflow:

cd worker
npm install
# run locally (wrangler will emulate the Worker)
npm run dev
# or: npx wrangler dev

# deploy (requires Cloudflare account + secrets configured)
npm run deploy
# or: npx wrangler deploy

You can exercise the worker with the /generate endpoint. Example:

GET /generate?country=us&type=year&bg=000000&accent=FFFFFF&width=1179&height=2556

Tip: worker/wrangler.toml includes the main = "src/index.js" entry and a build.command used by Wrangler.

Editing data presets

  • data/devices.js: add or update device objects (name, width, height, dpi). Follow existing format and keep entries sorted when possible.
  • data/countries.js: timezone / country presets. Ensure ISO codes match the API usage.

When changing presets, verify the UI loads them and the preview renders correctly (open index.html).

Working on the worker code

  • Main entry: worker/src/index.js
  • Utilities: worker/src/timezone.js, worker/src/validation.js
  • SVG generation helpers: worker/src/svg.js and worker/src/generators/*.js

If you modify the worker, test locally via npx wrangler dev and validate responses (SVG or PNG) using curl or the browser. Example:

curl "http://127.0.0.1:8787/generate?country=us&type=year&width=1179&height=2556" --output sample.png

Tests

There is no centralized test runner configured in the repository currently. If you add tests, include a top-level test script in worker/package.json or a root package.json and document how to run them in this file.

Pull request checklist

  • Branch name describes the change (use feat/ / fix/ / docs/).
  • Description explains the problem and solution.
  • Small, focused commits with clear messages.
  • Update data/ or README.md if relevant.
  • If you touched the worker, verify npx wrangler dev and the /generate endpoint work.

How to file good issues

Use the issue templates in .github/ISSUE_TEMPLATE/ (Bug, Feature, Good First Issue). A high-quality issue usually includes:

  • Short title and description
  • Steps to reproduce or sample URL for the /generate endpoint
  • Expected vs actual behavior
  • Screenshots, logs, or example params

Suggested labels: good first issue, help wanted, area: frontend|worker|data|docs, difficulty: easy|medium|hard.

Code style & best practices

  • Keep changes small and focused.
  • Follow existing JS style (ES modules, descriptive names).
  • Add inline comments for non-obvious algorithmic code (especially in generators).
  • When editing SVG output, include visual examples/screenshots in the PR description.

Security & secrets

  • Do not commit API keys or Cloudflare secrets. Use Wrangler secrets for deployment.
# to set a secret
npx wrangler secret put MY_SECRET

Communication & Code of Conduct

Be respectful and follow CODE_OF_CONDUCT.md. If you have questions, open an issue and mention a maintainer.

Thank you

Thanks for helping improve LifeGrid — every contribution is appreciated.