Using Automatic Cache Invalidation

When we delete a user, the user list should update automatically. Users shouldn’t need to manually refresh the page to see their changes. Effect Atom provides a reactivity system that handles exactly this.

How Reactivity Works

Effect Atom’s reactivity is built on a simple concept: shared keys.

Tag Atoms with keys: You mark Atoms with reactivity keys that describe what data they represent. For example, the users Atom might have the key "users".
Tag mutations with keys: You mark mutations with the same keys to indicate what data they affect. A delete user mutation would also use the key "users".
Automatic invalidation: When a mutation tagged with "users" completes successfully, Effect Atom automatically invalidates (refreshes) all Atoms tagged with "users".

This creates a declarative system where you describe relationships once, and the framework handles synchronization.

Note

Automatic invalidation only works when the target Atom has active subscribers. If no component is currently subscribed to the Atom, the invalidation signal has no effect. We’ll see why this matters shortly.

Setting Up Reactivity

Update usersAtom in atoms/user.ts to declare their reactivity keys:

1
import { Duration, Effect } from "effect";
2
import { Atom } from "effect/unstable/reactivity";
3

4
import { atomRuntime } from "@/atom-runtime";
5
import { type AddUserFormValues } from "@/schema/user-schema";
6
import { UserService } from "@/services/user-service";
7

8
// ============ Users Atom ============
9
export const usersAtom = atomRuntime
10
  .atom(
11
    Effect.gen(function* () {
12
      const userService = yield* UserService;
13
      return yield* userService.getUsers();
14
    }),
15
  )
16
  .pipe(Atom.setIdleTTL(Duration.hours(1)), Atom.withReactivity(["users"]));
17

27 collapsed lines
18
// ============ User Atom ============
19
export const userAtom = Atom.family((id: string) =>
20
  atomRuntime
21
    .atom(
22
      Effect.gen(function* () {
23
        const userService = yield* UserService;
24
        return yield* userService.getUser(id);
25
      }),
26
    )
27
    .pipe(Atom.setIdleTTL(Duration.hours(1))),
28
);
29

30
// ============ Delete User Atom ============
31
export const deleteUserAtom = atomRuntime.fn(
32
  Effect.fnUntraced(function* (userId: string) {
33
    const userService = yield* UserService;
34
    yield* userService.deleteUser(userId);
35
  }),
36
);
37

38
// ============ Add User Atom ============
39
export const addUserAtom = atomRuntime.fn<AddUserFormValues>()(
40
  Effect.fnUntraced(function* (user) {
41
    const userService = yield* UserService;
42
    return yield* userService.addUser(user);
43
  }),
44
);

Atom.withReactivity(["users"]) tags this Atom with the "users" key. Any mutation that invalidates "users" will cause this Atom to refresh.

Now update deleteUserAtom to trigger invalidation:


28 collapsed lines
1
import { Duration, Effect } from "effect";
2
import { Atom } from "effect/unstable/reactivity";
3

4
import { atomRuntime } from "@/atom-runtime";
5
import { type AddUserFormValues } from "@/schema/user-schema";
6
import { UserService } from "@/services/user-service";
7

8
// ============ Users Atom ============
9
export const usersAtom = atomRuntime
10
  .atom(
11
    Effect.gen(function* () {
12
      const userService = yield* UserService;
13
      return yield* userService.getUsers();
14
    }),
15
  )
16
  .pipe(Atom.setIdleTTL(Duration.hours(1)), Atom.withReactivity(["users"]));
17

18
// ============ User Atom ============
19
export const userAtom = Atom.family((id: string) =>
20
  atomRuntime
21
    .atom(
22
      Effect.gen(function* () {
23
        const userService = yield* UserService;
24
        return yield* userService.getUser(id);
25
      }),
26
    )
27
    .pipe(Atom.setIdleTTL(Duration.hours(1))),
28
);
29

30
// ============ Delete User Atom ============
31
export const deleteUserAtom = atomRuntime.fn(
32
  Effect.fnUntraced(function* (userId: string) {
33
    const userService = yield* UserService;
34
    yield* userService.deleteUser(userId);
35
  }),
36
  { reactivityKeys: ["users"] },
37
);
38

7 collapsed lines
39
// ============ Add User Atom ============
40
export const addUserAtom = atomRuntime.fn<AddUserFormValues>()(
41
  Effect.fnUntraced(function* (user) {
42
    const userService = yield* UserService;
43
    return yield* userService.addUser(user);
44
  }),
45
);

The { reactivityKeys: ["users"] } option tells the reactivity system: “When this operation succeeds, invalidate everything tagged with 'users'.”

Testing Automatic Invalidation

Let’s verify that everything works.

Testing User Deletion

