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

Note

Effect Atom uses the @effect/experimental package for the reactivity feature.

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

1
import { Atom } from "@effect-atom/atom-react";
2
import { Duration, Effect } from "effect";
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
      return yield* UserService.getUsers();
13
    }),
14
  )
15
  .pipe(Atom.setIdleTTL(Duration.hours(1)), Atom.withReactivity(["users"]));
16

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

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

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

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:


26 collapsed lines
1
import { Atom } from "@effect-atom/atom-react";
2
import { Duration, Effect } from "effect";
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
      return yield* UserService.getUsers();
13
    }),
14
  )
15
  .pipe(Atom.setIdleTTL(Duration.hours(1)), Atom.withReactivity(["users"]));
16

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

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

6 collapsed lines
36
// ============ Add User Atom ============
37
export const addUserAtom = atomRuntime.fn<AddUserFormValues>()(
38
  Effect.fnUntraced(function* (user) {
39
    return yield* UserService.addUser(user);
40
  }),
41
);

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 delete icon on any user card and confirm. The toast appears, and—without refreshing—the user card disappears from the grid. 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/atom-react";
6
import { effectTsResolver } from "@hookform/resolvers/effect-ts";
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
  AddUserFormSchema,
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: effectTsResolver(AddUserFormSchema),
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.failureOption(exit.cause);
70
      const errorMessage = Option.isSome(failureOption)
71
        ? failureOption.value.message
72
        : "An unexpected error occurred";
73
      setGlobalError(errorMessage);
74
    }
75
  };
76

77
  return (
146 collapsed lines
78
    <Card>
79
      <CardContent className="mt-4">
80
        <FormErrorMessage message={globalError} />
81

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

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

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

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

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

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

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

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

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

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 like delete, reactivityKeys handles everything automatically. For cross-page mutations like add, an explicit refresh before navigation ensures the data is up to date.