When to use async in routes and when not?

[nilslindemann]

The chapter Async route components in the fresh docs confuses me. According to it, an async component conceptually inlines a GET handler.

However, in my tests, async was seemingly not necessary (and also not possible if I await nothing inside).

For example, if I rewrite the form submissions example ...

import { Handlers, PageProps } from "$fresh/server.ts";

const NAMES = ["Alice", "Bob", "Charlie", "Dave", "Eve", "Frank"];

interface Data {
  results: string[];
  query: string;
}

export const handler: Handlers<Data> = {
  GET(req, ctx) {
    const url = new URL(req.url);
    const query = url.searchParams.get("q") || "";
    const results = NAMES.filter((name) => name.includes(query));
    return ctx.render({ results, query });
  },
};

export default function Page({ data }: PageProps<Data>) {
  const { results, query } = data;
  return (
    // ... the jsx ...
  );
}

... to ...

const NAMES = ["Alice", "Bob", "Charlie", "Dave", "Eve", "Frank"];

export default function Page(req: Request) {  // notice, it is not async
  const url = new URL(req.url);
  const query = url.searchParams.get("q") || "";
  const results = NAMES.filter((name) => name.includes(query));

  return (
    // ... the jsx ...
  );
}

... then it still works.

So, is using async not necessary?

[marvinhagemeister]

Synchronous components are bog standard Preact components. Because of that they do not receive Request as an argument to the function, but rather a standard props object. This is typed as PageProps like in your first snippet. That in turn receives the request url via props.url, which makes your example accidentally work, even though you mistyped props as being Request. Both have a url property. What's really happening is this here:

// Sync route components receives props, NOT a Request instance
export default function Page(props: PageProps) {
  // The `props.url` property is already a `URL` instance,
  // because it's not a `Request` object, rather an object created by us.
  // So this line does basically `new URL(new URL(...))` which works too
  const url = new URL(props.url);
  const query = url.searchParams.get("q") || "";
  const results = NAMES.filter((name) => name.includes(query));

  // ...snip
}

So yes, that works. All route components have access to the request URL. If you only need to operate on that and don't need to to anything asynchronous, it's perfectly fine to use a standard Preact component. No need for async routes in this case.

Where it gets tricky though, and I guess where your confusion comes from, is that you typed props as Request which is wrong. You can verify that yourself by adding console.log(req instanceof Request) in your sync snippet. That will return false, because it's a props object and not a Request instance.

Besides the ability to do await inside an async route, the main difference is precisely that it doesn't receive props and instead has access to the full Request instance. This allows you to set request headers, completely bail out of rendering by doing a redirect, etc.

However, in my tests, async was seemingly not necessary (and also not possible if I await nothing inside).

What do you mean by "not possible"?

[nilslindemann]

Thanks a ton @marvinhagemeister that clarifies it.

What do you mean by "not possible"?

My mistake, I wrongly interpreted that orange underline in VS Code as an error. It is actually a warning by the Deno linter, and can be disabled by adding // deno-lint-ignore require-await to the line above.

Thanks for Fresh (and Deno and Deno Deploy)