Documentation navigation

Vite plugin

Vite plugin

Configure Foldkit build integration and understand its build identity contract.

The @wsagency/wseffect-vite-plugin provides the foldkit() plugin factory for Foldkit development and builds. Install it with Foldkit, Vite 8.3.4, Effect ^4.0.5, and @effect/platform-browser@^4.0.5:

pnpm add -D @wsagency/wseffect-vite-plugin@0.1.0-rc.1 @wsagency/wseffect-foldkit@0.1.0-rc.1 vite@8.3.4 effect@^4.0.5 @effect/platform-browser@^4.0.5
import { foldkit } from '@wsagency/wseffect-vite-plugin'
export default { plugins: [foldkit()] }

For a standalone Foldkit plugin build, deployment identity is optional unless your server/client rendering needs a shared identity; set it with foldkit({ buildId: 'deployment-id' }) or FOLDKIT_BUILD_ID. The plugin does not derive this value from Git. By contrast, the app package’s Vite integration computes a WSEFFECT_BUILD_ID from the app’s Git metadata or requires that variable for Git-less builds; it uses that ID for version polling and update detection. Keep the two package-specific settings distinct. See Vite and chunking and the generated plugin export references. This is a separately maintained snapshot of upstream plugin source, not an upstream-affiliated release.

Package entry point

@wsagency/wseffect-vite-plugin · MIT · source · MIT license · WS-AGENCY-NOTICE · THIRD-PARTY-NOTICES

This entry point is published in @wsagency/wseffect-vite-plugin@0.1.0-rc.1. Import it from the package subpath shown below; the signatures and documentation are read from the installed package declarations.

import * as Wseffect from '@wsagency/wseffect-vite-plugin'

Exported declarations

brandDistDirectory

brandDistDirectory: (packageRoot: string, packageName: string) => BrandDistResult

BrandDistResult

export type BrandDistResult = Readonly<{
    brandedCount: number;
    skippedCount: number;
}>;

foldkit

foldkit: (options?: FoldkitPluginOptions) => Array<Plugin>

FOLDKIT_FETCH_MODULE_ID

Vite module id of the fetch handler Foldkit emits as the server entry.

FOLDKIT_FETCH_MODULE_ID = "virtual:foldkit/fetch"

foldkitBuild

Builds a Web `fetch` handler alongside the browser build, and generates static HTML from the server entry, inside one `vite build`. Vite builds both environments, so a deployment target that runs `vite build` gets the browser and server bundles. The `fetch` handler and generated pages use the server entry's `renderDocument` export with the emitted browser assets. The browser build has a script input and emits no HTML until prerendering. The server bundle's default export is `{ fetch }`.

foldkitBuild: (serverEntry: string, options: FoldkitBuildOptions) => Plugin<FoldkitBuildApi>

FoldkitBuildApi

The `foldkit:build` plugin's public integration API.

export type FoldkitBuildApi = Readonly<{
    /** Configured application source entry. */
    serverEntry: string;
    /** Virtual module used to bundle the fetch handler. */
    fetchModuleId: typeof FOLDKIT_FETCH_MODULE_ID;
    /**
     * Read after a successful `await builder.buildApp()`. Throws before Foldkit
     * finalizes or after another client or server build starts. Later plugin failures
     * still require callers to await the full build successfully.
     */
    getBuildMetadata: () => FoldkitBuildMetadata;
}>;

FoldkitBuildManifest

The decoded shape of `foldkit.build.json`. A deployment host decodes the manifest before using it. The Schema rejects unknown versions rather than letting the host read missing fields.

export type FoldkitBuildManifest = typeof FoldkitBuildManifest.Type;

FoldkitBuildManifest

What an `ssr.build` build produced, written beside the server bundle. An SSR host serves generated paths as files and sends requests without a matching file to the server entry. A static-only SSG host serves the files and leaves other paths as misses.

FoldkitBuildManifest: Schema.Struct<{
    /**
     * The shape of this document. A consumer decodes before reading and refuses
     * a version it does not know, so a manifest written by a newer Foldkit is a
     * clear refusal rather than a field silently read as undefined.
     */
    readonly schemaVersion: Schema.Literals<readonly [1]>;
    /**
     * Where the browser build was written, as a POSIX path relative to the Vite
     * root. Relative and normalized so a manifest survives being moved with the
     * build it describes.
     */
    readonly client: Schema.String;
    /** Where the server build was written, on the same terms as {@link client}. */
    readonly server: Schema.String;
    /** The server build's entry file, relative to `server`. */
    readonly serverEntry: Schema.String;
    /** Every path this build generated a page for, in the order it generated. */
    readonly prerendered: Schema.$Array<Schema.String>;
}>

FoldkitBuildMetadata

The serializable, frozen snapshot of a completed Foldkit build.

export type FoldkitBuildMetadata = typeof FoldkitBuildMetadata.Type;

FoldkitBuildMetadata

Completed application build data for an in-process deployment integration.

