Terminal.skills
Skills/recoil
>

recoil

You are an expert in Recoil, the state management library by Meta for React applications. You help developers manage application state with atoms (shared state units), selectors (derived/async state), and atom families — providing a graph-based state model that integrates naturally with React's concurrent features, avoids unnecessary re-renders, and handles async data fetching as first-class state.

#state-management#react#atoms#selectors#meta#async#graph
terminal-skillsv1.0.0
Works with:claude-codeopenai-codexgemini-clicursor
Source

Usage

$
✓ Installed recoil v1.0.0

Getting Started

  1. Install the skill using the command above
  2. Open your AI coding agent (Claude Code, Codex, Gemini CLI, or Cursor)
  3. Reference the skill in your prompt
  4. The AI will use the skill's capabilities automatically

Example Prompts

  • "Review the open pull requests and summarize what needs attention"
  • "Generate a changelog from the last 20 commits on the main branch"

Information

Version
1.0.0
Author
terminal-skills
Category
Frontend Development
License
Apache-2.0

Documentation

You are an expert in Recoil, the state management library by Meta for React applications. You help developers manage application state with atoms (shared state units), selectors (derived/async state), and atom families — providing a graph-based state model that integrates naturally with React's concurrent features, avoids unnecessary re-renders, and handles async data fetching as first-class state.

Core Capabilities

Atoms and Selectors

tsx
import { atom, selector, useRecoilState, useRecoilValue, RecoilRoot } from "recoil";

// Atoms — units of state
const todosAtom = atom<Todo[]>({
  key: "todos",
  default: [],
});

const filterAtom = atom<"all" | "active" | "completed">({
  key: "todoFilter",
  default: "all",
});

// Selectors — derived state (auto-updates when dependencies change)
const filteredTodosSelector = selector({
  key: "filteredTodos",
  get: ({ get }) => {
    const todos = get(todosAtom);
    const filter = get(filterAtom);
    switch (filter) {
      case "active": return todos.filter((t) => !t.done);
      case "completed": return todos.filter((t) => t.done);
      default: return todos;
    }
  },
});

const statsSelector = selector({
  key: "todoStats",
  get: ({ get }) => {
    const todos = get(todosAtom);
    return {
      total: todos.length,
      completed: todos.filter((t) => t.done).length,
      percent: todos.length ? Math.round(todos.filter((t) => t.done).length / todos.length * 100) : 0,
    };
  },
});

// Components
function TodoList() {
  const filteredTodos = useRecoilValue(filteredTodosSelector);  // Only re-renders when filtered list changes
  return (
    <ul>
      {filteredTodos.map((todo) => <TodoItem key={todo.id} id={todo.id} />)}
    </ul>
  );
}

function TodoStats() {
  const stats = useRecoilValue(statsSelector);
  return <p>{stats.completed}/{stats.total} done ({stats.percent}%)</p>;
}

function FilterButtons() {
  const [filter, setFilter] = useRecoilState(filterAtom);
  return (
    <div>
      {(["all", "active", "completed"] as const).map((f) => (
        <button key={f} onClick={() => setFilter(f)}
          style={{ fontWeight: filter === f ? "bold" : "normal" }}>
          {f}
        </button>
      ))}
    </div>
  );
}

function App() {
  return (
    <RecoilRoot>
      <TodoStats />
      <FilterButtons />
      <TodoList />
    </RecoilRoot>
  );
}

Async Selectors and Atom Families

tsx
// Async selector — fetches data, integrates with Suspense
const userProfileSelector = selector({
  key: "userProfile",
  get: async ({ get }) => {
    const userId = get(currentUserIdAtom);
    const response = await fetch(`/api/users/${userId}`);
    return response.json();
  },
});

// Atom families — parameterized atoms (one atom per ID)
const todoItemAtom = atomFamily<Todo | null, string>({
  key: "todoItem",
  default: null,
});

// Selector families — parameterized selectors
const userByIdSelector = selectorFamily<User, string>({
  key: "userById",
  get: (userId) => async ({ get }) => {
    const response = await fetch(`/api/users/${userId}`);
    return response.json();
  },
});

// Usage with Suspense
function UserProfile() {
  const profile = useRecoilValue(userProfileSelector);  // Suspends until loaded
  return <h1>{profile.name}</h1>;
}

function App() {
  return (
    <RecoilRoot>
      <Suspense fallback={<Spinner />}>
        <UserProfile />
      </Suspense>
    </RecoilRoot>
  );
}

Installation

bash
npm install recoil

Best Practices

  1. Unique keys — Every atom and selector needs a globally unique key string; use descriptive names
  2. Selectors for derived state — Never compute derived state in components; use selectors for memoized computation
  3. Atom families — Use atomFamily for collections (todo items, user profiles); one atom per entity
  4. Async selectors — Return promises from selector get; pairs with React Suspense for loading states
  5. Fine-grained atoms — Prefer many small atoms over one large one; minimizes re-renders
  6. RecoilRoot — Wrap app once; provides state context; can nest for isolated state subtrees
  7. useRecoilValue — Use when you only read; useRecoilState when you also write; avoids unnecessary subscriptions
  8. Concurrent mode — Recoil is designed for React concurrent features; async selectors work with Suspense transitions