Development and testing API
Experimental testing, validation, diagnostics, instrumentation, scheduling, inspection, overlays, configuration loading, and development servers.
Development and testing exports
55 public exports, grouped under their canonical import boundary.
@tavojs/core/dev
Canonical import boundary for every symbol in this section.
captureDiagnostics#
captureDiagnostics(): { traces: DevTraceEvent[]; mismatches: HydrationMismatchEvent[]; restore(): void; }Captures diagnostics for the experimental development tooling.
Related guideclearServices#
clearServices(): voidClears the shared service registry. Intended primarily for tests.
Related guideconfigureDevDiagnostics#
configureDevDiagnostics(options: DevDiagnosticsOptions): voidUpdates runtime diagnostics callbacks used by the DOM renderer.
Related guidecreateInstrumentation#
createInstrumentation(listener: TavoInstrumentationListener): TavoInstrumentationCreates an isolated observer. Listener failures never interrupt framework work.
Related guidecreateOpenTelemetryInstrumentation#
createOpenTelemetryInstrumentation(tracer: OpenTelemetryTracerLike, options?: { recordErrors?: boolean | undefined; } | undefined): TavoInstrumentationAdapts Tavo.js events to the stable tracing subset shared by OpenTelemetry implementations.
Related guidecreatePagesManifest#
createPagesManifest(modules: PageModules): PageRouteDefinition[]Convenience helper returning only sorted route definitions.
Related guidecreatePagesManifestDetailed#
createPagesManifestDetailed(modules: PageModules): PagesManifestBuilds the full pages manifest with routes, layouts, and diagnostics.
Related guidecreatePagesTestHarness#
createPagesTestHarness(modules: PageModules, options?: PageRuntimeOptions | undefined): { runtime: PagesRuntime; renderPath(pathname: string): string; resolvePath(pathname: string): Promise<unknown>; }Creates pages test harness for the experimental development tooling.
Related guidecreateTestRoot#
createTestRoot(): TestRootCreates test root for the experimental development tooling.
Related guidedefineValidatedAction#
defineValidatedAction<TInput>(schema: TavoSchema<TInput>, handler: (context: ValidatedActionContext<TInput>) => void | Response | ActionResult | Promise<void | Response | ActionResult>, options?: PageActionOptions | undefined): PageActionDefines a route action with portable schema validation and structured 400 failures.
Related guideDevDiagnosticsOptions#
type DevDiagnosticsOptions = {
enabled?: boolean;
devMode?: boolean;
onTrace?: ((event: DevTraceEvent) => void) | null;
onHydrationMismatch?: ((event: HydrationMismatchEvent) => void) | null;
onError?: ((error: unknown) => void) | null;
strictHydration?: boolean;
};Configures dev diagnostics in the experimental development tooling.
Related guideDevTraceEvent#
type DevTraceEvent = {
phase: DevTracePhase;
kind: string;
key?: string | number | null;
detail?: string;
};Describes an event emitted by dev trace in the experimental development tooling.
Related guideDevTracePhase#
type DevTracePhase = "mount" | "patch" | "hydrate";Defines the dev trace phase contract used by the experimental development tooling.
Related guideexpectTextContent#
expectTextContent(root: TestRoot, expected: string): voidAsserts text content for the experimental development tooling.
Related guideflushMicrotasks#
flushMicrotasks(): Promise<void>Flushes microtasks for the experimental development tooling.
Related guideflushSync#
flushSync<T>(callback: () => T): TFlushes sync for the experimental development tooling.
Related guidegetAutoPagesInspection#
getAutoPagesInspection(): AutoPagesInspectionReturns a privacy-safe snapshot for first-party development tools.
Related guidegetCurrentUpdatePriority#
getCurrentUpdatePriority(): UpdatePriorityReads current update priority for the experimental development tooling.
Related guideHydrationMismatchEvent#
type HydrationMismatchEvent = {
message: string;
expected?: string;
found?: string;
path?: string;
pathSegments?: string[];
phase?: DevTracePhase;
kind?: string;
recovery?: "text" | "subtree" | "cleanup";
};Describes an event emitted by hydration mismatch in the experimental development tooling.
Related guideinspectPages#
inspectPages(modules: PageModules): { routes: PageRouteDefinition[]; diagnostics: string[]; }Returns route data and diagnostics without creating runtime objects.
Related guideinspectPluginGraph#
inspectPluginGraph(config?: TavoPluginInput | undefined, options?: PluginCompileOptions | undefined): PluginGraphInspectionReturns a serializable inspection without executing plugin code.
Related guideinspectTavoRuntime#
inspectTavoRuntime(): TavoDevtoolsSnapshotReturns an inspection of tavo runtime for the experimental development tooling.
Related guideinstallDevOverlay#
installDevOverlay(options?: { traces?: boolean | undefined; } | undefined): voidEnables a browser overlay for runtime errors and hydration mismatches during development.
Related guideinstallTavoDevtoolsPanel#
installTavoDevtoolsPanel(options?: { target?: HTMLElement | undefined; initiallyOpen?: boolean | undefined; } | undefined): TavoDevtoolsPanelInstalls an opt-in, dependency-free browser panel backed by privacy-safe snapshots.
Related guideloadTavoConfig#
loadTavoConfig(rootDir?: string | undefined, options?: LoadTavoConfigOptions | undefined): Promise<TavoConfig>Loads the root `tavo.config.ts` default export once for the current process.
Related guideLoadTavoConfigOptions#
type LoadTavoConfigOptions = {
mode?: string;
};Configures load tavo config in the experimental development tooling.
Related guideOpenTelemetrySpanLike#
type OpenTelemetrySpanLike = {
setAttribute?(name: string, value: string | number | boolean): unknown;
recordException?(error: unknown): unknown;
setStatus?(status: {
code: number;
message?: string;
}): unknown;
end?(endTime?: number): unknown;
};Defines the open telemetry span like contract used by the experimental development tooling.
Related guideOpenTelemetryTracerLike#
type OpenTelemetryTracerLike = {
startSpan(name: string, options?: {
attributes?: Record<string, string | number | boolean>;
startTime?: number;
}): OpenTelemetrySpanLike;
};Defines the open telemetry tracer like contract used by the experimental development tooling.
Related guideParseSchema#
type ParseSchema<T> = {
parse?(value: unknown): T;
parseAsync?(value: unknown): Promise<T>;
};Defines the parse schema contract used by the experimental development tooling.
Related guideRunningDevServer#
type RunningDevServer = {
close(): Promise<void>;
url: string;
};Defines the running dev server contract used by the experimental development tooling.
Related guiderunWithUpdatePriority#
runWithUpdatePriority<T>(priority: UpdatePriority, callback: () => T): TRuns with update priority for the experimental development tooling.
Related guideSafeParseSchema#
type SafeParseSchema<T> = {
safeParse?(value: unknown): unknown;
safeParseAsync?(value: unknown): Promise<unknown>;
};Defines the safe parse schema contract used by the experimental development tooling.
Related guideStandardSchema#
type StandardSchema<T> = {
"~standard": {
validate(value: unknown): {
value: T;
issues?: undefined;
} | {
value?: undefined;
issues: ReadonlyArray<{
message: string;
path?: ReadonlyArray<PropertyKey | {
key: PropertyKey;
}>;
}>;
} | Promise<{
value: T;
issues?: undefined;
} | {
value?: undefined;
issues: ReadonlyArray<{
message: string;
path?: ReadonlyArray<PropertyKey | {
key: PropertyKey;
}>;
}>;
}>;
};
};Defines the standard schema contract used by the experimental development tooling.
Related guidestartTransition#
startTransition(callback: () => void): voidStarts transition for the experimental development tooling.
Related guidestartViteAutoPagesDevServer#
startViteAutoPagesDevServer(options?: ViteAutoPagesDevServerOptions | undefined): Promise<RunningDevServer>Starts a Vite middleware-mode server that SSR-renders file-based pages.
Related guidesubscribeTavoRuntime#
subscribeTavoRuntime(listener: (snapshot: TavoDevtoolsSnapshot) => void, options?: { immediate?: boolean | undefined; } | undefined): () => voidSubscribes to navigation and route lifecycle changes with privacy-safe snapshots.
Related guideTavoDevtoolsPanel#
type TavoDevtoolsPanel = {
element: HTMLElement;
refresh(): void;
dispose(): void;
};Defines the tavo devtools panel contract used by the experimental development tooling.
Related guideTavoDevtoolsSnapshot#
type TavoDevtoolsSnapshot = AutoPagesInspection & {
dom: {
mountedComponents: number;
pendingPassiveEffects: number;
pendingUpdates: number;
};
};Defines the tavo devtools snapshot contract used by the experimental development tooling.
Related guideTavoInstrumentation#
type TavoInstrumentation = {
emit(event: TavoInstrumentationEvent): void;
};Defines the tavo instrumentation contract used by the experimental development tooling.
Related guideTavoInstrumentationEvent#
type TavoInstrumentationEvent = {
name: TavoInstrumentationEventName;
phase: TavoInstrumentationPhase;
timestamp: number;
requestId?: string;
route?: string;
layer?: string;
durationMs?: number;
status?: number;
count?: number;
cacheTags?: string[];
error?: unknown;
};Describes an event emitted by tavo instrumentation in the experimental development tooling.
Related guideTavoInstrumentationEventName#
type TavoInstrumentationEventName = "route.resolve" | "route.middleware" | "route.loader" | "route.action" | "route.cache";Defines the tavo instrumentation event name contract used by the experimental development tooling.
Related guideTavoInstrumentationListener#
type TavoInstrumentationListener = (event: TavoInstrumentationEvent) => void;Defines a callback notified by tavo instrumentation in the experimental development tooling.
Related guideTavoInstrumentationPhase#
type TavoInstrumentationPhase = "start" | "end" | "error" | "abort" | "hit" | "miss" | "invalidate";Defines the tavo instrumentation phase contract used by the experimental development tooling.
Related guideTavoSchema#
type TavoSchema<T> = StandardSchema<T> | SafeParseSchema<T> | ParseSchema<T>;Defines the tavo schema contract used by the experimental development tooling.
Related guideTestRoot#
type TestRoot = {
container: HTMLElement;
render(node: Child): void;
hydrate(node: Child): void;
unmount(): void;
text(): string;
html(): string;
};Defines the test root contract used by the experimental development tooling.
Related guideunregisterService#
unregisterService(identifier: ServiceIdentifier<unknown>): booleanRemoves a service registration. Intended primarily for tests.
Related guideUpdatePriority#
type UpdatePriority = "immediate" | "user-blocking" | "normal" | "background" | "idle";Defines the update priority contract used by the experimental development tooling.
Related guideValidatedActionContext#
type ValidatedActionContext<TInput> = PageActionContext & {
input: TInput;
};Provides the context passed to validated action in the experimental development tooling.
Related guidevalidateInput#
validateInput<T>(schema: TavoSchema<T>, input: unknown): Promise<ValidationResult<T>>Validates through Standard Schema or common safeParse/parse-compatible validators.
Related guideValidationFailure#
type ValidationFailure = {
ok: false;
issues: ValidationIssue[];
};Defines the validation failure contract used by the experimental development tooling.
Related guideValidationIssue#
type ValidationIssue = {
message: string;
path?: ReadonlyArray<PropertyKey>;
};Defines the validation issue contract used by the experimental development tooling.
Related guideValidationResult#
type ValidationResult<T> = ValidationSuccess<T> | ValidationFailure;Describes the result returned by validation in the experimental development tooling.
Related guideValidationSuccess#
type ValidationSuccess<T> = {
ok: true;
value: T;
};Defines the validation success contract used by the experimental development tooling.
Related guideViteAutoPagesDevServerOptions#
type ViteAutoPagesDevServerOptions = {
root?: string;
pagesDir?: string;
cssEntries?: string[];
mode?: string;
images?: ImageOptimizerOptions;
port?: number;
host?: string;
};Configures vite auto pages dev server in the experimental development tooling.
Related guideViteDevServerLike#
type ViteDevServerLike = {
middlewares: (req: unknown, res: unknown, next: (error?: unknown) => void) => void;
transformRequest(url: string, options?: {
ssr?: boolean;
}): Promise<null | {
code: string;
}>;
pluginContainer?: {
resolveId(id: string, importer?: string, options?: {
ssr?: boolean;
}): Promise<string | null | {
id: string;
}>;
};
ssrLoadModule(id: string): Promise<unknown>;
ssrFixStacktrace(error: unknown): void;
close(): Promise<void>;
};Defines the vite dev server like contract used by the experimental development tooling.
Related guide