Registry / devops / voltra

voltra

JSON →
library1.4.0jsnpmunverified

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.

npm install voltra
INSTALL
IMPORT
SIG · VOLTRA
V
voltra
devopsjavascriptv1.4.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

useLiveActivity
import { useLiveActivity } from 'voltra/client'
import useLiveActivity from 'voltra/client'; // Incorrect default import const { useLiveActivity } = require('voltra/client'); // CommonJS import
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.
Voltra
import { Voltra } from 'voltra'
import Voltra from 'voltra'; // Voltra is not a default export const Voltra = require('voltra'); // CommonJS require might not correctly resolve named exports or ESM modules
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.
LiveActivityOptions
import type { LiveActivityOptions } from 'voltra/client'
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.

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.

import { useLiveActivity } from 'voltra/client'; import { Voltra } from 'voltra'; import React from 'react'; // React is a peer dependency and needed for JSX interface OrderTrackerProps { orderId: string; } export function OrderTracker({ orderId }: OrderTrackerProps) { // Define the UI for the Live Activity/Widget using Voltra components const ui = ( <Voltra.VStack style={{ padding: 16, borderRadius: 14, backgroundColor: '#111827' }}> <Voltra.Text style={{ color: 'white', fontSize: 18, fontWeight: '700' }}>Order #{orderId}</Voltra.Text> <Voltra.Text style={{ color: '#9CA3AF', marginTop: 6 }}>Driver en route · ETA 12 min</Voltra.Text> </Voltra.VStack> ); // Use the useLiveActivity hook to manage the Live Activity lifecycle const { start, update, end } = useLiveActivity( { lockScreen: ui }, // Define the UI for different states (here, just lockScreen) { activityName: `order-${orderId}`, // Unique name for the activity autoStart: true, // Automatically start the activity when the component mounts deepLinkUrl: `/orders/${orderId}` // URL to open when the activity is tapped } ); // In a real application, you might have buttons or logic to call update() or end() // For demonstration, we just return null as the UI is rendered natively. return null; }
Debug
Known issues
gotchaVoltra 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.
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.
affects: >=1.0.0
breakingIn 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.
fix
Update Voltra to version 1.1.2 or higher to ensure proper ESM compatibility. This release specifically addresses and restores the necessary patch.
affects: >=1.1.0 <1.1.2
gotchaThe 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.
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.
affects: >=1.2.0
Errors
Common errors & fixes
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?
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.
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.
TypeError: Cannot read properties of undefined (reading 'VStack')
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.
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`.
Module not found: Error: Can't resolve 'voltra/client' in '...'
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.
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.
Upgrade
Version history
1.4.0latest on npm
Audit
Dependencies
exporequiredRequired for the config plugin and integration within the Expo ecosystem, specifically needing Expo Dev Client and not Expo Go.
reactrequiredCore dependency for JSX syntax, component definition, and React hooks, fundamental for Voltra's component model.
react-nativerequiredProvides the foundational components, styling system, and runtime environment that Voltra extends and integrates with.
Agent activity
7 hits · last 30 days
node
6
OpenAI (training)
1
Resources
voltra — npm install voltra · libregistry