Skip to main content

Installation

Add the @despia/local plugin to your build:
npm install --save-dev @despia/local

Framework integration

Covers React, Vue, Svelte, Preact, and Lit projects using Vite.
vite.config.js
import { defineConfig } from 'vite';
import { despiaLocalPlugin } from '@despia/local/vite';

export default defineConfig({
  plugins: [
    despiaLocalPlugin({
      outDir: 'dist',         // optional, default: 'dist'
      entryHtml: 'index.html' // optional, default: 'index.html'
    })
  ]
});

Configure @despia/local for a specific framework and verify the manifest output. The agent will wire up the plugin, run the build, and confirm despia/local.json is generated correctly. Provide your framework, output directory, and entry HTML filename.

CursorOpen in Cursor

Configuration options

All plugins accept the same options:
OptionTypeDefaultDescription
outDirstring'dist'Output directory to scan for assets
entryHtmlstring'index.html'Entry HTML filename to include in manifest

Manifest schema

The plugin hooks into your build tool’s completion event, scans the output directory, and generates the manifest at despia/local.json.
The manifest must always be served at despia/local.json relative to your web app’s root. Do not change this path. Despia expects it at this exact location to detect and apply updates.
despia/local.json
{
  "entry": "/index.html",
  "deployed_at": "1737225600000",
  "assets": [
    "/index.html",
    "/assets/app.abc123.css",
    "/assets/app.def456.js",
    "/assets/logo.xyz789.png"
  ]
}
FieldDescription
entryThe entry HTML file path. Always required for client-side rendering.
deployed_atTimestamp in milliseconds (as string) when the manifest was generated. Updated on every deployment and used by the OTA cache system to detect new builds.
assetsAlphabetically sorted array of all asset paths, including the entry file.
This manifest enables Despia to discover all assets for complete caching, determine changes via deployed_at, guarantee offline operation, and perform atomic updates safely.

Version guards

For apps that need to maintain compatibility across different runtime versions, use despia-version-guard to conditionally render features based on the installed native runtime version.
import { VersionGuard } from 'despia-version-guard';

// Only renders this feature if the runtime version is 21.0.3 or higher
<VersionGuard min_version="21.0.3">
  <NewFeatureComponent />
</VersionGuard>
Use caseWhy it helps
Store complianceVersion-gate major UI changes to satisfy review requirements
Prevent broken UIEnsure features only render when the required runtime capability is available
Smooth rolloutsGradually introduce new capabilities without forcing immediate updates
Enterprise stabilityMaintain consistent behavior across deployments with mixed runtime versions
despia-version-guard supports React, Vue, Angular, Svelte, and Vanilla JS / Web Components.

Add version guards to an existing Despia web app. The agent will wrap the correct components in VersionGuard, identify the minimum version needed for each feature, and ensure fallback UI is in place for older runtimes. Provide your framework and the features you want to version-gate.

CursorOpen in Cursor

Troubleshooting

Manifest not generated
  • Ensure the build completes without errors before checking for the manifest
  • Confirm the output directory exists at the path specified in outDir
  • Verify the outDir option matches your build tool’s configured output directory
  • Check the console for error messages from the plugin
Missing assets in manifest
  • The plugin scans the entire output directory — confirm assets are copied there during the build step
  • Check that file paths resolve correctly relative to the output root
Path format issues
  • All paths are automatically normalised to root-relative format
  • Paths starting with / are preserved as-is
  • Windows backslashes are converted to forward slashes automatically

External resources

@despia/local on npm

Full package documentation, version history, and changelog.

despia-native SDK

Reference for the JavaScript bridge and all 30+ native API bindings.