I just came across this and am trying to find any docs or explainer, is there one?
Looks like this was done in a workshop

When following the setup guide, a super basic example complains of a missing QueryClient in the context.

Reproduction:
https://stackblitz.com/edit/nextjs-an43th?file=pages%2F_app.tsx

The SWR API allows users to opt out of fetching by having a null key:

useSWR(() => someCondition ? null : "/my/key", ...)

I think we can support that too with our API. We can accept null and/or a function that resolves into a null/object to allow conditional fetching

Summary

Currently the Form.encType has no effect when using @next-fetch/swr/form.
Enabling encTypes like multipart/form-data would allow all kinds of common features like File Uploads.

Basic example

File: pages/file-upload.tsx

export default function MyImageUpload() {
  const mutation = useImageUpload();
  return (
    <Form encType="multipart/form-data" mutation={mutation}>
      <input type="file" name="someFile" accept="image/*" />
      <button type="submit">Submit</button>
    </Form>
  );
}

File: pages/api/image.swr.ts

import { zfd } from "zod-form-data";

export const useImageUpload = mutation(
  zfd.formData({ someFile: zfd.file() }),
  async (formData) => {
    const file: File = formData.get('someFile')
    // ...
    return { message: "Success" };
  }
);

Motivation

Today next-fetch only supports application/x-www-form-urlencoded forms. These forms are quite limited, since they only allow structured string data.

Adding multipart/form-data support, would allow sending all kind of hybrid data (strings, blobs, etc) to the server while still being able to support native html forms (hookResponse).

Challenges

• FormData inside Edge Runtime and Node.js still lacks in some features.
• FormData blobs need to be lazy on the server.
• zod currently doesn't support ES Maps afaik. Nevertheless zod-form-data can help here.
• ...to be continued

Adoption strategy

The type definition of @next-fetch/swr/form element should be updated for the time multipart/form-data is not supported, otherwise a breaking change will be needed when the feature has been implemented.

export function Form<Data, Error>({
  mutation,
  mutationConfig,
  ...props
}: React.HTMLProps<HTMLFormElement> &
  React.PropsWithChildren<{
    mutation: HookWithFormSubmission<Data, Error>;
    mutationConfig?: SWRMutationConfiguration<Data, Error>;
+    encType?: 'application/x-www-form-urlencoded'
  }>) {
  const { formProps } = useForm(mutation, mutationConfig);
  return createElement("form", { ...formProps, ...props }, props.children);
}

Later this feature can be allowed by adding multipart/form-data to the encType union.

export function Form<Data, Error>({
  mutation,
  mutationConfig,
  ...props
}: React.HTMLProps<HTMLFormElement> &
  React.PropsWithChildren<{
    mutation: HookWithFormSubmission<Data, Error>;
    mutationConfig?: SWRMutationConfiguration<Data, Error>;
-    encType?: 'application/x-www-form-urlencoded' 
+    encType?: 'application/x-www-form-urlencoded' | 'multipart/form-data'
  }>) {
  const { formProps } = useForm(mutation, mutationConfig);
  return createElement("form", { ...formProps, ...props }, props.children);
}

Links

• https://developer.mozilla.org/en-US/docs/Web/API/FormData/FormData?retiredLocale=de
• https://www.npmjs.com/package/zod-form-data
• https://xhr.spec.whatwg.org/#dom-formdata

# Problem

When submitting this mutation, an Unhandled Runtime Error is thrown. next-fetch should let us know there’s not an input with name="content"

// pages/api/todos.swr.ts
export const useCreateTodo = mutation(
  z.object({
    content: z.string(),
  }),
  async ({ content }) => {
    // ...
  }
);

// pages/index.tsx

export default function Home() {
  const mutation = useCreateTodo();
  
  <Form mutation={mutation}>
      <label htmlFor='newTodo'>Add a new todo</label>
      <input
          type='text'
          name='newTodo'
          id='newTodo'			
          placeholder='New todo'
        />
      <button type='submit'>Add todo</button>
  </Form>
}

Solution Description

When using the <Form /> component, there should be typesafety letting the user know they don't have an <input /> that aligns with their mutation's input.

I'd expect the same typesafety if programmatically calling the mutation like so:

const handleSubmit = async (e: FormEvent<HTMLFormElement>) => {
  e.preventDefault();
  const values = new FormData(formRef.current as HTMLFormElement);
  const data = Object.fromEntries(values);
  createTodo.trigger(data);
};

This is the error on data being passed to trigger

Problem

There isn't a convenient way to get the types of inputs/outputs for queries/mutations.

Currently, I can get the output of a query like so:

I'm not sure how to get the input.

Solution Description

I like how tRPC has type helpers. Maybe we can achieve something similar. Here's a reference to tRPC's Inference Helpers

