Actions

Data mutations are done through Route actions. When the action completes, all loader data on the page is revalidated to keep your UI in sync with the data without writing any code to do it.

Route actions defined with action are only called on the server while actions defined with clientAction are run in the browser.

Client Actions

Client actions only run in the browser and take priority over a server action when both are defined.

import { Form } from "@orange-js/orange";
import { someApi } from "./api";

export async function clientAction({ request }: ClientActionFunctionArgs) {
  let formData = await request.formData();
  let title = formData.get("title");
  let project = await someApi.updateProject({ title });
  return project;
}

export default function Project() {
  const actionData = useActionData<typeof clientAction>();
  return (
    <div>
      <h1>Project</h1>
      <Form method="post">
        <input type="text" name="title" />
        <button type="submit">Submit</button>
      </Form>
      {actionData ? <p>{actionData.title} updated</p> : null}
    </div>
  );
}

Server Actions

Server actions only run on the server and are removed from client bundles.

import { Form, useActionData } from "@orange-js/orange";
import { fakeDb } from "../db";

export async function action({ request }: ActionFunctionArgs) {
  let formData = await request.formData();
  let title = formData.get("title");
  let project = await fakeDb.updateProject({ title });
  return project;
}

export default function Project() {
  const actionData = useActionData<typeof action>();

  return (
    <div>
      <h1>Project</h1>
      <Form method="post">
        <input type="text" name="title" />
        <button type="submit">Submit</button>
      </Form>
      {actionData ? <p>{actionData.title} updated</p> : null}
    </div>
  );
}

Durable Objects

Similar to loaders, actions can be used with Durable Objects. You must supply an id function that returns the name or a constant id string for the Durable Object to use.

import { RouteDurableObject, Form, ActionFunctionArgs, IdentifierLoaderArgs } from "@orange-js/orange";

export class ProjectObject extends RouteDurableObject<Env> {
  async action({ request }: ActionFunctionArgs) {
    const formData = await request.formData();
    const task = formData.get("task");

    this.ctx.storage.sql.exec("INSERT INTO tasks (title) VALUES (?)", task);
  }

  static id({ params }: IdentifierLoaderArgs) {
    return params.id;
  }
}

export default function Project() {
  return (
    <div>
      <h1>Project</h1>
      <Form method="post">
        <input type="text" name="task" placeholder="Add a task" />
        <button type="submit">Submit</button>
      </Form>
    </div>
  );
}

Calling Actions

Actions are called declaratively through <Form> and imperatively through useSubmit (or <fetcher.Form> and fetcher.submit) by referencing the route's path and a "post" method.

Calling actions with a Form

import { Form } from "@orange-js/orange";

function SomeComponent() {
  return (
    <Form action="/projects/123" method="post">
      <input type="text" name="title" />
      <button type="submit">Submit</button>
    </Form>
  );
}

This will cause a navigation and a new entry will be added to the browser history.

Calling actions with useSubmit

You can submit form data to an action imperatively with useSubmit.

import { useCallback } from "react";
import { useSubmit } from "@orange-js/orange";
import { useFakeTimer } from "fake-lib";

function useQuizTimer() {
  let submit = useSubmit();

  let cb = useCallback(() => {
    submit({ quizTimedOut: true }, { action: "/end-quiz", method: "post" });
  }, []);

  let tenMinutes = 10 * 60 * 1000;
  useFakeTimer(tenMinutes, cb);
}

This will cause a navigation and a new entry will be added to the browser history.

Calling actions with a fetcher

Fetchers allow you to submit data to actions (and loaders) without causing a navigation (no new entries in the browser history).

import { useFetcher } from "@orange-js/orange";

function Task() {
  let fetcher = useFetcher();
  let busy = fetcher.state !== "idle";

  return (
    <fetcher.Form method="post" action="/update-task/123">
      <input type="text" name="title" />
      <button type="submit">{busy ? "Saving..." : "Save"}</button>
    </fetcher.Form>
  );
}

They also have the imperative submit method.

fetcher.submit(
  { title: "New Title" },
  { action: "/update-task/123", method: "post" }
);