FoldkitBuildMetadata: Schema.Struct<{
    /** Absolute resolved Vite application root. */
    readonly root: Schema.String;
    /** Absolute resolved browser output directory. */
    readonly clientDirectory: Schema.String;
    /** Absolute resolved server output directory. */
    readonly serverDirectory: Schema.String;
    /** Absolute path to the emitted fetch handler. */
    readonly serverEntry: Schema.String;
    /** Portable data also written to `foldkit.build.json`. */
    readonly manifest: Schema.Struct<{
        /**
         * The shape of this document. A consumer decodes before reading and refuses
         * a version it does not know, so a manifest written by a newer Foldkit is a
         * clear refusal rather than a field silently read as undefined.
         */
        readonly schemaVersion: Schema.Literals<readonly [1]>;
        /**
         * Where the browser build was written, as a POSIX path relative to the Vite
         * root. Relative and normalized so a manifest survives being moved with the
         * build it describes.
         */
        readonly client: Schema.String;
        /** Where the server build was written, on the same terms as {@link client}. */
        readonly server: Schema.String;
        /** The server build's entry file, relative to `server`. */
        readonly serverEntry: Schema.String;
        /** Every path this build generated a page for, in the order it generated. */
        readonly prerendered: Schema.$Array<Schema.String>;
    }>;
}>

FoldkitBuildOptions

How `vite build` builds a server entry and what it generates from it.

export type FoldkitBuildOptions = Readonly<{
    /** Root-relative browser script entry resolved by Vite, such as `'/src/entry.ts'`. Import stylesheets from this module. */
    clientEntry: string;
    /** Where the browser build is written. */
    clientOutDir?: string;
    /** Where the server build is written. */
    serverOutDir?: string;
    /**
     * Generate static HTML for a set of URLs after both builds. `true` takes the
     * paths from the entry's `prerenderPaths` export.
     */
    prerender?: boolean | FoldkitPrerenderOptions;
}>;

FoldkitPluginOptions

Options for the `foldkit` Vite plugin.

export type FoldkitPluginOptions = Readonly<{
    /**
     * By default, the dev server hosts the DevTools MCP relay and publishes its
     * address for the MCP server to find. Middleware and HTTPS servers use a
     * separate loopback listener. Published addresses carry an access token.
     *
     * A number starts an unauthenticated listener on that port on every
     * interface; set `FOLDKIT_DEVTOOLS_MCP_PORT` in the MCP server to match.
     * `false` disables the relay. Vitest never starts it.
     */
    devToolsMcpPort?: number | false;
    /**
     * Serve server-rendered pages from the Vite dev server, and, with
     * `ssr.build`, emit a Web `fetch` handler as the server bundle. When
     * set, `vite` passes HTML navigations that fall through Vite, plus
     * non-GET requests, to `renderPage` from the module at
     * `ssr.serverEntry`. When `undefined` (the default), the dev server
     * serves the client entry only.
     */
    ssr?: Omit<FoldkitSsrOptions, 'buildId' | 'quietStandDown' | 'clientEntry' | 'containerId'> & (Readonly<{
        /** Root-relative browser script for the server entry's code-rendered document. */
        clientEntry: string;
        containerId?: never;
        /**
         * Build a Web `fetch` handler alongside the browser build, and generate
         * static HTML from the server entry, inside this project's own
         * `vite build`. The handler is the server bundle: Node and Workers
         * both run it. `true` builds it with the default output directories
         * and generates nothing.
         *
         * When this is absent, `vite build` builds the browser bundle only.
         */
        build?: boolean | Omit<FoldkitBuildOptions, 'clientEntry'>;
    }> | Readonly<{
        /** Use a custom template-based development and build pipeline. */
        clientEntry?: never;
        containerId?: string;
        build?: false;
    }>);
    /**
     * An explicit identity for the deployment this build belongs to. Foldkit
     * normally generates an opaque identity when one Vite app build coordinates
     * the client and server artifacts, then compiles it into the framework in
     * both. Hydration compares that value against the id the server stamped and
     * refuses a page from another deployment before adopting its DOM.
     *
     * Set this when the client and server are built separately, or when the id
     * should name a deployment in another system. The `FOLDKIT_BUILD_ID`
     * environment variable supplies the same override when this option is
     * absent. Give every artifact the same value. It is published in the page,
     * so it must not be a secret.
     *
     * Reusing an override across deployments makes stale pages appear current.
     * Use a value that changes whenever the deployment's rendering inputs can
     * change.
     */
    buildId?: string;
}>;

FoldkitPrerenderOptions

How a build materializes the URLs a server entry can render.

export type FoldkitPrerenderOptions = Readonly<{
    /**
     * The paths to generate. Defaults to the `prerenderPaths` the server entry
     * exports, so the application names its own static routes.
     */
    paths?: ReadonlyArray<string>;
    /**
     * The origin used for `Request.url` while generating, such as
     * `'https://app.example'`. This option does not set canonical or Open Graph
     * metadata. It affects those fields only when the server entry derives them
     * from `Request.url`, in which case it should match the published origin.
     */
    origin?: string;
}>;

