Files
jsonPrism/CLAUDE.md
T
2026-05-13 09:43:37 +07:00

8.2 KiB
Raw Permalink Blame History

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.json engines)
  • 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/vite plugin)
  • Tailwind CSS v4 (new @theme inline syntax in CSS, NOT tailwind.config.ts)
  • shadcn/ui New York style, neutral base, configured in components.json
  • ESLint v9 flat config + typescript-eslint v8
  • 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 uses plugin-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 uses tauri://drag-drop event via useTauriDragDrop

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 in src/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. Use unknown for JSON values and narrow with type guards. The only sanctioned any is in registry.ts for the heterogeneous record type — keep it there.
  • Type-only imports: import type { Converter } from './types'. Enforced by ESLint rule consistent-type-imports.
  • Use the @/* path alias for imports inside src/. 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.json and vi.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

  1. Create src/converters/myformat.ts exporting myFormatConverter (camelCase).
  2. Implement the Converter<MyFormatOptions> interface. Return errors as values.
  3. Add the format ID to the FormatId union in src/converters/types.ts.
  4. Register in src/converters/registry.ts (both CONVERTERS and ALL_FORMATS).
  5. Add formats.myformat label to BOTH src/i18n/locales/en.json AND src/i18n/locales/vi.json.
  6. If introducing a new parsing library, add it to vite.config.ts manualChunks.parsers so it splits cleanly.
  7. Update the format table in README.md and README.vi.md.
  8. Update docs/ROADMAP.md to mark the phase done.
  9. 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 defaultOptions to render a settings panel.
  • Don't use JSON.parse directly in components. Always go through parseJsonInput in src/lib/detect.ts so error positions surface uniformly.
  • CSV nested values: stringify nested objects as JSON by default (nestedStrategy: 'json'). The flatten strategy is alpha — keep it but don't make it default.
  • YAML force-quoting: js-yaml's forceQuotes only works in conjunction with quotingType. Leaving one undefined produces unquoted output. Tested.
  • GitHub Pages basename: production builds use base /jsonprism/. The router uses import.meta.env.PROD to switch basename. Do not hard-code.
  • Tailwind v4 dark mode: uses the new @custom-variant dark (&:is(.dark *)); syntax. The .dark class on <html> triggers all dark-mode variants. Don't add darkMode: '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.