All jobs

Add Async Username Validation to a Conform Form

Yes. An agent makes the onboarding form check username uniqueness on blur through Conform's server validation, keeps the submit path intact, tests it and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads the form as it stands. In a React Router app laid out like epicweb-dev/epic-stack, app/routes/_auth/onboarding/index.tsx builds SignupFormSchema from UsernameSchema, NameSchema and PasswordAndConfirmPasswordSchema in app/utils/user-validation.ts, and its action runs parseWithZod with async: true over a superRefine that looks the username up with prisma.user.findUnique and adds the issue A user already exists with this username, then checks the password against checkIsCommonPassword. The transform returns session: null whenever intent is not null, which is the hook Conform's validation requests use. On the client, useForm runs onValidate with the plain SignupFormSchema and shouldRevalidate: 'onBlur', so the browser knows a username is too short or has a bad character as soon as the field loses focus, but learns it is taken only after a full submit comes back with a 400.

Conform documents the pattern for exactly this. The agent turns the schema into a factory, createSignupSchema(constraint), whose username field carries a superRefine that reports conformZodMessage.VALIDATION_UNDEFINED when no isUsernameUnique function is given, which is the client, and otherwise awaits it and adds the existing message. A client-side result of VALIDATION_UNDEFINED tells Conform it cannot decide and makes it send a validation request to the action with the validate/username intent. On the server the factory gets the real lookup, and when the intent names one field the other refinements return VALIDATION_SKIPPED, so a blur on the username does not also run the pwned-password check or complain about an empty password. useForm gains shouldValidate: 'onBlur' beside the existing shouldRevalidate, and onValidate calls the factory with no lookup.

The action's shape barely moves. parseWithZod already takes schema: (intent) => ..., so the factory is called with the intent, the transform keeps returning session: null for a validation intent and signup(...) only on a real submit, and checkHoneypot(formData) keeps running first on every POST, including the validation ones, because HoneypotInputs are part of the same form. UsernameSchema lowercases its value in a transform, so the lookup sees the stored form, and the agent moves the email-exists check in app/routes/_auth/signup.tsx onto the same factory pattern so both forms behave alike.

Tests follow the repository's two layers. A Vitest file beside user-validation.ts checks that the factory with no lookup yields VALIDATION_UNDEFINED for a well-formed username and a normal error for a bad one. A Playwright test in tests/e2e/onboarding.test.ts, which already walks signup through the verification email read with readEmail from tests/mocks/utils.ts, creates a user first with createUser from tests/db-utils.ts, types that username on /onboarding, moves focus to the name field and expects the taken message before pressing Create an account. The agent runs npm run validate, which package.json defines as test -- --run, lint, typecheck and test:e2e:run in parallel, after npm run setup has built, migrated and installed the Playwright browser.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Make the onboarding form validate username uniqueness on blur. Read app/routes/_auth/onboarding/index.tsx, app/routes/_auth/signup.tsx, app/utils/user-validation.ts, app/components/forms.tsx, tests/e2e/onboarding.test.ts and tests/db-utils.ts first. Turn SignupFormSchema into a factory that uses conformZodMessage.VALIDATION_UNDEFINED on the client and the Prisma lookup on the server, skip the other async refinements when the intent validates one field, add shouldValidate onBlur to useForm, and keep the honeypot and the session-creating transform as they are. Apply the same pattern to the email check in signup.tsx. Add a Vitest test for the factory and a Playwright test that sees the taken-username message before submit. Run npm run validate, quote the results and open a pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request that changes app/routes/_auth/onboarding/index.tsx and app/routes/_auth/signup.tsx, adds one Vitest file beside app/utils/user-validation.ts, and extends tests/e2e/onboarding.test.ts with one test. app/components/forms.tsx and the Field component are untouched, since errors already render through fields.username.errors.

The description holds the Vitest, ESLint, TypeScript and Playwright output from npm run validate, a short trace of the validation request the agent captured in the sandbox browser, showing the validate/username intent going to the action and the 400 coming back with only the username error, and the note that the pwned-password lookup now runs on submit only. The repository's Deploy workflow runs its lint, typecheck, Vitest and Playwright jobs on the branch.

Before merging, a reviewer decides whether a validation request should also be rate limited like the rest of the auth routes the stack already limits with express-rate-limit, since each blur on the username is now a database lookup, and whether the taken-username message should suggest an alternative. The agent leaves both as they are and names them.

Run it on every Linear issue labelled forms

In the Project that holds the repository, create an automation with a general form of this page's prompt and a linear trigger on linear.issue.labeled with forms in its labels. The issue text follows the prompt and fills in nothing, so the prompt says to read the issue that follows, find the form it names, apply the Conform pattern the onboarding form uses for any field whose validity only the server knows, add the two layers of tests and open a pull request that names the issue.

A designer who files an issue because the profile page only reports a taken username after submit gets a pull request with the browser trace in it. A later issue for the change-email form starts its own run, and the automation runs as the member who created it, in the Project that has the repository.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

Why run it on Rush?

Seeing a validation request work means a built app, a seeded database with a conflicting user, a browser that blurs the field and a captured request showing the intent, all of which the repository sets up through npm run setup and its mocks. The sandbox runs that setup, drives the browser and keeps the trace, so the pull request opens with the behaviour shown rather than promised.

The run's record keeps the full npm run validate output and the request the agent captured, so a reviewer checks the intent and the response rather than a sentence saying blur validation works. A team with several Epic Stack apps starts one run each, and every pull request is fitted to that app's own forms.

Frequently asked questions

Does this add a new route for the check?

No. Conform sends the validation request to the form's own action with an intent, and the action's existing schema: (intent) => ... branch handles it. The transform already returns session: null for any intent, so no account is created by a blur.

Why skip the password check during a username validation?

The pwned-password lookup in checkIsCommonPassword is a network call and the password field may still be empty when the username loses focus. Returning VALIDATION_SKIPPED for refinements the intent did not ask about keeps the request to one database read and avoids an error on a field the person has not reached.

What does the user see while the request is in flight?

The field keeps its last state until the action answers, then fields.username.errors renders the taken message through the existing Field component. The submit button is unaffected, so someone who types fast and submits still gets the same error from the full submit path.

Does the honeypot interfere with validation requests?

No. HoneypotInputs are part of the form, so each validation request carries the same hidden fields and checkHoneypot passes as it does for a real submit. A bot that fills the honeypot is rejected on validation and on submit alike.

More jobs like this: Turn a Linear label into a PR

Keep reading