localgrid is a client-side browser toolbox: a dashboard of small dev-utility widgets (Base64, JSON formatting, JWT tools, color conversion, hashing, etc.). React 19 + Vite + TypeScript + Tailwind v4 + Zustand. No backend, everything runs in the browser.
- No em dash (—) or en dash (–) as punctuation. Use a comma, period, or parentheses instead.
- Avoid these words and phrases: delve, leverage, seamless, seamlessly, boilerplate, furthermore, moreover, "in today's world", "it's not just X, it's Y".
- No emoji unless the user explicitly asks for them.
npm run devstart the dev servernpm run buildtypecheck (tsc -b) then buildnpm run linteslintnpm run format/npm run format:checkprettiernpm testrun the full vitest suite oncenpm run test:watchvitest watch mode
After any code change, run npx tsc -b --noEmit, npm run lint, and npm test.
src/widgets/<widget-id>/one folder per widget:definition.ts(registry entry: id, name, category, icon, size, lazy import),<Name>Widget.tsx(the component), a matching.test.tsx, and any pure logic split into its own.tsfile with its own.test.ts.src/widgets/registry.tsthe single list every widget must be added to.src/widgets/categories.tscategory labels and display order.src/dashboard/the grid, tabs, sharing.src/components/shared UI (Field,CopyButton,SegmentedControl,CodeEditor,ui/*primitives).src/widgets/useWidgetState.ts/useWidgetDirty.tsper-widget-instance state and "has unsaved content" tracking, used by nearly every widget.src/widgets/widgetData.tsuseWidgetDataandsanitizeWidgetData: persisted, shareable widget data.src/settings/the Settings dialog (General, Share).docs/widget-architecture.mdlayout vs widget data vs state, lifecycle, persistence and share format.docs/flow.mdFlow, wiring widgets together: model, data flow, loop guardrails, routing, settings and sharing.
- Widget component signature is always
({ instanceId, mode }: WidgetProps). - Persist widget state with
useWidgetState(instanceId, field, initial), not plainuseStateit survives tab switches and remounts. - Report dirtiness with
useWidgetDirty(instanceId, isDirty), comparing current state to the widget's own defaults. Never include widget data fields. - Use
useWidgetData(plus adataSchemaindefinition.ts) only for setup that is tedious to redo and then used passively, like World Clock cities; everything else stays onuseWidgetState. Seedocs/widget-architecture.md. - Use
cnfrom@/lib/utils(not the deprecated@/lib/cn) for conditional class names. - Reuse existing shared components (
Field,CopyButton,SegmentedControl,ErrorMessage,NumberField) instead of hand-rolling equivalents. - Colors come from the semantic tokens in
src/index.css(success,destructive,muted, etc.), not raw Tailwind palette classes, unless a widget has a real reason to deviate. - Async work (Web Crypto, etc.) goes through
useEffectplus acancelledflag, not a bare unhandled promise see HashGeneratorWidget.
- Use conventional commit message pattern
- Do not commit or open pull requests without explicit instruction.