Mutations

As we saw in adding new endpoint, mutations allow us to modify data on the server, like creating, updating, or deleting resources. They can be defined similarly to queries using our API client.

Just like queries, mutations can be executed either server-side or client-side depending on your needs. Let's explore both approaches.

Server actions

Next.js provides server actions as a powerful way to handle mutations directly on the server. They're particularly well-suited for form submissions and other data modifications.

Using our api client with server actions is straightforward - you simply call the API function on the server.

Here's an example of how you can define an action to create a new post:

"use server";
 
import { revalidatePath } from "next/cache";
 
import { handle } from "@turbostarter/api/utils";
 
import { api } from "~/lib/api/server";
 
export async function createPost(post: PostInput) {
  try {
    await handle(api.posts.$post)(post);
  } catch (error) {
    onError(error);
  }
 
  revalidatePath("/posts");
}

In the above example we're also using revalidatePath to revalidate the path /posts to fetch the updated list of posts.

useMutation hook

On the other hand, if you want to perform a mutation in the client-side, you can use the useMutation hook that comes straight from the integration with Tanstack Query.

import { handle } from "@turbostarter/api/utils";
 
import { api } from "~/lib/api/react";
 
export function CreatePost() {
  const queryClient = useQueryClient();
  const { mutate } = useMutation({
    mutationFn: handle(api.posts.$post),
    onSuccess: () => {
      toast.success("Post created successfully!");
      queryClient.invalidateQueries({ queryKey: ["posts"] });
    },
  });
 
  return <form onSubmit={...} />;
}