Migrating from the tona-dashboard forms kit

submitly started as the src/lib/forms kit of the tona-dashboard starter. This guide maps that kit to the package, piece by piece, so a dashboard (or any app that copied the kit) can switch without rewriting its forms.

The mappingCopy Anchor Link

Step by stepCopy Anchor Link

npm i submitly

"use client";

import { useRouter } from "next/navigation";
import type { ReactNode } from "react";
import { toast } from "sonner";
import { NextCrudProvider } from "submitly/next";

import { useRouterWithTopLoader } from "@/hooks/use-router-with-top-loader";

export function CrudProviders({ children }: { children: ReactNode }) {
  const router = useRouterWithTopLoader(useRouter());

  return (
    <NextCrudProvider
      notify={{
        success: (result) => toast.success(result.message),
        error: (result) => toast.error(result.message),
      }}
      // The loader starts on every programmatic navigation, as before.
      navigate={(to) => router.push(to)}
      // runAction revalidates the paths, so skip the extra router.refresh().
      refreshOnMutated={false}
    >
      {children}
    </NextCrudProvider>
  );
}

// Before: local state, formKey bumped by hand, isPending passed by the caller.
const { open: dialogOpen, setOpen } = useControllableDialog(open, onOpenChange);
const [formKey, setFormKey] = useState(0);
// if (isPending) return; in every handler

// After: the lock and the remount key come from submitly.
const lock = useDialogLockScope();
const dialog = useControllableDialog({ open, onOpenChange, locked: lock.isLocked });
// dialog.openKey replaces formKey; wrap the content in <DialogLockProvider scope={lock.scope}>.

runActionCopy Anchor Link

// Before
return runAction({
  schema,
  input,
  handler: (data) => serviceFn(data), // returns ApiResponse
  revalidatePaths: ["/en/products"],
});

// After
return runAction({
  schema,
  input,
  handler: (data) => serviceFn(data), // an ApiResponse is already ActionResult-shaped
  revalidate: { paths: ["/en/products"] }, // also supports tags, and a function of (data, result)
});

What changed in behaviour:

For the dashboard, where the locale is an argument of the action, pass the translated strings per call:

export async function createProductAction(input: unknown, locale: string) {
  const t = await getActionTranslations(locale, "Crud");

  return runAction({
    schema: createProductSchema,
    input,
    messages: { validation: t("validation"), unexpected: t("unexpectedError") },
    handler: (data) => createProduct(data),
    revalidate: { paths: [`/${locale}/products`] },
  });
}

If the locale is available from the request instead, use a messages function in createRunAction.

Behaviour differences to know aboutCopy Anchor Link

• Success toasts need a message. The old hooks called toast.success(result.message) unconditionally. Now notify runs only when the result has a message. The dashboard's ApiResponse always has one, so nothing changes there; for new actions, return a message.
• A thrown action no longer crashes the form. It goes through mapError (default: the error's message as a failed result), so onSubmit and execute always settle.
• Double submits are ignored. Both hooks guard against a second call while one is running.
• Server field errors. A result with fieldErrors sets errors on the matching fields. The old kit only had the flat errors list.
• onError, notify, onMutated, redirectTo and lockDialog are new options on both hooks. See MutationOptions.
• useControllableDialog in controlled mode now bumps openKey too, so a controlled dialog also remounts its form on open. The old kit only did that for the uncontrolled FormDialog.
• ActionResult.statusCode and message are optional. Code that reads result.message as a string needs a fallback or a non-null assertion.

ChecklistCopy Anchor Link

• submitly installed; the provider mounted once.
• Hook and runAction imports switched; useConfirmAction renamed to useCrudAction.
• FormDialog and ConfirmDialog rewritten as app components over the headless helpers.
• revalidatePaths replaced with revalidate: { paths }.
• Per-call or global messages set, if the app is localized.
• src/lib/forms/hooks, server and types deleted; optionalString replaced.