Next.js app server actions - handling a successful server response

[dopoto]

I'm looking into how to take in use TanStack Form into a Next.js app using server actions:

• https://tanstack.com/form/v1/docs/framework/react/guides/ssr#using-tanstack-form-in-a-nextjs-app-router
• https://github.com/TanStack/form/blob/main/examples/react/next-server-actions/src/app/client-component.tsx
• https://github.com/TanStack/form/blob/main/examples/react/next-server-actions/src/app/action.ts

I might be missing something obvious, but neither the docs or the code examples show how to actually handle the happy path:

• the server action processes the form data and returns a success message:

...
// Your form has successfully validated!
const result = await saveToDb(validatedData)
// how to make this part of the data model being passed between server and client?
return { isSuccess: true}

• the client side code is notified about it and confirms to the user:

// where and how to check this?
if(state.isSuccess === true){
 console.log('Saved')
}

can anybody please point me to some more detailed examples on how to achieve this in a TanStackForm-way?

[ajaykarthikr]

@dopoto Were you able to figure this out?

[dopoto]

no, I just switched to react-hook-form...

[0x-DLN]

The actual shape you can return, as far as I can tell is this

type ServerFormState<TFormData, TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>> = {
    values: TFormData;
    errors: (UnwrapFormAsyncValidateOrFn<TOnServer> | undefined)[];
    errorMap: ValidationErrorMap<undefined, undefined, undefined, ... 4 more ..., UnwrapFormAsyncValidateOrFn<...>>;
}

If you return a string, or an array of strings they get added to the error map.

e.g. doing this:

const serverValidate = createServerValidate({
  ...formOpts,
  onServerValidate: ({ value }) => {
    if (value.description.length < 5) {
      return "description too short";
    }
  },
});

return this 1:{"errorMap":{"onServer":"description too short"},"values":{"title":"asd","description":"x"},"errors":["description too short"]}

And with an array:

const serverValidate = createServerValidate({
  ...formOpts,
  onServerValidate: ({ value }) => {
    if (value.description.length < 5) {
      return ["description too short", "some other error"];
    }
  },
});

returns 1:{"errorMap":{"onServer":["description too short","some other error"]},"values":{"title":"asd","description":"x"},"errors":["$1:errorMap:onServer"]}

The values are your form shape, so if you want to return a success variable (for example, an ID to navigate to after creation) you could do something like this:

export default async function someAction(prev: unknown, formData: FormData) {
  try {
    const validatedData = await serverValidate(formData);

    const newTodo = await db.todos.create({
      data: validatedData // Title and description
    });

    return {
      values: {
        ...validatedData,
        todoId: newTodo.id
      }
    };
  } catch (e) {
    if (e instanceof ServerValidateError) {
      return e.formState;
    }
    throw e;
  }
}

Then you can handle it in the client like so:

const form = useForm({
    ...formOpts,
    transform: useTransform(
      (baseForm) => {
        if (state.values?.todoId) { // state.value is undefined on initialization
          console.log("todoId", state.values.todoId); // You could do navigation or something here
        }
        return mergeForm(baseForm, state!);
      },
      [state]
    ),
  });

However, you lose type safety + this is a really scuffed workaround. Would not recommend.

[0x-DLN]

Since we're using nextjs and can easily share code between server/client, I'd recommend the following:

Put your zod schema somewhere both client & server can import it, probably the same place you put formOpts

// shared.ts
import z from "zod";
import { formOptions } from "@tanstack/react-form";

export const formOpts = formOptions({
  defaultValues: {
    title: "",
    description: "",
  },
});

export const formSchema = z.object({
  title: z
    .string()
    .min(3, "Title must be at least 3 characters long")
    .max(100, "Title must be at most 100 characters long"),
  description: z
    .string()
    .max(500, "Description must be at most 500 characters long"),
});

Do client-side validation only, using the zod schema. SInce we're using the schema anyways, this should be fine for showing any errors + we validate on the server against bad actors (I also don't think giving them perfect form errors matters much)

// client-component.ts

// Either for the whole form
const form = useForm({
  ... formOpts,
  transform: useTransform((baseForm) => mergeForm(baseForm, state!), [state]),
  validators: {
    onChange: formSchema,
  },
});
  
// or per field
<form.Field
  name="title"
  validators={{
    onChange: formSchema.shape.title,
  }}
>
  {(field) => {
    return (
      ... // Your input here
    );
  }}
</form.Field>

Then use a route.ts API endpoint. I'm using tRPC so my server code looks like this:

// api/routers/todos.ts
import { formSchema } from "@/lib/shared";
import { createTRPCRouter, publicProcedure } from "@/server/api/trpc";

export const todosRouter = createTRPCRouter({
  create: publicProcedure
    .input(formSchema)
    .mutation(({ input }) => {
      ... // Logic here
    }),
});

and on the client component we simply use onSubmit with an async handler. I'm using tRPC + Tanstack React Query so your syntax might be a bit different

// client-component.ts
const createTodo = useMutation(trpc.todos.create.mutationOptions())

const form = useForm({
  ...formOpts,
  transform: useTransform((baseForm) => mergeForm(baseForm, state!), [state]),
  onSubmit: async ({value}) => {
    // You could try-catch this, and put some errors on the form or show them in a different way
    // You can also block the button using field.Subscribe and `isSubmitting`
    const todo = await createTodo.mutateAsync(value)
    router.push(`todos/${todo.id}`)
  },
});

[0x-DLN]

cc @dopoto @ajaykarthikr a bit late, but maybe it's useful for you guys