Click the trash icon on any user card and confirm. The toast appears, and the user card disappears from the grid. You no longer need to manually refresh the page. The usersAtom automatically refetched the data because the deleteUserAtom mutation invalidated the "users" key.

This works because when you delete a user, you’re on the home page. The UserGridSuspense component is mounted and subscribed to usersAtom. When the reactivity system invalidates the "users" key, there’s an active subscriber listening, so the Atom refetches immediately.

Why Reactivity Keys Don’t Work for Adding Users

You might wonder: why not add reactivityKeys: ["users"] to addUserAtom as well?

The problem is that when you add a user, you’re on the /add-user page. The UserGridSuspense component is not mounted, which means no component is subscribed to usersAtom. The reactivity system invalidates the "users" key, but since nothing is listening, the invalidation has no effect. When you navigate back to the home page, usersAtom still holds its old cached data. You won’t see the newly added user.

Reactivity keys are subscription-driven. They work when the target Atom has active subscribers. For mutations that happen on the same page as the data they affect (like delete), they work perfectly. For mutations that happen on a different page (like add), we need a different approach.

The solution is to explicitly refresh usersAtom after adding a user, before navigating back to the home page.

Update components/add-user-form.tsx as shown below:

1
"use client";
2

3
import { startTransition, useId, useState } from "react";
4
import { useRouter } from "next/navigation";
5
import { useAtomRefresh, useAtomSet } from "@effect/atom-react";
6
import { standardSchemaResolver } from "@hookform/resolvers/standard-schema";
7
import { Cause, Exit, Option } from "effect";
8
import { useForm } from "react-hook-form";
9
import { useProgress } from "react-transition-progress";
10
import { toast } from "sonner";
11

12
import {
13
  FormErrorMessage,
14
  FormFieldErrorMessage,
15
} from "@/components/form-messages";
16
import { Icons } from "@/components/icons";
17
import { Button } from "@/components/ui/button";
18
import { Card, CardContent } from "@/components/ui/card";
19
import { Input } from "@/components/ui/input";
20
import { Label } from "@/components/ui/label";
21

22
import { addUserAtom, usersAtom } from "@/atoms/user";
23
import {
24
  AddUserFormStandardSchema,
25
  type AddUserFormValues,
26
} from "@/schema/user-schema";
27

