Vite plugin and TanStack Start adapter
Build-time plugins, virtual modules, and framework integration.
@akshatowo/radical/vite
radical(config, adapterLayer?) returns the core Vite plugin named radical:config. Config validation occurs before dev or build. The optional layer supplies RadicalAdapter for framework operations.
The plugin resolves enabled manifests, validates options, generates typed plugin declarations, and maintains native metadata. Its dev-server integration records the actual protocol and port with the selected devHost.
| CORS configuration | Behavior |
|---|---|
Bundled, server.cors undefined | Returns false for the two exact bundled origins so the API handler owns preflights and credentials |
| Other origins | Vite defaultAllowedOrigins |
| Remote mode | Vite defaults |
Explicit server.cors or preview.cors | Preserved, including booleans and objects |
| Preview precedence | preview.cors, then inherited server.cors |
| Custom policy for bundled requests | cors: false or an origin callback returning false for bundled origins; API handler owns CORS |
Exports include RadicalConfig, RadicalConfigSchema, validateConfig, InvalidConfig, InvalidPlugin, PluginDependencyConflict, AdapterUnavailable, and RadicalAdapter. Adapter types are RadicalCore, RadicalRoute, RadicalNavigation, and AdapterOutputs.
RadicalAdapter is an Effect service with name, optional vite(core), routes, provideRequestContext(get), navigation, and outputs. RadicalNavigation contains navigate(to, options?), onBeforeNavigate(callback), and onAfterNavigate(callback). outputs returns Effect<AdapterOutputs> with these fields:
| Field | Type | Contract |
|---|---|---|
clientDir | string | Client build output directory. |
spaShell | string, optional | SPA shell path relative to clientDir. |
exposedHeaders | readonly string[], optional | Response headers exposed to bundled clients through CORS when supplied to the core withBundledRequests(handler, outputs?). Omitted or empty arrays add no exposed headers. |
Virtual modules
| Module | Export | Contract |
|---|---|---|
virtual:radical/config | config | Browser-safe appId, mode, and optional origin. Omitted mode resolves to "remote". |
virtual:radical/plugins | plugins | Typed clients keyed by enabled manifest IDs and command names. Requires Bridge when commands run. |
.radical/plugins.d.ts declares both modules. Vite startup and radical typegen generate the declarations. Custom manifest commands and errors retain their schema-derived types.
@akshatowo/radical/tanstack-start
| Adapter export or behavior | Contract |
|---|---|
radical(config) | Core plugin with TanStackStartAdapter; remote offline build plugin omitted in bundled mode |
tanstackStartOptions(config) | { spa: { enabled: config.mode === "bundled" } } |
clientDir | "dist/client" |
spaShell | "_shell.html" |
exposedHeaders | ["x-tss-serialized", "x-tss-raw", "x-tss-error"] |
TanStackStartAdapter | Provides request context and outputs; navigation fails with AdapterUnavailable |
routes | Effect returns empty list; offline eligibility uses selected route at request time |
RadicalRouteOptions | staticData.radical with optional offline: boolean and transition: "slide" | "fade" |
@akshatowo/radical/tanstack-start-server
| Export | Contract |
|---|---|
createRadicalMiddleware(get?) | Start middleware adding nativeContext to request context. The optional reader returns Effect<NativeContext>. |
radicalMiddleware | Default instance using getNativeContext. |
radicalRequestMiddleware | Standard server-function CSRF middleware followed by Radical context middleware. |
createRadicalRequestMiddleware() | Explicit bundled-server opt-in. Allows the two exact bundled origins through the server-function CSRF origin checks. |
withBundledRequests(handler) | Wraps the core CORS helper with the TanStack Start adapter outputs. Exposes x-tss-serialized, x-tss-raw, and x-tss-error to the two exact bundled origins. |
offlineHandler(handler) | Sets x-radical-offline to 1 only when the deepest selected route has offline: true, otherwise 0, then delegates. |
Middleware exports also appear in @akshatowo/radical/tanstack-start for build-side integration. The server entry keeps server middleware out of browser imports.
@akshatowo/radical/tanstack-start-client
Exports browserTransitions, BrowserTransitionOptions, tanstackStartAdapterLayer(router), RadicalRouteOptions, and NavigationFailed.
tanstackStartAdapterLayer(router) supplies live navigation and fixed outputs. Its request-context operation fails with AdapterUnavailable. Its routes list is empty. browserTransitions is also re-exported from @akshatowo/radical/tanstack-start.
Generated offline output
| Remote output or export | Contract |
|---|---|
radical-sw.js | Worker in client output |
radical-manifest.json | buildId, cachePrefix, assets, fallback |
| Fallback | ${base}offline.html |
cachePattern | No public config field |
@akshatowo/radical/offline-entry | Build-side worker installation entry; no React lifecycle API |
Source: Vite implementation, TanStack adapter.