Remix Mutations — Complex Data Mutation Patterns

In this tutorial, you will learn about Remix Mutations. We cover key concepts, practical examples, and best practices to help you master this topic.

Learn Remix mutations: handle complex mutations, batch operations, optimistic updates, and multi-step form workflows for data-heavy applications.

In this lesson, you'll implement advanced mutation patterns including batch operations, multi-step forms, and mutations that span multiple resources.

What You'll Learn

How to handle batch mutations, multi-step form workflows, mutations with side effects, and transactional operations.

Why It Matters

Real-world apps need complex mutations: creating a user and sending a welcome email, updating multiple records at once, or processing multi-step checkout flows.

Real-World Use

DodaZIP processes file uploads with multiple side effects: saving file metadata, updating storage quotas, and sending notifications—all in a single action.

flowchart LR
    A[Action] --> B[Validate]
    B --> C[Step 1: Create]
    C --> D[Step 2: Notify]
    D --> E[Step 3: Log]
    E --> F[Redirect]
    style A fill:#121212,color:#fff

Batch Mutation

export const action = async ({ request }) => {
  const formData = await request.formData();
  const ids = formData.getAll("ids");
  const action = formData.get("bulkAction");

  switch (action) {
    case "delete":
      await db.item.deleteMany({ where: { id: { in: ids } } });
      break;
    case "archive":
      await db.item.updateMany({ where: { id: { in: ids } }, data: { archived: true } });
      break;
    case "publish":
      await db.item.updateMany({ where: { id: { in: ids } }, data: { published: true } });
      break;
  }

  return redirect("/items");
};

Multi-Step Form

Track the current step with a hidden field:

export const action = async ({ request }) => {
  const formData = await request.formData();
  const step = parseInt(formData.get("step"));
  
  switch (step) {
    case 1:
      // Validate step 1 data and return or proceed
      return json({ step: 2, data: { /* step 1 data */ } });
    case 2:
      // Validate step 2 and combine with step 1
      return json({ step: 3, data: { /* combined data */ } });
    case 3:
      // Process complete form
      await processCompleteForm(formData);
      return redirect("/success");
  }
};

Transactional Mutation

Use database transactions for atomic operations:

export const action = async ({ request }) => {
  const formData = await request.formData();

  try {
    const result = await db.$transaction(async (tx) => {
      const order = await tx.order.create({ data: { /* ... */ } });
      await tx.inventory.updateMany({ where: { /* ... */ }, data: { /* ... */ } });
      await tx.payment.create({ data: { orderId: order.id, /* ... */ } });
      return order;
    });

    return redirect(`/orders/${result.id}`);
  } catch (error) {
    return json({ error: "Transaction failed" }, { status: 500 });
  }
};

Mutation with Side Effects

Send emails, notifications, or trigger Webhooks after mutations:

export const action = async ({ request }) => {
  const formData = await request.formData();
  const user = await createUser(formData);

  // Side effects (fire and forget)
  sendWelcomeEmail(user.email).catch(console.error);
  notifyAdmins("new_user", user).catch(console.error);
  await logAuditTrail("user.created", user.id);

  return redirect(`/users/${user.id}`);
};

Common Mistakes

1. Not wrapping related mutations in transactions: If one mutation fails, partial changes remain. Use transactions for atomic operations.
2. Blocking the response on side effects: Side effects like emails should run asynchronously. Don't make the user wait for them.
3. Not handling partial failures: Batch operations should report which items succeeded and which failed.
4. Losing multi-step form state on refresh: Store multi-step state in the session, not just in memory.
5. Over-fetching in mutation responses: Return only what the UI needs after a mutation, not full data sets.

Practice Questions

1. How do you handle batch operations in an action? Answer: Use formData.getAll("fieldName") to get multiple values, then perform the operation on all selected items.

2. What is a database Transaction? Answer: A set of operations that all succeed or all fail together. If any step fails, all changes are rolled back.

3. How do you implement a multi-step form? Answer: Track the current step with a hidden input. The action validates the current step and returns the next step or processes the complete form.

4. Where should side effects (like sending emails) run? Answer: After the main mutation succeeds. Run them asynchronously or in the background to avoid delaying the response.

Challenge

Build a checkout flow with three steps: cart review (step 1), shipping address (step 2), payment (step 3). Use a single action that tracks the current step and processes the order only on the final step.

Mini Project

Create a project management app where a single action creates a project, assigns team members, creates default tasks, sends invitation emails, and logs the audit trail. Use transactions for atomicity.

FAQ

What's Next

Learn about Remix Optimistic UI for instant feedback during mutations.