antfu / nuxt-server-fn

Server functions in client for Nuxt 3

nuxt-server-fn

Server functions in client for Nuxt 3. Experiments of this RFC.

⚠️ Experimental ⚠️ APIs are subject to change.

Install

npm i -D nuxt-server-fn

// nuxt.config.ts
import { defineNuxtConfig } from 'nuxt'

export default defineNuxtConfig({
  modules: [
    'nuxt-server-fn',
  ],
})

Usage

Expose server functions under server/functions/*.ts

// server/functions/foo.ts

export function myFunction(name: string) {
  return `Hello ${name} from server`
}

On the client side:

const { myFunction } = useServerFunctions()
const msg = await myFunction('Nuxt') // 'Hello Nuxt from server'

Checkout the playground example.

Client Functions

Client functions can be auto imported.

useServerFunctions()

Use server functions in client. A POST request to Nuxt server will be created for function calls.

By default it's aggressively cached using the useState() hook under the hood. Multiple calls to the same arguments will reuse the same result across client and server sides for hydration.

const serverFn = useServerFunctions()
const msg1 = await serverFn.myFunction('Nuxt')
const msg2 = await serverFn.myFunction('Nuxt') // functions with same arguments will be cached, only one request

To opt-out the caches, pass cache: false:

const serverFn = useServerFunctions({ cache: false })
const msg1 = await serverFn.myFunction('Nuxt')
const msg2 = await serverFn.myFunction('Nuxt') // two requests will be fired

Or you can use $cached or $cacheless property to toggle between them for each call:

const serverFn = useServerFunctions() // cached by default

const msg1 = await serverFn.myFunction('Nuxt')

const msg2 = await serverFn.$cacheless.myFunction('Nuxt') // opt-out cache for this call

const serverFn = useServerFunctions({ cache: false }) // no cache

const msg1 = await serverFn.myFunction('Nuxt') // no cache

const msg2 = await serverFn.$cached.myFunction('Nuxt') // opt-in cache for this call

Server

Named exported inside server/functions/*.ts will be available to client automatically.

Request Context

Request context is available as this for functions. When using TypeScript, the type of this needs to be specified explicitly as H3Event from h3.

For example:

import type { H3Event } from 'h3'

export function myFunction(this: H3Event, firstArg: any) {
  const { req, res } = this
  const body = useBody(this)
  // ...
}

Sponsors

License

MIT License © 2022 Anthony Fu