nuxt-procedures

Nuxt Procedures

Nuxt module to define and easily consume your backend API in a validated and type-safe way using procedures and Zod schemas.

• 🏀 Online playground

Features

• Type-Safe API Layer: End-to-end type safety for your API calls.
• Zod Validation: Use Zod schemas to validate inputs and outputs.
• Automatic API Client: An apiClient is automatically generated based on your procedures.
• useFetch Integration: Seamlessly integrates with Nuxt's useFetch for easy data fetching in your components.
• superjson Support: Automatically handles serialization of complex data types.

Installation

Quick Install (Recommended)

Install and configure the module with a single command:

npx nuxi module add nuxt-procedures

This will add nuxt-procedures to your package.json and nuxt.config.ts.

You also need to install its peer dependency, zod:

npm install zod

Manual Install

1. Install the packages:

npm install nuxt-procedures zod

2. Add the module to your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ["nuxt-procedures"],
});

Usage

1. Define Procedures

Create .ts files in your server/procedures directory. The module will automatically create a corresponding client for each file.

Simple Example

For a simple input and output, you can use Zod schemas directly.

server/procedures/hello.ts:

import { z } from "zod";

export default defineProcedure({
  input: z.string(),
  output: z.string(),
  handler: async ({ input }) => {
    return `Hello, ${input}!`;
  },
});

Complex Example

For more complex scenarios, z.object is the way to go. This is useful for things like form submissions or creating database entries.

server/procedures/users/create.ts:

import { z } from "zod";

export default defineProcedure({
  input: z.object({
    name: z.string(),
    email: z.string().email(),
    role: z.enum(["admin", "user"]).default("user"),
  }),
  output: z.object({
    id: z.string(),
    name: z.string(),
    email: z.string(),
  }),
  handler: async ({ input, event }) => {
    // The event param gives you access to the request context and Nuxt utilities
    // For example, you can access request headers
    const headers = getRequestHeaders(event);
    console.log(headers);

    // In a real app, you would create a user in your database
    // The following is just an example of how you could get a db client
    const db = await useDB(event);
    const newUser = await db.user.create({
      data: input,
    });

    return newUser;
  },
});

2. Use the apiClient

The module automatically generates an apiClient that you can use in your components or pages. The structure of the apiClient mirrors your server/procedures directory.

useCall

The useCall method is a wrapper around Nuxt's useFetch and is the recommended way to call procedures from your Vue components.

Calling the simple hello procedure:

<script setup lang="ts">
const { data: greeting, pending } = await apiClient.hello.useCall("World");
</script>

<template>
  <p v-if="pending">Loading...</p>
  <p v-else>{{ greeting }}</p>
</template>

call

The call method makes a direct API call, without storing the result in the Nuxt payload as useFetch would. You would normally call procedures this way when you don't need to load data for the initial render of the component, but instead when triggering them in response to a form submission or some other event, same as when you would use $fetch.

// Calling the simple procedure
const greeting = await apiClient.hello.call("World");
// greeting is "Hello, World!"

// Calling the complex procedure
const newUser = await apiClient.users.create.call({
  name: "Andres",
  email: "andres@example.com",
});
// newUser is { id: '...', name: 'Andres', email: 'andres@example.com' }

Contribution

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest
npm run test
npm run test:watch

# Release new version
npm run release