The Complete Production SOP: How to Deploy and Run Recoil Atoms, Selectors & Asynchronous Data Queries in Autonomous AI Agents

---
name: "recoil-selectors-async-state"
description: "Manage fine-grained state graphs in React using Recoil atoms and pure functional selectors."
metadata:
  author: "Meta"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "create recoil atom selector"
  - "async selector recoil suspense"
  - "recoil atomfamily"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

# Recoil Atoms, Selectors & Asynchronous Data Queries

Configures Meta Recoil: defining atoms and atomFamily, synchronous and asynchronous selectors, snapshot navigation, handling suspense boundaries, and synchronizing state across sibling component trees.

## Execution SOP & Rules
1. Ensure root is wrapped in <RecoilRoot>.
2. Atoms MUST have globally unique string keys.
3. Async selectors MUST return pure Promises and be consumed inside React <Suspense>.
4. Avoid mutations inside selectors; selectors are pure derived functions.

import { atom, selector, atomFamily, selectorFamily } from 'recoil';

export interface UserProfile {
  id: string;
  name: string;
  role: 'admin' | 'member';
}

export const currentUserIdState = atom<string | null>({
  key: 'user/currentUserIdState',
  default: null,
});

export const fetchUserProfileQuery = selectorFamily<UserProfile, string>({
  key: 'user/fetchUserProfileQuery',
  get: (userId: string) => async () => {
    if (!userId) throw new Error('Invalid user ID provided');
    const res = await fetch(`/api/users/${userId}`);
    if (!res.ok) throw new Error(`User fetch failed: ${res.statusText}`);
    return (await res.json()) as UserProfile;
  },
});

import React, { Suspense } from 'react';
import { useRecoilValue } from 'recoil';
import { currentUserIdState, fetchUserProfileQuery } from '../state/userAtoms';

const UserDetails: React.FC<{ userId: string }> = ({ userId }) => {
  const profile = useRecoilValue(fetchUserProfileQuery(userId));
  return (
    <div className="p-4 border rounded shadow-sm">
      <h2 className="text-lg font-bold">{profile.name}</h2>
      <span className="text-xs uppercase bg-gray-200 px-2 py-1">{profile.role}</span>
    </div>
  );
};

export const UserProfileView: React.FC = () => {
  const currentUserId = useRecoilValue(currentUserIdState);

  if (!currentUserId) {
    return <p className="text-muted">No user selected.</p>;
  }

  return (
    <Suspense fallback={<div className="animate-pulse">Loading user profile...</div>}>
      <UserDetails userId={currentUserId} />
    </Suspense>
  );
};

import { renderHook, act } from '@testing-library/react';
import { RecoilRoot, useRecoilValue, useSetRecoilState } from 'recoil';
import { currentUserIdState } from '../userAtoms';

test('currentUserIdState updates correctly inside RecoilRoot', () => {
  const wrapper = ({ children }: { children: React.ReactNode }) => (
    <RecoilRoot>{children}</RecoilRoot>
  );
  const { result } = renderHook(() => ({
    id: useRecoilValue(currentUserIdState),
    setId: useSetRecoilState(currentUserIdState),
  }), { wrapper });

  expect(result.current.id).toBeNull();
  act(() => {
    result.current.setId('usr_102');
  });
  expect(result.current.id).toBe('usr_102');
});