8.2 KiB
CLAUDE.md
Guidance for Claude (and other AI assistants) working on this repository.
Project context
JSONPrism is a client-side JSON converter web app. Single JSON input → many formats (JSONL, CSV, TSV, YAML, XML, TOML, RESX, Markdown table, SQL INSERT). Deployed to GitHub Pages; later wrapped in Tauri 2 as a desktop app.
The maintainer is Kokone (@poli0981). Audience: developer community on the open-source Discord server + YouTube viewers who watch indie/visual-novel gameplay and occasionally want a quick devtool.
Project phase: Phase 0 scaffold complete. Phase 1 polishes the four working converters and adds CodeMirror. Phase 2 implements XML/TOML/Markdown/SQL and the Tauri build. Phase 3 implements RESX.
Stack — exact versions matter
- Node.js 22.x LTS (minimum 22.0.0; enforced in
package.jsonengines) - React 19.x (uses new JSX transform,
use()hook, ref-as-prop) - TypeScript 5.7+ (strict mode;
verbatimModuleSyntax;erasableSyntaxOnly) - Vite 6.x (ES2022 target,
@tailwindcss/viteplugin) - Tailwind CSS v4 (new
@theme inlinesyntax in CSS, NOTtailwind.config.ts) - shadcn/ui New York style, neutral base, configured in
components.json - ESLint v9 flat config +
typescript-eslintv8 - Prettier 3.x with
prettier-plugin-tailwindcss
Do not propose downgrading or "modernizing" to deprecated patterns.
Tauri 2 desktop wrapper
JSONPrism is shipped as both a web app (GitHub Pages) and a native desktop app (Tauri 2 bundles). The same React UI runs in both contexts.
Runtime detection: isTauri() from src/lib/tauri.ts is the single source of truth. The web bundle never imports Tauri modules statically — they're behind dynamic imports gated by isTauri() so tree-shaking keeps web builds clean.
When to branch on isTauri():
- File dialogs: web uses hidden
<input type="file">; Tauri usesplugin-dialog - Save .zip: web uses Blob URL download; Tauri uses native save dialog +
plugin-fs.writeFile - Drag-drop from File Explorer / Finder: web uses
react-dropzone; Tauri usestauri://drag-dropevent viauseTauriDragDrop
Don't branch on isTauri() for things that work in both: clipboard, in-memory operations, the converters themselves. Keep the Tauri-specific code at the I/O boundary.
Adding a new Tauri-only command: declare in src-tauri/src/lib.rs with #[tauri::command], register in invoke_handler!, expose a typed wrapper in src/lib/tauri.ts using invoke(). Update the capability JSON if it needs new permissions.
Icon updates: edit src-tauri/icons/icon.svg (1024×1024 canvas) then run npm run tauri:icon. The generated PNG/ICO/ICNS files are gitignored — CI regenerates them per build.
Permission model: Tauri 2 uses capability files. Edits to src-tauri/capabilities/default.json change which APIs the main window can call. Default capability already grants dialog, fs (scoped to $HOME, $DOCUMENT, $DOWNLOAD, $DESKTOP), os, and shell:open.
Bundling: npm run tauri:build produces the platform bundle of whatever OS you're on. For cross-platform releases, push a v* tag — .github/workflows/release.yml matrix-builds for Windows, macOS Intel/ARM, and Linux.
Velopack note: PhantomMAC uses Velopack for .exe deltas; JSONPrism uses Tauri's native bundler instead. Don't mix the two — Tauri's bundler produces .msi + .exe (NSIS) for Windows which covers the same ground.
Code style — non-negotiable
- Pure functions for converters. Each converter is a pure, synchronous module implementing the
Converter<TOptions>interface insrc/converters/types.ts. No I/O, no DOM access, no global state. - Errors as values. Converters return
{ ok: true, output } | { ok: false, error }. Never throw across converter boundaries. - No
any. Useunknownfor JSON values and narrow with type guards. The only sanctionedanyis inregistry.tsfor the heterogeneous record type — keep it there. - Type-only imports:
import type { Converter } from './types'. Enforced by ESLint ruleconsistent-type-imports. - Use the
@/*path alias for imports insidesrc/. Don't write../../lib/utils. - Tailwind class order: rely on
prettier-plugin-tailwindcss— never hand-sort. - Don't fight the theme system. Use the CSS variables (
--color-prism-*,bg-background, etc.) instead of hard-coded hex. - i18n everything user-facing. Hard-coded English strings in components are a bug. Add to both
en.jsonandvi.json.
File layout — where things go
src/
├── app/ # Top-level App component + routes
├── components/
│ ├── ui/ # shadcn components — generated by CLI, don't hand-edit
│ ├── layout/ # Header, Footer, theme/language toggles
│ ├── converter/ # The workspace UI
│ └── common/ # Reusable bits not specific to converters
├── converters/ # ONE file per format. Self-contained.
├── hooks/ # React hooks
├── i18n/ # i18next setup + locales
├── lib/ # Pure utilities: detect, theme, sample, utils
├── pages/ # Route components
└── styles/ # globals.css ONLY — no per-component CSS files
If you find yourself wanting to add a new top-level folder, stop and reconsider.
Adding a new converter — checklist
- Create
src/converters/myformat.tsexportingmyFormatConverter(camelCase). - Implement the
Converter<MyFormatOptions>interface. Return errors as values. - Add the format ID to the
FormatIdunion insrc/converters/types.ts. - Register in
src/converters/registry.ts(bothCONVERTERSandALL_FORMATS). - Add
formats.myformatlabel to BOTHsrc/i18n/locales/en.jsonANDsrc/i18n/locales/vi.json. - If introducing a new parsing library, add it to
vite.config.tsmanualChunks.parsersso it splits cleanly. - Update the format table in
README.mdandREADME.vi.md. - Update
docs/ROADMAP.mdto mark the phase done. - Write unit tests (Phase 1+ when Vitest lands).
Pitfalls observed in the wild
- Don't put options inside the converter call signature. Options are passed separately so the UI can introspect
defaultOptionsto render a settings panel. - Don't use
JSON.parsedirectly in components. Always go throughparseJsonInputinsrc/lib/detect.tsso error positions surface uniformly. - CSV nested values: stringify nested objects as JSON by default (
nestedStrategy: 'json'). Theflattenstrategy is alpha — keep it but don't make it default. - YAML force-quoting: js-yaml's
forceQuotesonly works in conjunction withquotingType. Leaving one undefined produces unquoted output. Tested. - GitHub Pages basename: production builds use base
/jsonprism/. The router usesimport.meta.env.PRODto switch basename. Do not hard-code. - Tailwind v4 dark mode: uses the new
@custom-variant dark (&:is(.dark *));syntax. The.darkclass on<html>triggers all dark-mode variants. Don't adddarkMode: 'class'configs — that's v3 syntax.
Commands the maintainer actually runs
npm run dev # 99% of the time
npm run typecheck # before pushing
npm run lint # CI does this anyway
npm run build # to verify production output
Format check happens automatically via Prettier in CI. The maintainer typically uses WebStorm (JetBrains license), so Prettier and ESLint run on save.
Communication preferences
- Reply in Vietnamese unless the maintainer writes in English.
- Be direct. Skip unnecessary preamble.
- When proposing changes, show the diff or full file; don't just describe.
- Match the file-naming and patterns already established (
*Converter,useFoo, kebab-case for files, PascalCase for components). - The maintainer dislikes excessive emoji; reserve them for status indicators in docs (✅ 🔜 📋).
- When unsure between two equally-valid approaches, pick one and explain briefly — don't ask which the maintainer prefers unless it's a meaningful tradeoff.
Roadmap reference
See docs/ROADMAP.md for the canonical phase plan. Update it as work lands.