Currently there is no declarative way to conditionally fetch data.

Future

This is how an implementation could look like following the swr convention.

import { useTestQuery } from "./api/test.swr";

export default function IndexPage({ id }) {
  const testQuery = useTestQuery(id ? { id } : null);
  return (
    ...
  );
}

fetch when parsing the received URL are adding unexpected resources, making the request to fail with HTTP 404

// .env.local
BASE_FETCH_URL=http://localhost:3000

by using like this:
process.env.BASE_FETCH_URL + '/api/apply/get-session-user'

results in the following URL:
http://localhost:3000/api/apply/get-session-user

This URL are getting well concatenated (also using template literals). You can confirm it by checking the console.log present into the Screenshot below
But into the browser, it's getting requested with "extra" resources right after the top-level domain (or the server port in my case)
Request URL: http://localhost:3000/apply/undefined/api/apply/get-session-user
Look at the first resource /apply/undefined. This resource shouldn't be present since it wasn't part of the original URL

Detail... It works by hard-coding the URL and eventually works with the relative resource path

Summarizing:

• It works: await fetch('http://localhost:3000/api/apply/get-session-user')

• It works: await fetch('http://localhost:3000' + '/api/apply/get-session-user')

• It works sometimes: await fetch('/api/apply/get-session-user')

• It doesn't works: await fetch(process.env.BASE_FETCH_URL + '/api/apply/get-session-user')

Problem

Currently, inputs are required to run queries/mutations

Solution Description

Make inputs optional.

https://github.com/vercel-labs/next-swr-endpoints/blob/9c93696201d50f1034544115d47c0ea0291f945b/packages/next-swr-endpoints/src/swr-server-endpoint-loader.ts#L49

.safeParse() will return a result object instead of throwing an error.

@Schniz Gal! Does this support SSR? If it doesn't, can it? I ask because I heavily use tRPC and can get SSR done with it.

If we can get this to do SSR, I would absolutely switch to this and make tons of contributions to make us a documentation site and everything. This could be a huge addition for the community!

Problem

Thanks for the phenomenal work. Having used trpc, I can't wait to have a native nextjs solution.

Something that works well in trpc is the notion of a context builder. We can build the authentication state for instance and provide the current user for all query mutation automatically.

I know we could do that on every query mutation manually / and or with an Higher Order Function but I am wondering if there is any plan to have that in scope.

How can I help ?

When I asked for feedback, one person told me he does not like the fact this library forces you to declare a type in advance using zod, alternative libraries, or pass any object with the function parse.

So their idea was:

export const useMyHook = query((value: { untrusted: string }) => {
  return "Hello, world!"
});

I am not so sure about it because I think we should have good defaults and suggest better and safer code. Maybe we can do something like:

import { unsafe } from 'next-swr-endpoints';

export const useMyHook = query(unsafe, (value: { untrusted: string }) => {
 ...
}));

// or as a function, because then I think that we can declare it as `unsafe<T>(): T`
export const useMyHook = query(unsafe(), (value: { untrusted: string }) => {
 ...
}));

This is a mind blowing project and I was just changing the code for my site. And I have my API routes and everything in the src folder.

But instead of sending request to /api/whatever it sends request to /src/pages/api/whatever

Is there a configuration I have to do if the pages dir is in src

Currently I'm unable to authenticate user requests since doing so with NextAuth requires the Request and Response objects to check auth.

I'd like to propose an API similar to this, exposing a ctx object:

// pages/api/message.swr.tsx
import { query } from "@next-fetch/swr";
import z from "zod";

import { authOptions } from 'pages/api/auth/[...nextauth]';
import { unstable_getServerSession } from "next-auth/next";

export const useMessage = query(
  async function ({ ctx }) {
    const session = await unstable_getServerSession(ctx.req, ctx.res, authOptions)
    return { hello: `world, ${session.user.name}` };
  }
);

Additionally, the documentation is misleading:

export const useMessage = query(
  // use zod or other input validation libraries
  z.object({
    name: z.string(),
  }),
  async function ({ name }) {
    // this.request is a `Request` instance            <------------ this.request is not available here
    return { hello: "world, " + name };
  }
);

The idea behind this feature is to enable long-running clients to react to changes in the backend schemas. Imagine you have an endpoint that returns { version: 1, data: string } and then while the customer is on your app, the server redeploys and now it returns { version: 2, result: string }. You probably want to make a hard-refresh, or at least show an error.

The suggested API would be something like:

import { query } from 'next-swr-endpoints';
export const useNoClientTypecheck = query(myParser, (value) => ...)
export const useWithClientTypecheck = query({ input: myParser, output: anotherParser }, value => ...)