frame-master-plugin-server-object

Frame-Master plugin to expose server-side objects or functions to the client, with automatic serialization and dynamic fetching support. Enables seamless sharing of server logic or data with the client in Bun-based Frame-Master projects.

Installation

bun add frame-master-plugin-server-object [email protected]

Usage

import type { FrameMasterConfig } from "frame-master/server/types";
import framemasterpluginserverobject from "frame-master-plugin-server-object";

const config: FrameMasterConfig = {
  HTTPServer: { port: 3000 },
  plugins: [framemasterpluginserverobject()],
};

export default config;

Features

• Exposes server-side objects or functions to the client, using a configurable prefix (default: Server).
• Supports both static (build-time) and dynamic (runtime) server object exports.
• Automatically serializes and deserializes server objects using superjson.
• Dynamic server objects are fetched via a special API route and executed on the server at runtime.
• Caches dynamic server object functions for efficient repeated access.
• Configurable source directory and export prefixes.
• Get Request in Dynamic Server Object with getRequest(arguments).
• Custom client-side parsers for advanced response handling with customClientParser.
• Custom server-side parsers for build-time transformation with customServerParser.
• Optional runtime parsing support for custom server parsers.

How It Works

1. During build, scans your source files for exports starting with a specified prefix (default: Server) or an optional dynamic prefix.
2. Static server objects are serialized and inlined for client use.
3. Dynamic server objects are replaced with a client function that fetches and executes the server object at runtime arguments must be serializable.
4. A special server route is set up to handle dynamic object requests, executing the function and returning the result: /__server_object_dynamic

Options

You can configure the plugin with the following options:

framemasterpluginserverobject({
  prefix: "Server", // Export prefix to identify server objects (default: "Server")
  dynamicPrefix: "DynamicServer", // Optional dynamic prefix for runtime-fetched server objects
  src: "src/server", // Optional base path to scan for server objects
  customClientParser: [
    {
      prefix: "MyClient",
      parser: ({ object, req, props }) => {
        // Custom parsing logic for client-side response
        return JSON.stringify(object);
      },
      buildParser: (res) => res.json(), // Optional: transform response at build time
    },
  ],
  customServerParser: [
    {
      prefix: "MyServer",
      parser: (object, filePath, objectName) => {
        // Return string representation for client-side access
        return JSON.stringify(object);
      },
      enableRuntimeParsing: false, // Enable runtime parsing (default: false)
    },
  ],
});

Usecase

export const DynamicServerGetter = async (id: string) => {
  // SQL query or fetch external data
  return await fetch(`https://exemple.com/api/${id}`).then((res) => res.json()); // must be serializable
};

export const ServerObject = Bun.file("./my-file.txt").text(); // must be serializable

// client side
console.log(ServerObject, await DynamicServerGetter("random-id"));

License

MIT