https://github.com/antfu/nuxt-server-fn

Server functions in client for Nuxt 3
https://github.com/antfu/nuxt-server-fn

Last synced: about 1 month ago
JSON representation

Server functions in client for Nuxt 3

• Host: GitHub
• URL: https://github.com/antfu/nuxt-server-fn
• Owner: antfu
• License: mit
• Created: 2022-05-16T06:17:55.000Z (over 2 years ago)
• Default Branch: main
• Last Pushed: 2024-04-07T22:56:03.000Z (5 months ago)
• Last Synced: 2024-07-19T10:03:33.636Z (about 2 months ago)
• Language: TypeScript
• Homepage:
• Size: 433 KB
• Stars: 205
• Watchers: 6
• Forks: 7
• Open Issues: 4
• Metadata Files:
  • Readme: README.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE

Awesome Lists containing this project

README

        
# nuxt-server-fn

[![NPM version](https://img.shields.io/npm/v/nuxt-server-fn?color=a1b858&label=)](https://www.npmjs.com/package/nuxt-server-fn)

Server functions in client for Nuxt 3. [Experiments of this RFC](https://github.com/unjs/nitro/discussions/235).

> ⚠️ Experimental ⚠️ APIs are subject to change.

## Install

```bash

npm i -D nuxt-server-fn

```

```ts

// nuxt.config.ts

import { defineNuxtConfig } from 'nuxt'

export default defineNuxtConfig({

  modules: [

    'nuxt-server-fn',

  ],

})

```

## Usage

Expose server functions under `server/functions/*.ts`

```ts

// server/functions/foo.ts

export function myFunction(name: string) {

  return `Hello ${name} from server`

}

```

On the client side:

```ts

const { myFunction } = useServerFunctions()

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

```

Checkout [the playground example](https://github.com/antfu/nuxt-server-fn/blob/main/playground).

## 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](https://v3.nuxtjs.org/api/composables/use-state) under the hood. Multiple calls to the same arguments will reuse the same result across client and server sides for hydration.

```ts

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`:

```ts

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:

```ts

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

```

```ts

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:

```ts

import type { H3Event } from 'h3'

export function myFunction(this: H3Event, firstArg: any) {

  const { req, res } = this

  const body = useBody(this)

  // ...

}

```

## Sponsors



  

    

  



## License

[MIT](./LICENSE) License © 2022 [Anthony Fu](https://github.com/antfu)