foldkitSsr

Serves server-rendered pages from the Vite dev server. Vite retains ownership of configured proxies, source modules, HMR, and assets. Requests that fall through load the server entry through Vite's SSR module loader, call its `renderPage` with a Web `Request`, and send the resulting Web `Response`. Vite's host validation applies before either owner. Foldkit then validates and normalizes the request target before Vite or the server entry can resolve it. Vite's CORS option applies only to Vite-owned responses, while the server entry owns CORS for application responses. Server entry edits take effect without a restart.

foldkitSsr: (options: FoldkitSsrOptions) => Plugin

FoldkitSsrOptions

Options for serving server-rendered pages from the Vite dev server.

export type FoldkitSsrOptions = Readonly<{
    /**
     * Module path of the server entry, resolved by Vite (e.g.
     * `'/src/entry.server.ts'`). The module must export a `renderPage`
     * function taking a Web `Request` and returning a
     * `Promise<EntryResult>`.
     */
    serverEntry: string;
    /**
     * Root-relative browser script entry for a code-rendered document. The server entry must
     * also export `renderDocument(application, assets)`. When absent, the dev
     * host uses `index.html` for a custom template-based build pipeline.
     */
    clientEntry?: string;
    /**
     * The `id` of the empty container element in `index.html` the rendered
     * markup replaces. Defaults to `'root'`.
     */
    containerId?: string;
    /**
     * The origin the entry sees as `Request.url`, such as
     * `'https://app.example'`. Defaults to the origin the dev server itself
     * resolved from its own configuration.
     *
     * The origin is deployment configuration rather than something a request
     * carries. A client chooses its own `Host` header, and Vite accepts IP
     * literals and (with `allowedHosts`) arbitrary names, so deriving the origin
     * from the request would let the client pick the redirects, canonical URLs,
     * and cookie domains an entry builds from `Request.url`. Set this when the
     * dev server sits behind a proxy or TLS terminator that serves a different
     * public origin.
     */
    origin?: string;
    /**
     * The deployment id compiled into a server entry when `foldkitSsr` is used
     * as a standalone plugin. It defaults to `FOLDKIT_BUILD_ID`, or to the fixed
     * development id in serve mode. The aggregate `foldkit` plugin supplies its
     * top-level `buildId` here automatically.
     *
     * The value is public in rendered HTML, so it must not be a secret.
     */
    buildId?: string;
    /**
     * Skip the stand-down warning when the `ssr` environment is not runnable.
     * The aggregate plugin sets this when `ssr.build` is on, because production
     * still needs `serverEntry` and the host is supposed to serve.
     */
    quietStandDown?: boolean;
}>;

foldkitViewIdentity

foldkitViewIdentity: () => Plugin

transformViewIdentity

Brands the return value of every function in a module with that function's identity via `brandViewResult` from `@wsagency/wseffect-foldkit/brand`. Identities are `${posixRelativePathFromRoot}#${functionName}`, with the function name taken from, in order: the function's own id (declarations and named function expressions), the variable a function expression is bound to, the non-computed key of an object property, class method, or class field, `default` for an export-default function, the member name of an `x.y = fn` assignment, and `anonymous` otherwise. Duplicate names within a module are disambiguated in source order with `~2`, `~3`, and so on, so ids are fully deterministic. Expression-body arrows have their body wrapped in the branding call; block bodies have every `return` argument belonging directly to the function wrapped (nested functions instrument their own returns, and bare `return` is untouched). Branding is set-if-absent on vnodes at runtime, so wrapping every function, including async and generator functions and functions that never produce a vnode, is inert outside view results. Skips foldkit core modules: if the element factory's own returns were branded, every vnode would carry an identity at construction and set-if-absent would neutralize the feature. Core under `node_modules` is always skipped. The plugin resolves the installed foldkit package and passes `isFoldkitCoreResolved`; when it resolved, the plugin's precise package-root gate is authoritative and the coarse `packages/foldkit/` path fragment is left to the resolution-failed fallback, so a consumer whose own path merely contains that segment is still branded. Skips modules whose parsed program imports or re-exports the `@wsagency/wseffect-foldkit/brand` specifier: packages such as `@wsagency/wseffect-foldkit-ui` and `@foldkit/devtools` brand their dist at package build time, and pnpm symlink realpaths can surface that dist outside `node_modules`, where the module-id checks alone would let a build wrap the same returns twice. A module that merely mentions the specifier in a comment or string is still branded; the raw-text check is only a fast negative prefilter. Returns `null` when the module needs no changes.

transformViewIdentity: (code: string, id: string, root: string, options?: Readonly<{
    isFoldkitCoreResolved?: boolean;
}>) => ViewIdentityTransformResult | null

ViewIdentityTransformResult

export type ViewIdentityTransformResult = Readonly<{
    code: string;
    map: SourceMap;
}>;