Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 67 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Build & Development Commands

```bash
npm run build # Full build: types → i18n → tsup bundle
npm run build:types # TypeScript declarations only
npm run generate-i18n # Compile locale JSON into src/i18n/compiled-i18n.json
npm run lint # ESLint with Prettier integration
npm run format # Prettier formatting
npm test # Vitest in watch mode
npm run test:run # Single test run
npm run test:ui # Vitest UI
```

Run a single test file:
```bash
npx vitest run src/utils/base64.test.ts
```

## Architecture Overview

**qapp-core** is a React component library for building Qortal decentralized applications (q-apps). It provides hooks, components, and utilities for interacting with the Qortal Data Network (QDN).

### Global State Pattern

The library uses Zustand stores in `src/state/` for internal state management:
- `publishes.ts` - Resource download status tracking, peer info, caching
- `cache.ts` - Search results and resource data caching with TTL expiry
- `lists.ts` - List pagination state
- `auth.ts` - Authentication state

The `GlobalProvider` in `src/context/GlobalProvider.tsx` is the main entry point. Apps wrap their root with it, passing `appName` and `publicSalt` config. It wires up:
- Authentication (`useAuth`)
- Resource management (`useResources`)
- Persistent storage (`usePersistentStore`)
- Index management (`useIndexes`)

### QDN Resource Flow

Resources on QDN are identified by `{service, name, identifier}`. The typical flow:
1. `useResources` or `ResourceListDisplay` components search/list metadata
2. `useResourceStatus` tracks download progress from peers
3. Resources are fetched via `qortalRequest()` - a global injected by the Qortal browser

### Global Type Augmentation

`src/global.ts` declares the global `qortalRequest()` function and `QortalRequestOptions` union type. This provides TypeScript support for the ~100+ Qortal API actions. The types are in `src/types/qortalRequests/interfaces.ts`.

### Build Output

tsup bundles to ESM/CJS with externalized React/MUI peer deps. Type declarations are generated separately via `tsc`. The `global.d.ts` export provides ambient types for consumers.

### i18n

Locale JSON files in `src/i18n/locales/{lang}/` are compiled into a single `compiled-i18n.json` at build time. Add translations there, then run `npm run generate-i18n`.

## Key Exports

- `GlobalProvider`, `useGlobal` - Context setup and access
- `usePublish`, `useResources`, `useResourceStatus` - QDN resource operations
- `ResourceListDisplay`, `ResourceListPreloadedDisplay` - List rendering components
- `VideoPlayer`, `AudioPlayerControls` - Media components with QDN integration
- `addAndEncryptSymmetricKeys`, `decryptWithSymmetricKeys` - Encryption utilities
- `EnumCollisionStrength`, `hashWordWithoutPublicSalt` - Identifier hashing for privacy
Loading
Loading