SvelteKit Superactions

Call your server code from the client like normal functions.

🚧 This library is in an early state, and breaking changes will likely happen before the API is stabilised for a v1.0 release! 🚧

Documentation

Why?

While SvelteKit's data fetching patterns are great, but the ease-of-use of React Server Actions doesn't seem to have an equivalent in SvelteKit. The ability to just 'call a function' in the client-side, have it perform logic on the server and return the result to the client is sometimes very useful.

SvelteKit's form actions are a great fit for many cases, but they can be clunky when you want to call an endpoint without a form element, or when you need to send data that is too complex to be represented in FormData.

This library aims to provide additional tools alongside SvelteKit's API routes:

Features

• Type satefy between server and client
• Automatic JSON conversion (request/response)
• Schema validation
  • zod helper function
  • joi helper function

Installation

Install Superactions with your favourite package manager:

# npm, yarn, pnpm, bun, etc
npm i sveltekit-superactions

Usage

A minimal setup requires the following.

In a +server.ts file, define the actions that you want to use:

// src/routes/api/+server.ts
import { endpoint } from 'sveltekit-superactions';
import { db } from '$lib/server/db';
import { deleteTodo, findTodo, type TodoUpdate } from '$lib/server/handlers';

// Always attach the endpoint as a POST handler
export const POST = endpoint({
    // e is the RequestEvent provided by SvelteKit,
    // and the second argument is the request body decoded as JSON.
    editTodo: async (e, body: TodoUpdate) => {
        // The returned value is automatically serialized as JSON.
        // The client-side function gets its return type directly from the return type of its server action
        return await db.update(body.id, body);
    },

    // You can also just import handlers from other files and group them here.
    deleteTodo,

    // Or give them custom names
    my_handler: findTodo
});

// export the type of the endpoint, so that we get types in the client
export type API = typeof POST;

And in any Svelte component import the superActions function and the exported types to instantiate the client.

<!-- src/routes/+page.svelte -->
<script lang="ts">
    import { superActions } from 'sveltekit-superactions';
    import type { API } from './api/+server.js'; // exported API type

    // give the client the path and API types to instantiate it.
    const api = superActions<API>('/api');
</script>

{#await api.getTodos()}
    <p>Loading TODOs...</p>
{:then todos}
    <ul>
        {#each todos as todo}
            <li>
                {todo.text}
                <input type="checkbox" checked={todo.checked} />
            </li>
        {/each}
    </ul>
{/await}