Log in Sign up

florian42

MusicBox

Public

Like

Val Town is a collaborative website to build and scale JavaScript apps.

Deploy APIs, crons, & store data – all from the browser, and deployed in milliseconds.

Sign up now

Code

/

AGENTS.md

9/1/2025

Viewing readonly version of main branch: v37

View latest version

AGENTS.md

Repository Guidelines

Project Structure & Modules

main.tsx: React SSR HTTP handler (default export authHandler); session + bookmark logic and TIDAL API integration.
deno.json: Deno config (TS, JSX, lint rules, Val.town types).
test-artist.ts: Ad‑hoc script to inspect TIDAL artist relationships.

Build, Run, and Test

Format: deno fmt — apply repository formatting.
Lint: deno lint — run configured lint rules.
Type check: deno check main.tsx — validate types without running.
Ad‑hoc test: deno run --allow-net --allow-env test-artist.ts — exercises artist fetching (requires TIDAL env vars).
Val.town (optional): vt dev to run locally and vt deploy to publish if you use the Val.town CLI.

Coding Style & Conventions

JSX pragma: start React files with /** @jsxImportSource https://esm.sh/react */.
Imports: prefer ESM (npm: specifiers and HTTPS URLs). No Node require.
Naming: PascalCase for React components, camelCase for functions/variables, .tsx for JSX modules.
Formatting: accept deno fmt defaults; do not hand‑tweak style.

Testing Guidelines

Prefer Deno’s built‑in tests; name files *.test.ts or *.test.tsx.
Keep tests deterministic; mock network calls. Example: deno test --allow-none for pure unit tests.
For coverage (optional): deno test --coverage=cov && deno coverage cov.

Commit & PR Guidelines

Commits: use Conventional Commits (e.g., feat: add bookmark deletion, fix: handle missing artist rel).
PRs: include summary, rationale, affected routes, and any schema changes. Link related issues. Add screenshots of UI states when applicable.
Keep PRs small and focused; include deno fmt and deno lint clean runs.

Security & Config

Required env vars: TIDAL_CLIENT_ID, TIDAL_CLIENT_SECRET, MUSICBOX_PASSWORD.
Do not commit secrets. Use the minimal permissions flags (--allow-env, --allow-net) when running scripts.

Architecture Overview

Runtime: Deno; Platform: Val.town. Server responds by rendering React to HTML via renderToString.
Storage: Val.town SQLite via https://esm.town/v/std/sqlite with sessions and bookmarks tables.
HTTP: default export handles routes (/, /login, /logout, /bookmark, /bookmark/delete).