Navigate

API reference

@pyric/cli/vite

11 published symbols from @pyric/cli

Generated from the TypeScript declarations shipped at this import path.

Interfaces

AssetRequest

Properties

PropertyTypeDescription
contextRecord<string, unknown>-
keystring-
seedstring-
sourceAllowed?booleanfalse answers from the cache, the pool, or the fallback and never starts the source. Absent means the source may run.

FlowConfig

JSON project configuration; module paths resolve from the project root.

Properties

PropertyType
treatment?string
treatments?{ description?: string; id: string; label: string; module: string; }[]

OwnersConfig

JSON project configuration for listener and operation owners.

Properties

PropertyTypeDescription
frames?numberApplication frames each owner keeps, counted from the shown frame. Default 3.
skip?string[]Globs for modules whose frames an owner never shows first, e.g. src/db/**.

PyricOptions

Properties

PropertyTypeDescription
ai?PyricAiOptionsDev-server-level AI configuration for pyric/ai (the sanctioned replacement for threading engine through every app getAI(...) call, which is first-call-wins and easy to get wrong). pyric({ ai: { model: ‘llama3.2’, proxyUpstream: ‘http://localhost:11434/v1’, // your Ollama }, }) - model is the simple OpenAI-compatible path. It becomes the catch-all upstream model. PYRIC_AI_MODEL selects the same path when neither model nor engine is explicit. - engine is pyric/ai’s EngineConfig (scripted
avatars?PyricAvatarsOptionsProfile photos for sandbox provider users. Default: deterministic generated avatars. A string selects a pre-created avatar set (directory path, resolved from the project root). false disables the avatar route entirely. An object supplies a custom source that runs in the dev server, never the browser.
bridge?| boolean | { disableAuditLog?: boolean; project?: string; }Mount the MCP bridge on Vite’s dev origin so an external agent (Claude Code, Cursor) can drive this sandbox over MCP — POST /__pyric/mcp + GET /__pyric/health + WS /__pyric/sandbox, all on Vite’s port. true is shorthand for {}. The agent and the page share ONE sandbox. Does NOT change the sandbox topology: on the default SharedWorker path the page dials the bridge WS and relays agent tool-calls THROUGH the worker (connectBridgePeer), so multi-tab stays on. The in-page fallback engages only when the worker bundle itself fails, bridge or not.
capture?booleanWrite the live session fixture to .pyric/last-session.json (for pyric verify). Default true; pass false to suppress.
flow?FlowConfigOverrides the shared pyric.json Flow configuration.
fresh?booleanWith persist or hosted: discard existing state and re-seed on startup.
functions?| false | { instance?: string; region?: string; watch?: boolean; }RTDB-triggered Cloud Functions under this dev server (the pyric sandbox parity fold). By default a functions block in firebase.json is discovered automatically: its onValueCreated triggers run in an isolated node child against the shared sandbox (other trigger kinds warn and are skipped), and the discovered codebase turns the MCP bridge mount on (the child dials the sandbox over the bridge WS — the page’s sandbox topology is unchanged, see bridge). functions: false is the off switch: no discovery, no child, no functions-forced bridge mount. Field precedence: explicit option > env var > firebase files > default. - region: the trigger location. Beats PYRIC_FUNCTIONS_RTDB_REGION; default us-central1. - instance: the RTDB instance name. Default <projectId>-default-rtdb, where projectId is the resolved project (see that option), else demo-project. - watch: hot-reload the functions source (default true, matching rules). A save under the functions source dir stops the child and respawns it — redeploy semantics: in-flight executions in the old child may drop, and writes landing during the swap gap are consumed as the new child’s baseline (they do not fire). Unlike rules, a broken save cannot keep last-good live — the old child is already gone — so functions stay down until the next good save.
hosted?booleanRun the dev sandbox in the Vite server process, shared across browsers and Studio, with durable project state. Automatically mounts the bridge. Default: false (SharedWorker). Requires Vite’s own HTTP server; middleware mode is unsupported. Does not affect production builds.
owners?OwnersConfigOverrides the shared pyric.json owners configuration, field by field. skip lists globs for the app’s data-layer wrapper modules, so a listener’s owner shows the code that called the wrapper; the wrapper’s frame stays on the owner’s stack. frames is how many application frames each owner keeps, counted from the frame it shows (default 3).
persist?booleanPersist sandbox state to .pyric/state/state.json so data + test users survive reloads/restarts. Off by default for SharedWorker; hosted mode always persists state.
project?stringThe Firebase project the sandbox runs as: a project id or a .firebaserc alias. It names the default Realtime Database instance, selects the .firebaserc deploy targets a firebase.json database array names, and is the functions child’s project. Without it, the project resolves as the Firebase CLI resolves it: PYRIC_PROJECT, then the firebase use active project for this directory, then .firebaserc projects.default.
root?stringProject dir for firebase.json / rules discovery. Default: Vite’s root.
rules?stringFirestore rules path (relative to root). Default discovery prefers an authored firestore.modules.rules, then firebase.json, then firestore.rules in the project root.
runtimeChip?PyricRuntimeChipOptionInject the collapsed Pyric runtime chip into the app during sandbox Vite dev/builds. On by default. Pass false to hide it, or { initiallyOpen: true } when actively debugging runtime errors.
seed?stringSeed file: a "collection/doc" → fields JSON map, or a pyric snapshot state-file envelope. Applied at page init (state wins once it exists).
serviceWorker?stringThe app’s own service worker module (path from the Vite root), such as a vite-plugin-pwa injectManifest source. In dev, the plugin adds a fetch listener to it that answers production Storage download URLs from the sandbox (sandboxStorageFetch from pyric/storage/sw), so the file needs no Pyric import. Builds are untouched.
sessionToken?booleanRequire a per-boot session capability token on every local /__pyric/* route, MCP, and WS /__pyric/sandbox (workspace, project, and AI proxy routes always require one). Default: false (or pyric.json#sessionToken).
swapInBuild?booleanForce whether vite build runs the firebase→pyric swap, overriding the mode default. Unset (default): swap for any NON-production mode, keep real firebase for mode production. true = always produce a sandbox build; false = never swap in build (real firebase regardless of mode). vite dev is unaffected — the swap is always on there.
ui?booleanServe the Pyric Studio app at /__pyric/ui/ on Vite’s dev origin (the pyric sandbox --ui equivalent). Mounts the disk-backed workspace/project routes Studio’s local mode talks to AND serves the unified Astro site (vendored in this package at dist/serve/site-ui). On by default, including under bridge (the bridge peer routes through the SharedWorker, so app, Studio, and agent all observe the one sandbox); pass ui: false to disable.

Type Aliases

AssetResult

type AssetResult =
  | {
  url: string;
}
  | {
  contentType: string;
  data: Uint8Array;
};

AssetSource()

type AssetSource = (req: AssetRequest) =>
  | AssetResult
| Promise<AssetResult>;

Parameters

ParameterType
reqAssetRequest

Returns

| AssetResult | Promise<AssetResult>


PyricAvatarsOptions

type PyricAvatarsOptions =
  | false
  | string
  | {
  source: AssetSource;
};

Profile photos for sandbox provider users. Default: deterministic generated avatars. A string selects a pre-created avatar set (directory path, resolved from the project root). false disables the avatar route entirely. An object supplies a custom source that runs in the dev server, never the browser.


PyricRuntimeChipOption

type PyricRuntimeChipOption =
  | boolean
  | {
  initiallyOpen?: boolean;
};

Variables

NODE_BUILTIN_RE

const NODE_BUILTIN_RE: RegExp;

The node builtins pyric’s browser graph reaches for (via the rules module resolver). Bare and node:-prefixed both match.


NODE_BUILTIN_SHIMS

const NODE_BUILTIN_SHIMS: Record<string, string>;

Benign browser shim SOURCE per builtin (see header — droppable only when pyric breaks the firestore/index → rules/tools → modules/resolver static chain, #553). Exported so the Vite plugin (./vite) reuses the SAME shims through its own resolveId/load + optimizeDeps esbuild pass, instead of re-deriving them.

Functions

pyric()

function pyric(options?: PyricOptions): Plugin<any> & EnvironmentHooks;

The dev-only Vite plugin. Add to vite.config:

import { pyric } from ‘@pyric/cli/vite’; export default defineConfig({ plugins: [pyric()] });

Parameters

ParameterType
options?PyricOptions

Returns

Plugin<any> & EnvironmentHooks