# IC Reactor LLM Manifest Purpose: compact routing context for AI agents and retrieval systems. For a longer task-oriented guide, read `llms-full.txt`. ## Project IC Reactor v3 is a TypeScript monorepo for building Internet Computer apps with typed canister calls, TanStack Query caching, React hooks, optional authentication helpers, runtime Candid parsing, and code generation. Repository: `https://github.com/B3Pay/ic-reactor` Docs: `https://ic-reactor.b3pay.net/v3/` Release posture: the published documentation and package manifests target the stable `@ic-reactor/core` v3.12.3 runtime release. ## Package Versions Runtime lane: - `@ic-reactor/core`: `3.12.3` - `@ic-reactor/react`: `3.12.3` - `@ic-reactor/candid`: `3.12.3` Codegen lane: - `@ic-reactor/codegen`: `0.13.1` - `@ic-reactor/cli`: `0.13.1` - `@ic-reactor/vite-plugin`: `0.13.1` Parser lane: - `@ic-reactor/parser`: `0.4.9` ## Canonical AI Entrypoints | File | Use | | --------------------------------------------- | ---------------------------------------------------------- | | `llms.txt` | Compact package/task routing manifest | | `llms-full.txt` | Copy-paste LLM guide with patterns, APIs, and verification | | `AGENTS.md` | OpenAI Codex repository instructions | | `CLAUDE.md` | Claude repository instructions | | `.github/copilot-instructions.md` | GitHub Copilot repository instructions | | `.cursorrules` | Cursor repository rules | | `skill-packages/ic-reactor-hooks/SKILL.md` | React hook/factory/generation guidance | | `skill-packages/ic-reactor-packages/SKILL.md` | Package ownership, generated files, verification | ## Package Ownership | Package | Owns | Start here | | ------------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- | | `@ic-reactor/core` | Framework-agnostic runtime: `ClientManager`, `Reactor`, `DisplayReactor`, `@tanstack/query-core` cache integration | `packages/core/src/`, `packages/core/README.md` | | `@ic-reactor/react` | React hook factories, query/mutation factories, `useActorMethod`, Internet Identity auth, and identity-attribute hooks | `packages/react/src/`, `packages/react/README.md`, `skill-packages/ic-reactor-hooks/SKILL.md` | | `@ic-reactor/candid` | Runtime Candid fetching/parsing adapters and dynamic reactors | `packages/candid/src/`, `packages/candid/README.md` | | `@ic-reactor/parser` | Rust/WASM Candid parser; one `.` entrypoint with browser/node conditional exports | `packages/parser/src/`, `packages/parser/README.md` | | `@ic-reactor/codegen` | Shared declaration/reactor/client generation pipeline used by CLI and Vite plugin | `packages/codegen/src/`, `packages/codegen/README.md` | | `@ic-reactor/cli` | `ic-reactor` executable and config schema | `packages/cli/src/`, `packages/cli/schema.json` | | `@ic-reactor/vite-plugin` | Vite `.did` watching, generation, local environment-cookie injection | `packages/vite-plugin/src/`, `packages/vite-plugin/README.md` | ## Task Routing | Task | Preferred reference | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | One-call React setup (reactor + hooks) | `defineReactor` in `packages/react/src/defineReactor.ts`, `skill-packages/ic-reactor-hooks/SKILL.md` | | Build a React canister integration | `packages/react/README.md`, `docs/src/content/docs/framework/react-setup.mdx` | | Choose inside-React vs outside-React APIs | `skill-packages/ic-reactor-hooks/SKILL.md`, `llms-full.txt` | | Add reusable query/mutation factories | `docs/src/content/docs/reference/factories/overview.mdx`, `skill-packages/ic-reactor-hooks/references/patterns.md` | | Add auth/login or identity attributes | `AuthenticationManager` + `createAuthHooks`, `IdentityAttributesManager` + `createIdentityAttributeHooks` in `packages/react/src/auth/`, `docs/src/content/docs/guides/authentication.mdx` | | Change generated hook output | `packages/codegen/src/`, then verify CLI/Vite consumers | | Configure Vite generation | `packages/vite-plugin/README.md`, `docs/src/content/docs/packages/vite-plugin.mdx` | | Configure CLI generation | `packages/cli/README.md`, `docs/src/content/docs/packages/cli.mdx` | | Work with unknown/runtime Candid | `packages/candid/README.md`, `docs/src/content/docs/packages/candid/index.mdx` | | Parse `.did` locally | `packages/parser/README.md`, `docs/src/content/docs/packages/parser/index.mdx` | ## Generated Boundaries Do not hand-edit generated artifacts unless the source of truth is generated docs or publish output and the change is intentional. Generated or transient paths include `dist/`, `.dfx/`, `.icp/`, `.mops/`, `target/`, `.next/`, `.astro/`, `*.tsbuildinfo`, generated canister declarations, and generated hook files. For codegen behavior, edit `packages/codegen/src/` instead of generated output. ## Verification By Change Type | Change | Minimum verification | | -------------------------- | ------------------------------------------------------------------------------------------------ | | Docs only | `pnpm format:check`, `pnpm check:ai-context`, `pnpm docs:build`, `pnpm docs:check-links` | | Skill/frontmatter/metadata | YAML/frontmatter parse check plus `pnpm format:check` | | AI context files | `pnpm check:ai-context` | | React hooks/factories | `pnpm --filter @ic-reactor/react test` | | Runtime core | `pnpm --filter @ic-reactor/core test` | | React auth | `pnpm --filter @ic-reactor/react test` | | Codegen/CLI/Vite output | `pnpm --filter @ic-reactor/codegen test` plus affected CLI/Vite checks | | Broad package change | `pnpm typecheck`, `pnpm exec tsc -b`, `pnpm build`, `pnpm test` | | Package exports/build output/module format | `pnpm verify:packages` | | Examples | `pnpm typecheck:examples`, `pnpm build:examples` | Notes: - `pnpm format:check` covers the whole repo. Exclusions are declared in one place, `.prettierignore`, which the pre-commit hook honours too. - `pnpm check:ai-context` is a CI gate: it asserts the package versions listed above match each `package.json` and that every `packages/*/llms.txt` exists. - `pnpm lint` is a CI gate. Run `pnpm build` first: the type-aware rules read core's emitted `.d.ts` through the workspace symlinks, and without a build they degrade to `any` and stop reporting. A new package needs a `tsconfig.typecheck.json` and an entry in `TYPECHECK_PROJECTS`. - `pnpm typecheck` runs each package's own `typecheck` script plus `e2e/`'s, so `src` **and** tests are covered. The root `tsconfig.json` is references-only, so `pnpm exec tsc --noEmit` at the root checks nothing. - `pnpm verify:packages` packs every publishable package, installs the tarballs outside the workspace, imports/requires each entry point in real Node, and runs `publint` + `attw`. In-repo consumers resolve through workspace symlinks, so this is the only check that sees the published artifact. - `pnpm build:examples` is a CI gate alongside `pnpm typecheck:examples`. `tsc` never loads a bundler, so a broken Vite/Next config type-checks clean; both Next.js examples were unbuildable while the type-check job stayed green. ## Inside React vs Outside React React hooks (`useActorQuery`, `.useQuery()`, `.useMutation()`, `.useSuspenseQuery()`, `.useInfiniteQuery()`) belong only in React components or custom hooks. Outside React, use imperative APIs: query `.fetch()`, `.prefetch()`, `.invalidate()`, `.getCacheData()`, mutation `.execute(args)`, or direct reactor methods such as `.fetchQuery()`, `.getQueryData()`, `.invalidateQueries()`, and `.callMethod()`.