28
export function AddUserForm() {
29
  const id = useId();
30
  const router = useRouter();
31
  const startProgress = useProgress();
32

33
  const [globalError, setGlobalError] = useState<string | null>(null);
34

35
  const addUser = useAtomSet(addUserAtom, { mode: "promiseExit" });
36
  const refreshUsers = useAtomRefresh(usersAtom);
37

38
  const {
39
    register,
40
    handleSubmit,
41
    formState: { errors, isSubmitting },
42
  } = useForm<AddUserFormValues>({
43
    resolver: standardSchemaResolver(AddUserFormStandardSchema),
44
    defaultValues: {
45
      firstName: "",
46
      lastName: "",
47
      email: "",
48
      company: { name: "", title: "" },
49
      address: { address: "", city: "", state: "" },
50
    },
51
  });
52

53
  const onSubmit = async (data: AddUserFormValues) => {
54
    setGlobalError(null);
55

56
    const exit = await addUser(data);
57

58
    if (Exit.isSuccess(exit)) {
59
      const user = exit.value;
60
      refreshUsers();
61
      toast.success("User Added Successfully", {
62
        description: `${user.firstName} ${user.lastName} was added successfully.`,
63
      });
64
      startTransition(() => {
65
        startProgress();
66
        router.push("/");
67
      });
68
    } else {
69
      const failureOption = Cause.findErrorOption(exit.cause);
70
      const errorMessage = Option.isSome(failureOption)
71
        ? failureOption.value.message
72
        : "An unexpected error occurred";
73
      setGlobalError(errorMessage);
74
    }
75
  };
76
  return (
146 collapsed lines
77
    <Card>
78
      <CardContent className="mt-4">
79
        <FormErrorMessage message={globalError} />
80

81
        <form onSubmit={handleSubmit(onSubmit)} className="space-y-6">
82
          {/* First Name */}
83
          <div className="space-y-2">
84
            <Label htmlFor={`${id}-firstName`}>First Name</Label>
85
            <Input
86
              id={`${id}-firstName`}
87
              {...register("firstName")}
88
              aria-invalid={!!errors.firstName}
89
              aria-describedby={
90
                errors.firstName ? `${id}-firstName-error` : undefined
91
              }
92
            />
93
            <FormFieldErrorMessage
94
              id={`${id}-firstName-error`}
95
              message={errors.firstName?.message}
96
            />
97
          </div>
98

99
          {/* Last Name */}
100
          <div className="space-y-2">
101
            <Label htmlFor={`${id}-lastName`}>Last Name</Label>
102
            <Input
103
              id={`${id}-lastName`}
104
              {...register("lastName")}
105
              aria-invalid={!!errors.lastName}
106
              aria-describedby={
107
                errors.lastName ? `${id}-lastName-error` : undefined
108
              }
109
            />
110
            <FormFieldErrorMessage
111
              id={`${id}-lastName-error`}
112
              message={errors.lastName?.message}
113
            />
114
          </div>
115

116
          {/* Email */}
117
          <div className="space-y-2">
118
            <Label htmlFor={`${id}-email`}>Email</Label>
119
            <Input
120
              id={`${id}-email`}
121
              type="email"
122
              {...register("email")}
123
              aria-invalid={!!errors.email}
124
              aria-describedby={errors.email ? `${id}-email-error` : undefined}
125
            />
126
            <FormFieldErrorMessage
127
              id={`${id}-email-error`}
128
              message={errors.email?.message}
129
            />
130
          </div>
131

132
          <div className="grid grid-cols-2 gap-4">
133
            {/* Company Name */}
134
            <div className="space-y-2">
135
              <Label htmlFor={`${id}-companyName`}>Company Name</Label>
136
              <Input
137
                id={`${id}-companyName`}
138
                {...register("company.name")}
139
                aria-invalid={!!errors.company?.name}
140
                aria-describedby={
141
                  errors.company?.name ? `${id}-companyName-error` : undefined
142
                }
143
              />
144
              <FormFieldErrorMessage
145
                id={`${id}-companyName-error`}
146
                message={errors.company?.name?.message}
147
              />
148
            </div>
149

150
            {/* Job Title */}
151
            <div className="space-y-2">
152
              <Label htmlFor={`${id}-jobTitle`}>Job Title</Label>
153
              <Input
154
                id={`${id}-jobTitle`}
155
                {...register("company.title")}
156
                aria-invalid={!!errors.company?.title}
157
                aria-describedby={
158
                  errors.company?.title ? `${id}-jobTitle-error` : undefined
159
                }
160
              />
161
              <FormFieldErrorMessage
162
                id={`${id}-jobTitle-error`}
163
                message={errors.company?.title?.message}
164
              />
165
            </div>
166
          </div>
167

168
          {/* Address Info */}
169
          <div className="space-y-4 pt-2">
170
            <div className="space-y-2">
171
              <Label htmlFor={`${id}-address`}>Street Address</Label>
172
              <Input
173
                id={`${id}-address`}
174
                {...register("address.address")}
175
                aria-invalid={!!errors.address?.address}
176
              />
177
              <FormFieldErrorMessage
178
                id={`${id}-address-error`}
179
                message={errors.address?.address?.message}
180
              />
181
            </div>
182

183
            <div className="grid grid-cols-2 gap-4">
184
              <div className="space-y-2">
185
                <Label htmlFor={`${id}-city`}>City</Label>
186
                <Input
187
                  id={`${id}-city`}
188
                  {...register("address.city")}
189
                  aria-invalid={!!errors.address?.city}
190
                />
191
                <FormFieldErrorMessage
192
                  id={`${id}-city-error`}
193
                  message={errors.address?.city?.message}
194
                />
195
              </div>
196

197
              <div className="space-y-2">
198
                <Label htmlFor={`${id}-state`}>State</Label>
199
                <Input
200
                  id={`${id}-state`}
201
                  {...register("address.state")}
202
                  aria-invalid={!!errors.address?.state}
203
                />
204
                <FormFieldErrorMessage
205
                  id={`${id}-state-error`}
206
                  message={errors.address?.state?.message}
207
                />
208
              </div>
209
            </div>
210
          </div>
211

212
          <div className="flex justify-end pt-4">
213
            <Button type="submit" disabled={isSubmitting}>
214
              {isSubmitting && (
215
                <Icons.spinner className="size-4 animate-spin" />
216
              )}
217
              Add User
218
            </Button>
219
          </div>
220
        </form>
221
      </CardContent>
222
    </Card>
223
  );
224
}

useAtomRefresh takes an Atom and returns a function that, when called, tells the Registry to invalidate the Atom and re-run its Effect. We call refreshUsers() after a successful addition, before navigating to the home page. This ensures usersAtom fetches fresh data that includes the newly added user.

Testing User Addition

Click Add User, fill out the form, and submit. After the redirect, you should see your newly added user in the list.

The reactivity system keeps your UI synchronized with your data. For same-page mutations, reactivityKeys handles everything automatically. For cross-page mutations, an explicit refresh before navigation ensures the data is up to date.