Skip to content

AGENTS.md

Latest commit

 

History

History
160 lines (116 loc) · 6.46 KB

AGENTS.md

File metadata and controls

160 lines (116 loc) · 6.46 KB

🤖 Codex Agent Guidelines for thirdweb-dev/js

Welcome, AI copilots! This guide captures the coding standards, architectural decisions, and workflow conventions that every automated agent (and human contributor!) must follow. Unless a rule explicitly targets a sub‑project, it applies repo‑wide.

⸻

1. GitHub Workflow & Etiquette

  • Pull‑request titles must start with the affected workspace in brackets (e.g. [SDK], [Dashboard], [Portal], [Playground]).
  • Begin the PR description with a one‑sentence summary, then add a checklist of changes and reference issues with Fixes #123.
  • Keep commits small and topical – one logical change per commit.
  • Branch names should follow area/brief-topic (e.g. sdk/fix-gas-estimate). Avoid personal names.
  • Request at least one core maintainer review. Do not self‑merge unless you are the sole owner of that package.
  • All CI checks (type‑check, Biome, tests) must pass before merging.

⸻

2. Formatting & Linting

  • Biome governs formatting and linting; its rules live in biome.json.
  • Run pnpm fix & pnpm lint before committing, make sure there are no linting errors.
  • Avoid editor‑specific configs; rely on the shared settings.
  • make sure everything builds after each file change by running pnpm build

⸻

3. TypeScript Style Guide

  • Write idiomatic TypeScript: explicit function declarations and return types.
  • Limit each file to one stateless, single‑responsibility function for clarity and testability.
  • Re‑use shared types from @/types or local types.ts barrels.
  • Prefer type aliases over interface except for nominal shapes.
  • Avoid any and unknown unless unavoidable; narrow generics whenever possible.
  • Choose composition over inheritance; leverage utility types (Partial, Pick, etc.).

⸻

4. Testing Strategy

  • Co‑locate tests: foo.ts ↔ foo.test.ts.
  • Use real function invocations with stub data; avoid brittle mocks.
  • For network interactions, use Mock Service Worker (MSW) to intercept fetch/HTTP calls, mocking only scenarios that are hard to reproduce.
  • Keep tests deterministic and side‑effect free; Vitest is pre‑configured.
  • to run the tests: cd packages thirdweb & pnpm test:dev <filename>

⸻

5. packages/thirdweb

5.1 Public API Surface

  • Export everything via the exports/ directory, grouped by feature.

  • Every public symbol must have comprehensive TSDoc:

  • Include at least one @example block that compiles.

  • Tag with one custom annotation (@beta, @internal, @experimental, etc.).

  • Comment only ambiguous logic; avoid restating TypeScript in prose.

    5.2 Performance

  • Lazy‑load heavy dependencies inside async paths to keep the initial bundle lean:

const { jsPDF } = await import("jspdf");

⸻

6. apps/dashboard & apps/playground

6.1 Core UI Toolkit

  • Import primitives from @/components/ui/_ (e.g. Button, Input, Select, Tabs, Card, Sidebar, Badge, Separator).

  • Use NavLink for internal navigation so active states are handled automatically.

  • Group feature‑specific components under feature/components/_ and expose a barrel index.ts when necessary.

    6.2 Styling Conventions

  • Tailwind CSS is the styling system – no inline styles or CSS modules.

  • Merge class names with cn() from @/lib/utils to keep conditional logic readable.

  • Stick to design tokens: backgrounds (bg-card), borders (border-border), muted text (text-muted-foreground), etc.

  • Expose a className prop on the root element of every component for overrides.

    6.3 Component Patterns

  • Server Components (run on the Node edge): -- Read cookies/headers with next/headers. -- Access server‑only environment variables or secrets. -- Perform heavy data fetching that should not ship to the client. -- Implement redirect logic with redirect() from next/navigation. -- Start files with import "server-only"; to prevent client bundling.

  • Client Components (run in the browser): -- Begin files with 'use client'; before imports. -- Handle interactive UI relying on React hooks (useState, useEffect, React Query, wallet hooks). -- Access browser APIs (localStorage, window, IntersectionObserver, etc.). -- Support fast transitions where data is prefetched on the client.

    6.4 Data Fetching Guidelines

  • Server Side -- Always call getAuthToken() to retrieve the JWT from cookies. -- Inject the token as an Authorization: Bearer header – never embed it in the URL. -- Return typed results (Project[], User[], …) – avoid any.

  • Client Side -- Wrap calls in React Query (@tanstack/react-query). -- Use descriptive, stable queryKeys for cache hits. -- Configure staleTime / cacheTime based on freshness requirements (default ≥ 60 s). -- Keep tokens secret by calling internal API routes or server actions.

    6.5 Analytics Event Reporting

  • When to create a new event
    -- Only add events that answer a clear product or business question.
    -- Check src/@/analytics/report.ts first; avoid duplicates.

  • Naming conventions
    -- Event name: human-readable phrase in the form <subject> <verb> (e.g. "contract deployed").
    -- Reporting function: report<Subject><Verb> (PascalCase).
    -- All reporting helpers currently live in the shared report.ts file.

  • Boilerplate template
    -- Add a JSDoc header explaining Why the event exists and Who owns it (@username).
    -- Accept a single typed properties object and forward it unchanged to posthog.capture.
    -- Example:

/**
 * ### Why do we need to report this event?
 * - Tracks number of contracts deployed
 *
 * ### Who is responsible for this event?
 * @jnsdls
 */
export function reportContractDeployed(properties: {
  address: string;
  chainId: number;
}) {
  posthog.capture("contract deployed", properties);
}
  • Client-side only: never import posthog-js in server components.
  • Housekeeping: Inform #eng-core-services before renaming or removing an existing event.

⸻

7. Performance & Bundle Size

  • Track bundle budgets via package.json#size-limit.
  • Lazy‑import optional features; avoid top‑level side‑effects.
  • De‑duplicate dependencies across packages through pnpm workspace hoisting.

⸻

8. Documentation & Developer Experience

  • Each change in packages/* should contain a changeset for the appropriate package, with the appropriate version bump

    • patch for changes that don't impact the public API
    • minor for any new/modified public API

  • Surface breaking changes prominently in PR descriptions.

  • For new UI components, add Storybook stories (*.stories.tsx) alongside the code.