@roostjs/start

Bridges the Roost framework with TanStack Start. Provides the context bridge, middleware factory, and server function wrappers.

Installation

bun add @roostjs/start

Configuration

No environment variables are required. @roostjs/start depends on the Application instance you construct and pass into its factories.

createRoostMiddleware API

createRoostMiddleware(factory: () => Application): TanStackMiddleware

Create a TanStack Start middleware that bootstraps a Roost Application and attaches it to the server context. The factory function is called once per request. Returns a middleware compatible with TanStack Start's createMiddleware() system.

import { createRoostMiddleware } from '@roostjs/start';
import { Application } from '@roostjs/core';
import { CloudflareServiceProvider } from '@roostjs/cloudflare';

export const roostMiddleware = createRoostMiddleware(() => {
  const app = new Application({});
  app.register(CloudflareServiceProvider);
  return app;
});

roostFn API

roostFn(middleware: TanStackMiddleware, handler: (roost: RoostContext) => Promise<T>): ServerFunction<T>

Wrap a TanStack Start server function with Roost context injection. The handler receives a RoostContext object with access to the container and resolved application. Use when the server function takes no user input.

import { roostFn } from '@roostjs/start';
import { roostMiddleware } from '../middleware';

const listUsers = roostFn(roostMiddleware, async (roost) => {
  return roost.container.resolve(UserService).findAll();
});

roostFnWithInput API

roostFnWithInput(middleware: TanStackMiddleware, validator: (raw: unknown) => TInput, handler: (roost: RoostContext, input: TInput) => Promise<T>): ServerFunction<TInput, T>

Wrap a TanStack Start server function with Roost context injection and typed input. The validator function receives the raw deserialized input and returns the typed value. Throw from the validator to reject invalid input.

import { roostFnWithInput } from '@roostjs/start';
import { roostMiddleware } from '../middleware';

const getUser = roostFnWithInput(
  roostMiddleware,
  (d: { id: string }) => d,
  async (roost, input) => {
    return roost.container.resolve(UserService).find(input.id);
  }
);

Context Utilities

bootApp(createApp: () => Application): Application

Boot the Roost application singleton. Calls createApp once and caches the result. Subsequent calls return the cached instance. Used by createRoostMiddleware internally; call directly when you need the app outside of a middleware context.

getApp(): Application

Retrieve the cached application instance. Throws if bootApp() has not been called yet.

createRoostContext(app: Application): RoostServerContext

Create a per-request scoped context from the application. Returns a RoostServerContext with a scoped container. Called once per request by createRoostMiddleware.

resetAppCache(): void

Clear the cached application instance. Use in tests to ensure each test suite starts with a fresh application.

StartServiceProvider

Service provider that registers @roostjs/start integrations in the Roost container. Register this provider when using bootApp directly to ensure TanStack Start bindings are available.

Types

interface RoostServerContext {
  container: RoostContainer;
  app: Application;
}

interface RoostMiddlewareContext {
  roost: RoostServerContext;
}