GO — Healthy across all four use cases

• 34+ active contributors
• Distributed ownership (top contributor 11% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 1y ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Recoil is an experimental state management library for React that provides fine-grained reactivity and atom-based state, solving the difficulty of managing complex, shared application state that React alone doesn't handle well. It enables efficient re-rendering by letting components subscribe only to the atoms and selectors they depend on, rather than relying on context or prop drilling. Monorepo structure with packages-ext/recoil-devtools (browser dev tools plugin), src/ containing core state logic, and multiple build outputs (umd, es, cjs, native) via rollup. Flow types throughout, ESLint+Prettier for code quality, relay-compiler for GraphQL integration via recoil-relay and recoil-sync packages.

React developers (16.13.1+) building medium-to-large applications who need flexible, composable state management with derived state (selectors), async queries, and fine-grained subscriptions—especially those avoiding Redux boilerplate or context prop-drilling hell.

Recoil is stable and actively maintained but still marked experimental. The repo shows clear CI/CD via GitHub Actions workflows (nodejs.yml, nightly.yml), comprehensive test suites (jest.config.js), Flow and TypeScript type coverage, and recent changelog updates (CHANGELOG-recoil.md). It is production-ready with the caveat that the API may evolve—not abandoned or bleeding-edge.

Risk is moderate: Recoil has minimal direct dependencies (only hamt_plus v1.0.2 and transit-js ^0.8.874), reducing supply-chain risk. However, it's a Facebook experimental project, so long-term investment guarantees are weaker than Zustand or Jotai. No obvious signs of stale maintenance visible, but the 'experimental' tag means API breaking changes are possible across minor versions.

The project is actively maintained with nightly builds (deploy-nightly script), recent changelog entries for recoil, recoil-relay, recoil-sync, and refine packages, and ongoing GitHub Actions CI. The presence of multiple CHANGELOG files and relay-compiler integration suggests active feature work on sync and relay integration.

git clone https://github.com/facebookexperimental/Recoil.git
cd Recoil
npm install
npm run build
npm test

Daily commands:

npm run build        # Transpile src/ to umd/, es/, cjs/, native/
npm test             # Run Jest suite across packages/*
npm run flow         # Type-check with Flow
npm run lint         # ESLint validation
npm run relay        # Compile GraphQL fragments (relay-compiler)

• package.json — Defines build targets (cjs, es, umd, native), entry points, and all scripts—understanding this is essential for any contribution workflow
• babel.config.json — Controls transpilation and source transformation across all build targets; changes here affect the entire distribution pipeline
• jest.config.js — Central test configuration; required reading for understanding test execution and mock setup across the monorepo
• .eslintrc.js — Enforces code standards and custom rules (including no-fb-only.js); every PR must pass linting
• packages-ext/recoil-devtools/src/pages/Background/Background.js — Core devtools extension background script that bridges page and content scripts; handles extension state synchronization
• packages-ext/recoil-devtools/src/pages/Popup/PopupApp.js — Main devtools UI entry point; integrates snapshot inspection, dependency graphs, and transaction history

• Background Script (Background.js) — undefined

Add a new Devtools UI panel

1. Create new React component in packages-ext/recoil-devtools/src/pages/Popup/ (packages-ext/recoil-devtools/src/pages/Popup/PopupMainContent.js)
2. Register the component in the tab router within PopupApp.js (packages-ext/recoil-devtools/src/pages/Popup/PopupApp.js)
3. Use ConnectionContext to subscribe to devtools state updates (packages-ext/recoil-devtools/src/pages/Popup/ConnectionContext.js)
4. Add corresponding test file following tests pattern (packages-ext/recoil-devtools/src/pages/Background/__tests__/Background.test.js)

Add a new devtools utility function

1. Create .js file in packages-ext/recoil-devtools/src/utils/ with exported function (packages-ext/recoil-devtools/src/utils/GraphUtils.js)
2. Export from utils/index.js (or create if missing) for consumption by UI components (packages-ext/recoil-devtools/src/pages/Popup/PopupDependencyGraph.js)
3. Add unit tests in tests subdirectory with .test.js suffix (packages-ext/recoil-devtools/src/pages/Background/__tests__/Background.test.js)
4. Run jest packages/recoil-devtools to verify coverage (jest.config.js)

Extend devtools message protocol

1. Define new message type in packages-ext/recoil-devtools/src/types/DevtoolsTypes.js (packages-ext/recoil-devtools/src/types/DevtoolsTypes.js)
2. Handle message in Background.js event listener and forward to content/popup as needed (packages-ext/recoil-devtools/src/pages/Background/Background.js)
3. Update ContentScript.js to dispatch or listen for the new message type (packages-ext/recoil-devtools/src/pages/Content/ContentScript.js)
4. Consume message in PopupApp or specific panel component via ConnectionContext (packages-ext/recoil-devtools/src/pages/Popup/ConnectionContext.js)

• React 18.x — Recoil is a React state management library; components use latest hooks and concurrent features
• Flow (static typing) — Provides gradual type safety for the core library; flow-typed/ stubs ensure compatibility across browser and Node contexts
• Jest + Babel — Unified test and transpilation pipeline for multiple output formats (CJS, ES, UMD, React Native)
• Browser Extension APIs (Chrome/Firefox) — Devtools communicates via content scripts, background service workers, and message ports for sandbox isolation
• Monorepo structure (packages-ext/) — Allows independent versioning and testing of Recoil core vs. satellite packages (devtools, relay integration, etc.)

• Browser extension architecture with separate background/content/popup scripts

  • Why: Provides security sandboxing and allows inspection without modifying app code
  • Consequence: Requires cross-context message passing (JSON serialization); state must be reconstructed in multiple processes

• EvictableList (ring buffer) for transaction history

  • Why: Avoids unbounded memory growth in long-running inspections
  • Consequence: Older transactions are discarded; users cannot inspect full history beyond buffer capacity

• Multiple build targets (CJS, ES, UMD, React Native) from single source

  • Why: Supports diverse consumers (Node, browsers, native apps)
  • Consequence: Complex Babel configuration and must verify each target separately; larger build pipeline

• Does not replace React DevTools; only inspects Recoil state, not React component props/hooks
• Does not persist state across browser restarts (snapshots are in-memory only)
• Does not provide time-travel debugging of individual atom mutations (only snapshots at transaction boundaries)
• Not a real-time collaboration tool; devtools are single-user, single-browser-instance only

Flow type-checker must be installed and run separately (npm run flow) or via pre-commit hooks—it does not integrate into Jest. Relay integration (relay-compiler) requires a graphql.config.js in projects using recoil-relay, not in core Recoil itself. Async selectors (queries) and error handling differ from Redux middleware patterns—study the async tutorial. Native target output assumes React Native environment; standard web projects use es or cjs. No obvious environment variable requirements, but nightly builds reference a deploy script that likely requires CI secrets.

• Atoms — Recoil's fundamental primitive for mutable state; understanding atom identity, updates, and subscription is core to using Recoil correctly
• Selectors (derived state) — Composable, memoized computed values that auto-update when dependencies change; Recoil's answer to Redux selectors and MobX computeds
• Reactive graph updates — Recoil maintains a dependency graph and only notifies subscribers to atoms/selectors that actually changed, enabling fine-grained re-renders without Redux-style global subscribe
• Suspense integration — Async selectors throw promises during loading, enabling React Suspense boundaries and concurrent features; central to Recoil's async query pattern
• Persistent Atom Effects — Lifecycle hooks on atoms (initializeState, onSet) for side effects like localStorage sync—Recoil's answer to Redux middleware
• HAMT (Hash Array Mapped Trie) — Recoil uses hamt_plus v1.0.2 for efficient immutable data structures in the state graph, enabling structural sharing and fast cloning
• Transit serialization — transit-js dependency handles serialization of Recoil snapshots for debugging and persistence; enables safe JSON-like encoding of complex state values

• pmndrs/zustand — Lightweight alternative state manager for React with similar atom-like store concept but simpler API and less boilerplate
• pmndrs/jotai — Primitive atom-based state management for React with similar goals to Recoil but lighter footprint and Suspense-first design
• reduxjs/redux — Established predictable state container; Recoil is often positioned as Redux alternative for smaller/medium apps avoiding action boilerplate
• relayjs/relay — Facebook's GraphQL client; recoil-relay bridges Recoil state with Relay query/mutation patterns for seamless data fetching
• facebookexperimental/recoil-relay — Official Recoil integration for Relay—companion package in this monorepo for GraphQL-centric apps

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive TypeScript definitions tests for Recoil core atoms and selectors

The repo has typescript/ directory for dtslint tests (referenced in package.json scripts), but based on the file structure provided, there's no visibility into test coverage for TypeScript definitions. Recoil's type system is critical for TypeScript users. New contributors could add exhaustive dtslint test cases for atom creation, selector derivation, and useRecoilValue/useRecoilState hook typing to catch type regressions early.

• [ ] Examine existing test cases in typescript/ directory (not shown in file structure)
• [ ] Create new dtslint test file for atom() edge cases (optional parameters, type inference)
• [ ] Create new dtslint test file for selector() type safety (get/set variants, dependency typing)
• [ ] Create new dtslint test file for hook return types under different scenarios
• [ ] Add tests to jest.config.js or CI workflow to ensure yarn test:typescript runs consistently

Add GitHub Actions workflow for TypeScript type checking on PRs

Looking at .github/workflows/, there are nightly.yml and nodejs.yml workflows, but no explicit TypeScript checking workflow. The package.json has test:typescript script using dtslint, but this critical check may not be enforced on every PR. Adding a dedicated workflow ensures type safety regressions are caught before merge.

• [ ] Create .github/workflows/typescript.yml with job for yarn test:typescript
• [ ] Configure the workflow to run on pull_request and push to main
• [ ] Ensure it runs after dependencies are installed (add caching similar to nodejs.yml)
• [ ] Add failure condition to block merging if types don't pass dtslint validation
• [ ] Document the new check in CONTRIBUTING.md

Add unit tests for ESLint custom rules in eslint-rules/ directory

The repo contains custom ESLint rules in eslint-rules/no-fb-only.js, but there's no visible test suite for these custom rules. ESLint custom rules should have test coverage to prevent regression. New contributors can add Jest tests to validate rule behavior against various code patterns.

• [ ] Create eslint-rules/__tests__/no-fb-only.test.js test file
• [ ] Write test cases for: detecting FB_ONLY calls, ignoring legitimate patterns, testing message output
• [ ] Use ESLint's RuleTester utility to validate rule detection
• [ ] Add test script to package.json or CI to run jest eslint-rules/ on PRs
• [ ] Document the custom rule purpose and testing approach in CONTRIBUTING.md

• Add missing Flow types or TypeScript stubs for undocumented selector/atom patterns in src/; many internal helpers lack comprehensive type coverage
• Write integration tests for recoil-sync's cross-tab persistence (packages-ext may have gaps) to ensure localStorage/IndexedDB sync is reliable
• Document and test error boundary behavior when atoms throw during evaluation—currently unclear how errors propagate to Suspense

The Recoil repository demonstrates a generally secure codebase with MIT licensing and open-source transparency. However, several medium-severity issues exist: (1) multiple outdated dependencies from 2020-2021 that should be updated to current stable versions, particularly Babel and Rollup packages, (2) potential XSS risks in the browser extension components that require code review, and (3) missing formal security disclosure policy. The repository uses Flow for type safety and ESLint for code quality, which are positive security practices. No hardcoded credentials, SQL injection risks, or critical infrastructure misconfigurations were detected. Dependencies are well-managed with peer dependency constraints. Primary recommendation: update all devDependencies to current versions and add a SECURITY.md file defining vulnerability reporting procedures.

• Medium · Outdated Babel Dependencies — package.json - devDependencies (@babel/* packages). Multiple Babel dependencies are pinned to older versions (^7.16.0 from 2021). These versions may contain known security vulnerabilities. Current stable versions are significantly newer. Fix: Update all @babel packages to the latest stable versions (^7.23.0 or newer). Run 'npm audit' and 'npm audit fix' to identify and patch vulnerabilities.
• Medium · Outdated Rollup Dependencies — package.json - devDependencies (@rollup/* packages). Rollup plugin dependencies are pinned to older versions from 2020-2021. @rollup/plugin-node-resolve@^7.1.3 and @rollup/plugin-commonjs@^11.1.0 are significantly outdated. Fix: Update all @rollup packages to the latest stable versions. Current versions are @rollup/plugin-node-resolve@^15.0.0+ and @rollup/plugin-commonjs@^24.0.0+.
• Low · Incomplete Package.json DevDependencies — package.json - devDependencies (babel-plugin-relay entry). The package.json file appears truncated in the provided content. The babel-plugin-relay dependency entry is incomplete, making it impossible to verify its version and security status. Fix: Verify the complete package.json file is properly formatted and all dependencies are fully specified with pinned versions.
• Low · Transit-js Dependency Version — package.json - dependencies. The transit-js dependency is pinned to ^0.8.874, an older version from 2016. While this library is stable, newer versions may include bug fixes and security patches. Fix: Review the latest transit-js releases and upgrade if newer versions are compatible. Current stable version is 0.8.887+.
• Low · Missing Security Headers Configuration — Repository root. No security configuration files detected (no .security.json, security.md, or SECURITY.md file for vulnerability disclosure). The repository lacks a clear security policy. Fix: Create a SECURITY.md file outlining the vulnerability disclosure process and security contact information, following the GitHub security advisory guidelines.
• Low · Potential XSS Risk in DevTools Extension — packages-ext/recoil-devtools/src/pages/Popup/Items/. The recoil-devtools browser extension contains multiple components that manipulate DOM (DiffItem.js, ItemValue.js, ItemDescription.js). Without code review, there's a risk of XSS if user input or state values are rendered without proper sanitization. Fix: Review all DOM manipulation code to ensure proper escaping and sanitization. Use React's built-in protections against XSS and avoid dangerouslySetInnerHTML. Add Content Security Policy headers to the extension manifest.
• Low · DevTools Manifest Not Reviewed — packages-ext/recoil-devtools/src/manifest.json. Browser extension manifest.json file exists but content not provided. Extensions require careful review of permissions requested to minimize attack surface. Fix: Review manifest.json to ensure only necessary permissions are requested. Use host_permissions to restrict content script injection to required domains only. Implement Content Security Policy.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/facebookexperimental/Recoil shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live facebookexperimental/Recoil repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/facebookexperimental/Recoil.

What it runs against: a local clone of facebookexperimental/Recoil — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in facebookexperimental/Recoil | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 523 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of facebookexperimental/Recoil. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/facebookexperimental/Recoil.git
#   cd Recoil
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of facebookexperimental/Recoil and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "facebookexperimental/Recoil(\\.git)?\\b" \\
  && ok "origin remote is facebookexperimental/Recoil" \\
  || miss "origin remote is not facebookexperimental/Recoil (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "package.json" \\
  && ok "package.json" \\
  || miss "missing critical file: package.json"
test -f "babel.config.json" \\
  && ok "babel.config.json" \\
  || miss "missing critical file: babel.config.json"
test -f "jest.config.js" \\
  && ok "jest.config.js" \\
  || miss "missing critical file: jest.config.js"
test -f ".eslintrc.js" \\
  && ok ".eslintrc.js" \\
  || miss "missing critical file: .eslintrc.js"
test -f "packages-ext/recoil-devtools/src/pages/Background/Background.js" \\
  && ok "packages-ext/recoil-devtools/src/pages/Background/Background.js" \\
  || miss "missing critical file: packages-ext/recoil-devtools/src/pages/Background/Background.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 523 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~493d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/facebookexperimental/Recoil"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.