Widget Pre-rendering

Widget pre-rendering allows you to provide meaningful initial state for widgets before they are synced when the app runs for the first time.

Configuration

Add initialStatePath to your widget configuration in app.json:

{
  "expo": {
    "plugins": [
      [
        "@use-voltra/ios-client",
        {
          "widgets": [
            {
              "id": "weather",
              "displayName": "Weather Widget",
              "description": "Shows current weather conditions",
              "supportedFamilies": ["systemSmall", "systemMedium", "systemLarge"],
              "initialStatePath": "./widgets/weather-initial.tsx"
            }
          ]
        }
      ]
    ]
  }
}

Localized initial states

Use a locale map so the config plugin pre-renders one bundle per language; iOS and Android pick the best match at runtime from the device locale (fallback order: preferred languages → language-only → en → first locale):

"initialStatePath": {
  "en": "./widgets/weather-initial.tsx",
  "pl": "./widgets/weather-initial-pl.tsx"
}

Implementation

Create a file at each configured path that exports a WidgetVariants object (or use the same file path for multiple locales if copy is identical):

import { Voltra, type WidgetVariants } from '@use-voltra/ios'

const initialState: WidgetVariants = {
  systemSmall: <Voltra.Text>Content</Voltra.Text>,
  systemMedium: <Voltra.Text>Content</Voltra.Text>,
  systemLarge: <Voltra.Text>Content</Voltra.Text>,
}

export default initialState

Note

initialStatePath files are not part of your React Native app bundle. Voltra transpiles them with Babel and runs them in Node.js during prebuild to generate the initial states bundled into the iOS app. Import Voltra and types from @use-voltra/ios, not @use-voltra/ios-client — the client package pulls in native modules that are unavailable in the prebuild sandbox.

Limitations

• Node.js Environment: Code runs in Node.js, not in React Native or iOS
• Babel Support: TypeScript is supported via Babel transpilation
• No Bundling: Import resolution works for local files but there is no bundler involved
• Voltra Imports: Use @use-voltra/ios for JSX and types in initialStatePath files. Do not import from @use-voltra/ios-client or other React Native client APIs.