Skip to main content

Documentation Index

Fetch the complete documentation index at: https://setup.despia.com/llms.txt

Use this file to discover all available pages before exploring further.

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'
    })
  ]
});

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.

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

Resources

@despia/local on npm

Full package documentation, version history, and changelog.

despia-native SDK

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