{"id":14251,"library":"voltra","title":"Voltra","description":"Voltra is a React Native library that enables developers to build iOS Live Activities, Dynamic Island layouts, and Android Home Screen Widgets using JSX, eliminating the need to write native Swift, Kotlin, or SwiftUI/Jetpack Compose Glance code directly. It leverages React Native's familiar development workflow, including Fast Refresh, and provides a unified approach for styling with React Native style props and platform-native modifiers. Key features include support for ActivityKit push tokens and FCM for server-driven updates, a new Flexbox layout engine for iOS (introduced in v1.2.0 via `Voltra.View`), and capabilities for server-driven widgets and charts (introduced in v1.3.0). The current stable package version is 1.4.0, with a release cadence that has included significant feature additions in recent minor versions. It is compatible with Expo Dev Client and bare React Native projects, using an Expo config plugin to automatically wire native extension targets. This library aims to streamline cross-platform native surface development for React Native engineers.","status":"active","version":"1.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/callstackincubator/voltra","tags":["javascript","react-native","expo","live-activity","ios","apple","typescript"],"install":[{"cmd":"npm install voltra","lang":"bash","label":"npm"},{"cmd":"yarn add voltra","lang":"bash","label":"yarn"},{"cmd":"pnpm add voltra","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for the config plugin and integration within the Expo ecosystem, specifically needing Expo Dev Client and not Expo Go.","package":"expo","optional":false},{"reason":"Core dependency for JSX syntax, component definition, and React hooks, fundamental for Voltra's component model.","package":"react","optional":false},{"reason":"Provides the foundational components, styling system, and runtime environment that Voltra extends and integrates with.","package":"react-native","optional":false}],"imports":[{"note":"This hook, central to managing Live Activity lifecycles, must be imported from the 'voltra/client' subpath. It is a named export, not a default export, and assumes an ESM environment typically used with modern React Native projects.","wrong":"import useLiveActivity from 'voltra/client'; // Incorrect default import\nconst { useLiveActivity } = require('voltra/client'); // CommonJS import","symbol":"useLiveActivity","correct":"import { useLiveActivity } from 'voltra/client'"},{"note":"The 'Voltra' object, which encapsulates all JSX components like `VStack`, `Text`, and `View`, is a named export from the root 'voltra' package. Always use named import syntax for these components.","wrong":"import Voltra from 'voltra'; // Voltra is not a default export\nconst Voltra = require('voltra'); // CommonJS require might not correctly resolve named exports or ESM modules","symbol":"Voltra","correct":"import { Voltra } from 'voltra'"},{"note":"This is a TypeScript type definition used for configuring the behavior of a Live Activity, typically the second argument to `useLiveActivity`. Always use `import type` for type-only imports to ensure they are stripped from the JavaScript bundle.","symbol":"LiveActivityOptions","correct":"import type { LiveActivityOptions } from 'voltra/client'"}],"quickstart":{"code":"import { useLiveActivity } from 'voltra/client';\nimport { Voltra } from 'voltra';\nimport React from 'react'; // React is a peer dependency and needed for JSX\n\ninterface OrderTrackerProps {\n  orderId: string;\n}\n\nexport function OrderTracker({ orderId }: OrderTrackerProps) {\n  // Define the UI for the Live Activity/Widget using Voltra components\n  const ui = (\n    <Voltra.VStack style={{ padding: 16, borderRadius: 14, backgroundColor: '#111827' }}>\n      <Voltra.Text style={{ color: 'white', fontSize: 18, fontWeight: '700' }}>Order #{orderId}</Voltra.Text>\n      <Voltra.Text style={{ color: '#9CA3AF', marginTop: 6 }}>Driver en route · ETA 12 min</Voltra.Text>\n    </Voltra.VStack>\n  );\n\n  // Use the useLiveActivity hook to manage the Live Activity lifecycle\n  const { start, update, end } = useLiveActivity(\n    { lockScreen: ui }, // Define the UI for different states (here, just lockScreen)\n    {\n      activityName: `order-${orderId}`, // Unique name for the activity\n      autoStart: true, // Automatically start the activity when the component mounts\n      deepLinkUrl: `/orders/${orderId}` // URL to open when the activity is tapped\n    }\n  );\n\n  // In a real application, you might have buttons or logic to call update() or end()\n  // For demonstration, we just return null as the UI is rendered natively.\n  return null;\n}","lang":"typescript","description":"This example demonstrates how to create a basic iOS Live Activity or Android Widget using Voltra's JSX components and manage its lifecycle with the `useLiveActivity` hook. It showcases defining a native UI directly within React Native and configuring its behavior."},"warnings":[{"fix":"Ensure your project is configured to use Expo Dev Client. Add `\"plugins\": [\"voltra\"]` to your `app.json` and run `npx expo prebuild --clean` to generate the native extension targets, then rebuild your native app.","message":"Voltra is not supported in Expo Go. It explicitly requires an Expo Dev Client or a bare React Native project. Attempting to run Voltra components or hooks in Expo Go will result in runtime errors related to missing native module linking.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update Voltra to version 1.1.2 or higher to ensure proper ESM compatibility. This release specifically addresses and restores the necessary patch.","message":"In versions prior to 1.1.2, users might encounter issues with ESM compatibility. An accidental overwrite during the Android rewrite in v1.1.0 removed a crucial ESM patch, potentially leading to module resolution errors in some environments.","severity":"breaking","affected_versions":">=1.1.0 <1.1.2"},{"fix":"To utilize Flexbox for layout on iOS, ensure you replace `VStack` or `HStack` with `Voltra.View` and apply standard React Native style props for layout.","message":"The new Flexbox layout system for iOS, introduced in Voltra 1.2.0 via `Voltra.View`, is opt-in. Components like `Voltra.VStack` and `Voltra.HStack` continue to use standard SwiftUI layout semantics. Developers must explicitly choose `Voltra.View` for React Native-style Flexbox behavior.","severity":"gotcha","affected_versions":">=1.2.0"}],"env_vars":null,"search_vec":"'1.4.0':113 'activ':15,173 'activitykit':73 'addit':123 'aim':153 'android':20 'appl':175 'approach':55 'automat':146 'bare':136 'build':12 'cadenc':117 'capabl':96 'chart':103 'client':134 'code':38 'compat':130 'compos':36 'config':143 'cross':157 'cross-platform':156 'current':108 'dev':133 'develop':10,46,161 'direct':39 'driven':81,100 'dynam':16 'elimin':26 'enabl':9 'engin':87,165 'expo':132,142,170 'extens':149 'familiar':45 'fast':49 'fcm':77 'featur':69,122 'flexbox':85 'glanc':37 'home':21 'includ':48,70,120 'introduc':90,104 'io':13,89,174 'island':17 'javascript':166 'jsx':25 'key':68 'kotlin':33 'layout':18,86 'leverag':41 'librari':7,152 'live':14,172 'live-act':171 'minor':126 'modifi':67 'nativ':6,31,43,60,66,138,148,159,164,169 'need':28 'new':84 'packag':110 'platform':65,158 'platform-n':64 'plugin':144 'project':139 'prop':62 'provid':52 'push':74 'react':5,42,59,137,163,168 'react-nat':167 'recent':125 'refresh':50 'releas':116 'screen':22 'server':80,99 'server-driven':79,98 'signific':121 'stabl':109 'streamlin':155 'style':57,61 'support':71 'surfac':160 'swift':32 'swiftui/jetpack':35 'target':150 'token':75 'typescript':176 'unifi':54 'updat':82 'use':24,140 'v1.2.0':92 'v1.3.0':106 'version':111,127 'via':93 'voltra':1,2 'voltra.view':94 'widget':23,101 'wire':147 'workflow':47 'write':30","created_at":"2026-04-20T01:58:43.841581+00:00","updated_at":"2026-04-20T01:58:43.841581+00:00","problems":[{"fix":"Verify that `[\"voltra\"]` is included in the `plugins` array within your `app.json`. Then, run `npx expo prebuild --clean` and rebuild your native application (`npx expo run:ios` or `npx expo run:android`) to ensure native modules are correctly compiled and linked.","cause":"Voltra's native modules (for Live Activities or Widgets) are not correctly linked or registered within the native app bundle, often due to an incomplete `npx expo prebuild` step or incorrect plugin configuration.","error":"Invariant Violation: `new NativeEventEmitter()` was called with a non-null argument without the native module `Voltra` being a subclass of `NativeEventEmitter`. Did you forget to register the native module?"},{"fix":"Ensure you are using `import { Voltra } from 'voltra';` to correctly import the `Voltra` object. This provides access to its components like `VStack`, `Text`, and `View`.","cause":"The `Voltra` named export, which contains all UI components, was not correctly imported or its path was wrong. This often occurs if attempting to use a default import or a CommonJS `require()` statement instead of a named ESM import.","error":"TypeError: Cannot read properties of undefined (reading 'VStack')"},{"fix":"First, ensure `voltra` is installed correctly. Verify your bundler configuration supports package exports. If using an older React Native version, consider upgrading your development environment or checking for specific module resolution settings that might be required.","cause":"The subpath import `voltra/client` is not being correctly resolved by the module bundler (e.g., Metro, Webpack). This could be due to a misconfigured bundler, an older environment not fully supporting package exports, or an incorrect package installation.","error":"Module not found: Error: Can't resolve 'voltra/client' in '...'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":"https://voltra.dev","github":"https://github.com/callstackincubator/voltra","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/voltra","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops","web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}