Follow these instructions when working on SkyCrypt Frontend. Nested AGENTS.md files may add instructions for their directories. See CONTRIBUTING.md for setup and release policy.
- Read the code, configuration, and tests relevant to the task before editing. Preserve unrelated staged and unstaged work.
- Ask clarifying questions before starting non-trivial work when the request leaves a real choice open.
- Reuse existing helpers and components before introducing dependencies or abstractions.
- Update this file when project practices change, or when the user states a preference or corrects your approach in a way that should apply to future work. Add or update the rule without being asked and mention it in your report. Project rules go here, not in an agent's private memory, so every session and contributor sees them. Check instructions against the repository and link to existing documentation instead of repeating it. Keep machine-specific paths out of this file.
- SkyCrypt is a Hypixel SkyBlock profile viewer built with SvelteKit 2, Svelte 5, strict TypeScript, and Tailwind CSS 4. Production uses the Node adapter.
- Use Node 26 and pnpm 12, as required by
package.jsonand CI. Other runtimes and package managers are unsupported. Keeppnpm-lock.yamlin sync with dependency changes. - Install with
pnpm install. Copy.env.exampleto.envwithout overwriting an existing file. Never commit secrets or local environment files. - Profile data and end-to-end tests require the Go backend from the separate SkyCrypt-Backend repository. Newsroom uploads go to Cloudflare R2. See
.env.examplefor service URLs. - Database and authentication code use PostgreSQL, Drizzle, and Better Auth.
pnpm db:startstarts local PostgreSQL. Server startup applies migrations fromdrizzle/throughsrc/hooks.server.ts; builds skip migration execution.
| Location | Purpose |
|---|---|
src/lib/components/ |
Reusable UI and feature components; shared UI primitives live in ui/ |
src/lib/layouts/ |
Structural composition of components |
src/lib/sections/ |
Domain sections composed from layouts and components |
src/lib/shared/ |
Shared utilities, themes, API clients, and remote functions |
src/lib/server/ |
Server-only authentication, integrations, and database code |
src/lib/hooks/ |
Reusable Svelte hooks |
src/lib/types/ |
Shared TypeScript types |
src/context/ |
Reactive contexts and preferences |
src/routes/ |
SvelteKit routes and route-specific remote functions |
src/test-utils/ |
Shared test wrappers and helpers |
e2e/ |
Playwright user-flow tests |
drizzle/ |
SQL migrations and migration metadata |
static/ |
Public assets |
scripts/ |
Release and maintenance scripts |
- Compose components into layouts, then layouts into sections. Components must not depend on sections.
- Initialize global contexts in
src/routes/+layout.svelte. Keep request-specific user and session state out of shared server globals. - Use configured aliases such as
#lib,$ctx,$types,$ui, and$utils. Alias and SvelteKit configuration live invite.config.ts. - Write local and alias imports without
.js/.tsextensions or a trailing/index(#lib/server/db,./format). Keep the extension on.svelte.tsmodules so they aren't read as components. shadcn-managed files insrc/lib/components/ui/and Orval output keep their generated style.#libresolves through the Vite alias and the#lib/*TypeScript path, not only thepackage.jsonimport map, which needs exact file names. getHeadersinsrc/lib/shared/api/mutator/custom-instance.tsforwards every incoming request header to the backend. That is intended; don't strip headers or flag it in reviews.- Keep credentials and database access in server-only code. Treat every
PUBLIC_*environment variable as exposed to the browser. src/routes/api/internal/holds routes only the Go backend calls (API key verification and usage reporting), guarded bySERVER_API_TOKENthroughrequireBackendToken. nginx must never route/api/internalpublicly. The backend enforces API key rate limits, so Better Auth's own API key rate limiter stays disabled.- Log with evlog, never
console.*in server code (ESLint enforces this). Configure it inevlog.config.ts;src/hooks.server.tswires the hooks, Better Auth identity and drains. In a request, add context to the single wide event withlocals.log.set({ ... })instead of extra log lines. Outside a request uselogfromevlog:log.info("tag", "message"), orlog.error({ action: "domain.event", error })so HyperDX can filter onaction. Output is plain text in the Dokploy Logs tab and ships to HyperDX whenHYPERDX_OTLP_ENDPOINTis set (dev writes NDJSON to.evlog/logs, readable withpnpm exec evlog logs). Server traces (SvelteKit spans plus outgoingfetch) go to the same HyperDX endpoint throughsrc/instrumentation.server.ts, which readsprocess.envbecause it loads before the app;traceHandlerinsrc/hooks.server.tsputs the trace id on each request's wide event so HyperDX links logs to traces. Browser code logs withlogfromevlog/client(set up insrc/hooks.client.ts); warnings and errors post to/api/client-logs, an unauthenticated endpoint that sanitizes and rate limits input, so never trust or extend its payload without updatingsrc/lib/server/client-logs.ts.
The shiiyu.moe zone sits in front of everything. Its custom, transform and configuration rules live in Cloudflare, not in this repo. Confirm with the user before changing them.
- Clients may send
X-Known-Bot: trueon purpose: the backend then serves stored data instead of spending a Hypixel API key request. Don't strip or restrict it. Bot counts useX-Verified-Bot, which Cloudflare sets on every request, so clients can't spoof it. - Never block HTTP/1.x or allow only HTTP/3. Doing that once locked Googlebot out and hurt search rankings.
- Every page calls
/_app/remote/*, so a challenge or rate limit there breaks the site for real users. Change those rules with care. - Requests to
api.shiiyu.moewith anx-api-keyheader skip the bot rules; the backend checks keys and enforces rate limits. Bot Fight Mode is off for all ofapi.shiiyu.moe, because it challenged third-party integrations. - Our own tools must stay reachable without a browser:
logs,dokploy,u,arcane,drizzleandtinyauth(each has its own login, and MCP clients send no Referer), and the Umami endpoints that sky proxies (/api/send,/api/script.js,/api/recorder.js,/api/websites/*/recorder). Check them after any rule change. - Allow AI crawlers and AI search bots. Only block scrapers and SEO crawlers such as AhrefsBot.
- Don't add Cloudflare cache rules for
/_app/*, including/_app/remote/*. Caching them broke the site; nginx handles caching. - Do routing, redirects and caching in nginx (the GitOpsConfig repo,
nginx/conf.d), not in Traefik or Dokploy domain settings.
- Use Svelte 5 runes (
$state,$derived,$props) and snippets. Avoid legacy reactive declarations,export let, and slots in new code. - Use the Svelte MCP to get the latest svelte documentation and conventions. Use the async flag to get the latest SvelteKit documentation and conventions for async svelte and remote functions, as that is the default for this project (instead of +page.server.ts way of loading data).
- The project enables async Svelte compilation and SvelteKit remote functions. Use
--asyncwhen validating with Svelte MCP/CLI tooling. - Check official documentation before implementing: the Svelte MCP for Svelte and SvelteKit, the library's own docs (for example takumi, Better Auth, Cloudflare) and the Node 26 docs for server code. Prefer SvelteKit features, then Node 26 built-ins, then library features, then hand-written code. Context7 can lag behind official docs. Say which docs you checked when reporting.
- Use SvelteKit remote functions in
*.remote.tsfor new data loading and mutations instead of adding+page.server.ts. Migrate existing server route files only when the task calls for it. - Validate remote-function inputs and check authentication and authorization on the server. Follow nearby implementations, and check permissions in each protected mutation even when route guards or hidden controls restrict access.
- Use Tailwind utilities, the shared
cn()helper, and existing theme tokens and UI primitives. UI changes must work with a keyboard, show focus, adapt to screen size, and support existing themes. - Encode static images, animated ones included, as AVIF, not WebP or GIF.
- Name reusable Svelte components in PascalCase and utilities in camelCase; follow SvelteKit route naming and nearby feature-file conventions.
- Follow
.oxfmtrc.json: two spaces, double quotes, no trailing commas, sorted imports, and ordered Tailwind classes. Format only changed files. - Comment only what the code cannot say (a non-obvious reason, a gotcha, a security constraint) and keep comments to a minimum, only add a comment when its absolutely necessary. Don't restate what the code does. Also do not add comments for any changes, unless it adheres to the above rule.
- Never nest ternaries (ESLint enforces
no-nested-ternary). Useif/else, an early-returning helper, or a lookup object instead. - Use braces on
if/elseblocks. Skip them only for a short single-statement guard such asif (!user) return;.
- Posts and banners live in
src/lib/server/db/schema/content.schema.tsand are managed underadmin-dashboard/postsandadmin-dashboard/banners, gated by thecontent: ["manage"]permission. A published post keeps its live columns while edits autosave todraft; every publish writes apost_revision. - The editor is Edra, vendored in
src/lib/components/edra/(Tiptap v3). We own that code: edit it directly.getContentExtensions()is the server-safe schema and must stay free of.svelteimports; node names and attributes must match the editor's. - Store editor JSON and render it on the server with
renderContentinsrc/lib/server/rich-text.ts. CallassertValidContentbefore every save; it checks the schema and allows only safe links and embed hosts. Never render user content with the editor on public pages. - Show users with
UserChip(src/lib/components/misc/) andgetPublicProfiles(src/lib/server/public-profile.ts): the primary Minecraft account, with the Discord profile on hover or tap. Keep private fields out ofPublicProfile. - Live data uses
query.livewithwatch()fromsrc/lib/server/live.ts; callpublish()after changing posts or banners so open pages update.
- Do not manually edit Orval-generated API clients or schemas in
src/lib/shared/api/. Changeorval.config.ts, custom mutators, or the upstream API definition, then regenerate the relevant target. - Run
pnpm exec orval --project <target>forskycrypt,skycryptZod, orpatreon. SkyCrypt targets readhttp://localhost:8080/openapi.json; Patreon reads its configured upstream spec. Required services must be available. - Edit database schemas in
src/lib/server/db/schema/, then runpnpm db:generateand review the SQL and metadata indrizzle/. Do not rewrite applied migrations. pnpm auth:schemaregenerates the Better Auth schema fromsrc/lib/server/auth.ts. Review the generated changes and generate any required database migration separately.pnpm db:pushdirectly changes the configured database; use it only for local schema work. Commit migrations for schema changes. Drizzle CLI commands requireDATABASE_URLin the process environment.
| Command | Purpose |
|---|---|
pnpm dev |
Start Vite at http://localhost:5173 |
pnpm check |
Synchronize SvelteKit types and run Svelte/TypeScript diagnostics |
pnpm lint |
Check formatting, run ESLint, and run pnpm check |
pnpm exec oxfmt --write <files> |
Format selected files |
pnpm format |
Format the repository |
pnpm test |
Run both Vitest projects once |
pnpm exec vitest run --project server <file> |
Run a focused Node test |
pnpm exec vitest run --project client <file> |
Run a focused browser/component test |
pnpm test:coverage |
Run Vitest with V8 coverage |
pnpm test:e2e |
Run Playwright tests; starts or reuses the local dev server |
pnpm check:pages [baseUrl] [paths...] |
Load pages in Chromium; fail on console, CSP or HTTP errors |
pnpm build |
Create the production build |
pnpm preview |
Serve the build locally at http://localhost:4173 |
pnpm runbuild |
Start the built Node server |
- Add regression tests beside the code when behavior changes. Use
*.spec.tsfor Node tests and*.svelte.spec.tsfor browser/component tests. Reuse helpers fromsrc/test-utils/. - Only write tests that would catch a real bug: logic, parsing, edge cases, security checks, persistence and migrations, and user flows that broke before. Don't test that something renders, that a prop or class is applied, that a constant or lookup table has its current values, or how a library behaves. A test that has to change whenever the UI changes on purpose, without ever catching a regression, costs more than it saves. Delete such tests when you find them.
- Vitest has
serverandclientprojects invite.config.ts. The client project uses headless Chromium and requirespnpm exec playwright install chromium. Tests must make assertions;expect.requireAssertionsis enabled. - Run
pnpm lint, relevant tests, andpnpm buildfor code changes before submitting. For documentation-only changes, check formatting and the accuracy of referenced paths and commands. - Use the player
tiltedhoneyorRefractionwhen checking profile pages (in the browser); these profiles have populated data. - If a check needs the backend or the dev server and they aren't running, start them yourself instead of skipping the check:
go run main.goin the SkyCrypt-Backend checkout (it uses the Redis and Postgres containers) andpnpm devhere. Stop what you started when you're done. - After changing UI, routes, CSP, headers or third-party scripts, run
pnpm check:pagesagainst the running dev server (add paths for the pages you touched) and fix what it reports before calling the work done. Cloudflare blocks headless browsers on the public sites, so check those in the browser preview instead. - Gather evidence yourself instead of asking the user to paste it: CI logs with
gh run view <id> --log-failed, production logs and containers through the Dokploy MCP, errors and traces through the HyperDX (clickstack) MCP, and browser console output through the preview tools. Use theghCLI for GitHub; the GitHub MCP may be signed in to a different account. - For dependency upgrades, follow the
upgrade-depsskill in.github/skills/. - End-to-end tests run locally with the backend and its required API credentials; they are currently disabled in CI. A production build can also require backend access for prerendered data.
- Report which checks you ran, their results, and anything you could not run. Never report a skipped check as passing.
- Claude Code hooks in
.claude/settings.jsonenforce part of this: before a turn ends,pnpm lintruns on uncommitted changes and changes to UI, routes or headers prompt forpnpm check:pages. Everygit add,git commitandgit pushneeds the user's confirmation.
- Use Conventional Commits, for example
fix(theme): preserve contrast. The commit-message hook runs commitlint. - Before committing or pushing, ask whether the change goes directly on
devor on a new branch. The answer depends on the change, so never choose on your own. - Never stage changes (
git add,git mv,git rm) unless asked. The user stages after reviewing; rename or delete files with plainmv/rm. - Follow
.github/PULL_REQUEST_TEMPLATE.md: explain the problem and resulting behavior, link relevant issues, list verification, and include before/after screenshots for visible UI changes. Note migration or environment requirements. - Add a changeset with
pnpm changesetwhen the change belongs in the release changelog. Documentation-only agent guidance does not need one. - Changesets target
dev. Automation creates beta releases ondevand stable releases onprod. FollowCONTRIBUTING.mdfor promotion and changeset cleanup. Run release scripts only for an explicit release task. - Preserve applicable license notices. New contributions default to AGPLv3; brand assets listed in
NOTICEare proprietary (LICENSES/LicenseRef-SkyCrypt-Brand.txt).NOTICEis the authoritative list; mirror changes instatic/BRAND_ASSETS_LICENSE,REUSE.tomland the README list.