Skip to content

CLAUDE.md

Latest commit

 

History

History
123 lines (88 loc) · 4.3 KB

CLAUDE.md

File metadata and controls

123 lines (88 loc) · 4.3 KB

CLAUDE.md

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

Commands

# Install dependencies
npm install

# Build all packages (parallel)
npm run build

# Build all packages (sequential, use if parallel causes issues)
npm run build-serial

# Run all tests
npm test

# Lint
npm run lint

# Prettier check / format
npm run cs-check
npm run cs-format

# Run a single package's tests
cd packages/core && npm test

# Watch mode for a single package
cd packages/core && npm run test:watch

# Update snapshots
cd packages/snapshot-tests && npm run test:update

# Start the playground (interactive demo)
cd packages/playground && npm start

# Full sanity check (lint + build + test)
npm run sanity-check

Individual package builds output three module formats: build:cjs, build:esm, build:umd.

Architecture

This is an npm workspaces + Nx monorepo. All packages live under packages/ and are scoped as @rjsf/*.

Package roles

Package Role
@rjsf/utils Shared types, 80+ utility functions, schema helpers. No UI dependencies.
@rjsf/core Core Form component, Bootstrap 3 as default theme, withTheme() HOC.
@rjsf/validator-ajv8 AJV 8-based validator. Exported via customizeValidator().
@rjsf/snapshot-tests Shared snapshot test suite consumed by all theme packages.
Theme packages (@rjsf/mui, @rjsf/antd, @rjsf/chakra-ui, etc.) UI-library-specific implementations of fields, widgets, and templates.
@rjsf/playground Vite app importing all themes, used for manual testing and demos.
@rjsf/docs Docusaurus documentation site.

Registry pattern (the plugin system)

The Registry object is the core extension point passed to every field/widget/template:

Registry = {
  fields,        // Map of field type → Field component
  widgets,       // Map of widget name → Widget component
  templates,     // Layout/structural templates
  rootSchema,    // Root JSON Schema
  formContext,   // Arbitrary context object threaded to all components
  schemaUtils,   // Schema parsing & validation helpers
  translateString,
  globalFormOptions,
}

Override fields/widgets/templates per-form via props, or globally via withTheme().

Theme pattern

Every theme package follows the same structure:

  1. Imports withTheme from @rjsf/core
  2. Defines custom Templates, Widgets, and optionally Fields
  3. Calls withTheme({ templates, widgets, fields }) to produce a themed Form
  4. Exports: Form (default), Theme, Templates, Widgets

Field → Widget → Template hierarchy

  • Fields handle schema-level logic (ObjectField, ArrayField, MultiSchemaField for oneOf/anyOf, etc.)
  • Widgets handle individual input rendering (TextWidget, SelectWidget, CheckboxWidget, etc.)
  • Templates control structural/layout rendering (FieldTemplate, ArrayFieldTemplate, ButtonTemplates, etc.)

Fields select which widget to render based on schema type and ui:widget. Templates wrap the output for consistent styling.

Form rendering flow

  1. Caller provides schema, validator (required), formData, and uiSchema
  2. Form creates schemaUtils from validator + schema
  3. Schema is recursively decomposed into fields → widgets → templates
  4. On change/blur: callbacks fire with updated formData and errorSchema
  5. On submit: full validation runs, then onSubmit fires (or onError if invalid)

Key @rjsf/utils exports to know

  • Schema helpers: findSchemaDefinition, mergeSchemas, getSchemaType, createSchemaUtils
  • Form data: mergeDefaultsWithFormData, removeOptionalEmptyObjects
  • Error handling: toErrorSchema, toErrorList
  • Enum helpers: enumOptionsSelectValue, enumOptionsDeselectValue
  • React hooks: useDeepCompareMemo, useFileWidgetProps, useAltDateWidgetProps

Code style

  • TypeScript strict mode, ES2020 target
  • Prettier: single quotes, JSX single quotes, 120-char print width
  • ESLint: enforces semicolons, curly braces, no-console, React Hooks rules
  • Pre-commit hook (Husky + lint-staged) auto-formats and lints staged files

Testing

  • Vitest, jsdom, Testing Library
  • Snapshot tests in @rjsf/snapshot-tests are shared across theme packages — run test:update there when changing core rendering
  • Node >=20 required