Every analytics tool wants a subscription. And your data. I built Twiligent instead. YouTube stats. Instagram stats. One dashboard. Runs locally on your machine.
Code Style
How code in this repository reads. Every change follows it, so a file written today looks like the files around it. The detailed rules live in the guides linked from each section; this page is the one to read first and the checklist to run last.
When this page and the code disagree, the code in the newest reviewed files wins: fix this page in the same change.
The Short Version
- Match the nearest example. Before writing a file, open its closest sibling (the same layer, the same kind of component) and copy its shape: imports, exports, naming, comment density, error handling.
- One job per file and per layer. A route table maps, a controller translates HTTP, a service decides, a repository queries, a component renders, a
lib/helper computes. - Comments say why, in one lowercase line. Never what the code does.
- Failures are typed and written for people. Throw a typed error with a message that says what happened and what to do; never "Something went wrong".
- Strict TypeScript with erasable syntax. No
any, no enums,import typefor types,.tson relative imports. - Design tokens and shared components only in the UI. No hex or palette colours, no one-off cards.
- Tests describe behaviour in a sentence and live in
tests/, mirroring the source path. - No em dashes, en dashes, emoji or exclamation marks in code, copy, docs or commits.
Formatting
Prettier settings in .prettierrc.json and .editorconfig describe the layout; match the file you edit rather than reformatting it.
| Backend, scripts | Frontend, site | |
|---|---|---|
| Indentation | 4 spaces | 2 spaces |
| Quotes | single | single (JSX attributes use double) |
| Semicolons, trailing commas | yes | yes |
| Line length | up to about 120 columns; long JSX props go one per line | same |
Files and Imports
- One exported unit per file: a component, a hook, a service factory, a repository factory, a route table. Small helpers used only in that file stay unexported beside it.
- Names follow
docs/guidelines/NAMING.mdand the table indocs/guidelines/TYPESCRIPT.md(accountService.ts,PasswordSection.tsx,useChannelVideos.ts,use-mobile.ts). - Import order: packages first, then project modules. Backend files put every
import typeline after the value imports, as below; frontend files may keep a type import next to the value import from the same module.
import { NotConfiguredError, RateLimitedError, UpstreamError } from '../lib/errors.ts';
import { composeAuthEmails } from './email/authEmails.ts';
import { sendEmail } from './email/resendApi.ts';
import type { AuthEmail } from './email/authEmails.ts';
import type { EmailQuotaRepository } from '../repositories/emailQuotaRepository.ts';
- Backend and test imports are relative and end in
.ts. Frontend imports use@/forsrc/(no extension) and./for siblings; files that Node tests import use relative.tspaths only. - Pure logic that can be tested goes in a plain
.tsfile with no JSX (frontend/src/lib/passwords.ts,backend/services/email/authEmails.ts), so Node can run its test directly. scripts/has no dependencies. A rule a script shares with the Worker lives in an import-freebackend/lib/helper that the script imports by relative path (scripts/publish-scheduled.tsimports../backend/lib/scheduledPublishing.ts); that helper imports nothing at runtime. Seedocs/guidelines/TYPESCRIPT.md.
Comments
Write a comment only when the reason is not visible in the code: a constraint from outside (a provider's limit, a browser quirk), an invariant, or behaviour that would surprise a reader. One line, lowercase start, no full stop needed, placed above the line it explains.
// Supabase gives the whole hook call 5 seconds, so a slow send is abandoned before Supabase gives up on the Worker
const SEND_TIMEOUT_MS = 4000;
// a refused send increments nothing, so one address asking again and again cannot use up the day's allowance
Do not write comments that restate the code (// send the email), name the task or issue, describe callers, or document parameters (types do that). No JSDoc and no multi-line blocks. A module-level constant with a number in it nearly always needs its one-line reason.
Naming Inside Functions
- Event handlers in components:
handleSubmit,handleResend,handleSave. Mode-specific steps they call:submitLogin,submitReset. - Booleans read as questions or states:
loading,saving,isLogin,emailLimitReached,configured. - Lookups keyed by a union are typed records, not
switchchains, when each case is a value:const FAILURE_PREFIX: Record<LoginMode, string> = { ... }. - Functions that return a reason or
nullsay so:newPasswordProblem(password, confirmation): string | null.
Backend Patterns
The layers are in docs/architecture/backend/REQUEST_PIPELINE.md; the recipes are in docs/features/NEW_API_ENDPOINT.md and docs/guidelines/HONO.md. The shapes to copy:
| Layer | Shape | Example |
|---|---|---|
| Route table | const router = new Hono<AppEnv>(); router.post(path, ...middleware, ...controller) |
routes/authHookRoutes.ts |
| Controller | controller.createHandlers(validator, async c => { one service call; return c.json(... satisfies Type) }) |
controllers/settingsController.ts |
| Validator | parseX(fields: Fields): XRequest with the helpers in validators/fields.ts |
validators/authHookValidators.ts |
| Service | interface XService, interface XDeps, export function createXService(deps): XService returning an object literal |
services/authEmailService.ts |
| Repository | interface XRepository, createXRepository(client), one method per query, ...ForUser for user-scoped methods |
repositories/emailQuotaRepository.ts |
| Platform module | plain functions taking config and an optional trailing signal, throwing UpstreamError and UpstreamTimeoutError |
services/email/resendApi.ts |
- Services never import
hono. They receive repositories,AppConfigand theRequestContext, and log throughcontext.logwith a short lowercase message and fields:context.log.warn('auth email skipped', { action, reason: 'limit reached' }). - Every platform
fetchgetscontext.signal(plus its own timeout when the caller has a budget). - Redis code catches every failure and falls back; nothing else swallows errors, with two exceptions that log instead: a job that works through many items (the scheduled publisher, the reply processor, the token refresh) catches one item's failure and moves on, and a secondary step after the main write (subscribing an account when a rule is turned on) is logged with
context.log.warnso the main result still stands. - A platform call whose every failure leads somewhere different may answer a result union instead of throwing (
sendPrivateReplyreturns{ kind: 'accepted' | 'error' | 'ambiguous' | 'not_sent' }); the decision table lives in a purelib/helper (finishPlaninlib/automationDelivery.ts) with its tests. - Work after a response goes through
inBackground(c, label, work)incontrollers/http.ts, which gives it its own deadline, neverc.executionCtx.waitUntil()with the request's services. - The schema changes only through a migration in
supabase/migrations/(npm run db:new <verb>_<object>) with its reverse insupabase/rollbacks/under the same name, one database entity per file: a table (with its columns, keys and checks), its browser access, one trigger, one index or one function (a new table is at least four files; the test intests/database/migrations.test.tsrefuses a file that creates more); each migration and rollback opens with one plain sentence that says what it does (-- adds an index that lists a user's drafts newest first), andsupabase/schemas/is regenerated withnpm run db:schemaafter a push, never edited; a repository updatesdatathrough a merge function withdb.rpc(), never by reading and writing it back. Seedocs/features/NEW_DATABASE_TABLE.md. - New row ids come from
newRowId()inlib/ids.ts; tests pin them withmockRowIds()fromtests/fixtures/rowIds.ts. - No new runtime dependency in the Worker without approval: call HTTP APIs with
fetch(Resend is called this way, not through its SDK).
Errors and Messages
Messages are UI copy. Follow docs/WRITING_STANDARDS.md (UI Copy) and docs/guidelines/ERROR_HANDLING.md.
- Backend: throw the typed error whose code matches the failure (
ValidationError,NotFoundError,RateLimitedError,NotConfiguredError,UpstreamError), with a message a person can act on:'This address has received the most codes allowed today. Use the latest code you received, or try again tomorrow.'A missing secret names the secret:'Email sending is not set up: the RESEND_API_KEY and EMAIL_FROM Worker secrets are required'. - Frontend failures: a field the person can fix shows its message under the field through
FieldRow error; a request failure is a toast that starts with what failed and adds the reason:`Couldn't save the password. ${reason}`; a failed load showsErrorState, never an empty state. Seedocs/guidelines/ERROR_HANDLING.md. Map provider error codes to plain sentences in alib/helper (lib/authErrors.ts) and keep the provider's own message when it already says what to do. - Frontend success: confirm what happened in past tense, sentence case, no exclamation mark:
'Password saved','New code sent'. - Never reveal more than the user should know: the password reset message reads
If an account uses <email>, a code is on its way.because the server does not say whether the account exists.
Frontend Patterns
Rules in docs/guidelines/REACT.md, docs/guidelines/TAILWIND.md, docs/guidelines/SHADCN.md and docs/architecture/frontend/DESIGN_SYSTEM.md. The shapes to copy:
export interface LoginEmailFormProps {
copy: LoginCopy;
email: string;
onEmailChange: (value: string) => void;
loading: boolean;
onSubmit: (e: FormEvent<HTMLFormElement>) => void;
}
export default function LoginEmailForm({ copy, email, onEmailChange, loading, onSubmit }: LoginEmailFormProps) {
return (
<form onSubmit={onSubmit} className="flex flex-col gap-4">
<FieldRow label="Email" htmlFor="email">
<Input id="email" type="email" className="h-(--control-h-lg)" value={email} onChange={e => onEmailChange(e.target.value)} required />
</FieldRow>
<Button type="submit" size="lg" className="mt-2 w-full" disabled={loading}>
{loading && <Spinner className="size-4" />}
{loading ? copy.busy : copy.submit}
</Button>
</form>
);
}
- Presentational components get values and callbacks as props; the page or section owns state and calls
useAuth(),useAppContext()orapi. - Forms:
FieldRowfor label and hint, shadcnInputandButton,Spinnerin the button while busy, the action named for what it does (Save password,Send code). - Sections of a settings-style page use
SettingsSectionandSurfaceBox; pages usePageHeader; toasts go throughshowToastinside the app shell (the login page usestoastfromsonnerdirectly). - Icons are Lucide with
data-icon="inline-start"orinline-endin buttons. - When markup repeats in two places, extract it (
PasswordInput.tsxfor the password field with its show button) rather than copying it. - Copy that changes by mode lives in a typed table (
loginCopy.ts,LOGIN_COPY: Record<LoginMode, LoginCopy>). - The public site (
site/) follows the same React rules without shadcn: it has its own tokens insite/src/index.cssand uses the Solar icons from@/components/icons, never Lucide. Seedocs/architecture/site/SITE.md.
Tests
Rules in docs/workflows/TESTING.md.
node:testwithassert from 'node:assert/strict'; no other framework.- Test names are sentences about behaviour, not function names:
'past the daily cap nothing is sent and the error tells the person to use Google'. - One behaviour per test, with the smallest fake that exercises it, cast once to the interface it stands in for. Shared fakes and fixtures live in
backend/tests/fixtures/. - Every new pure helper, validator, service and route gets a test in the mirrored
tests/path.
Docs and Commits
- Docs follow
docs/WRITING_STANDARDS.md: short declarative sentences, tables for structured facts, code blocks for commands, no marketing words. - User and self-hosting docs are MDX pages in
site/content/docs/; engineering docs stay indocs/. Adding or moving a docs page is indocs/architecture/site/SITE.md. - Commits follow
docs/workflows/GIT.md:type(scope): imperative summary, a body that says why, andRefs #NorCloses #N. No AI attribution lines. - Every change is tracked by an issue (
docs/workflows/ISSUES.md) and lands onmainthrough a pull request that passed CI.
Before Every Commit
- The new file looks like its nearest sibling: imports, exports, naming, comments
- Interface changes pass the checklist in
docs/guidelines/UI_UX.md - Comments only explain why; no restated code, no task references
- Errors are typed (backend) or toasts with a reason (frontend), and every message says what to do
- No
any, enums,@ts-ignore, hex colours, emoji, em dashes or exclamation marks - Tests added in the mirrored
tests/path, with behaviour sentences as names -
npm run typecheck,npm run lint,npm testandnpm run buildpass - Docs in the Documentation Maintenance Policy updated in the same change