JavaScript SPA Frameworks

The PowerSync JavaScript/Web SDK is compatible with popular Single-Page Application (SPA) frameworks like React, Vue, Angular, and Svelte. For React and Vue specifically, wrapper packages are available to support reactivity and live queries, making it easier for developers to leverage PowerSync’s features.

PowerSync also integrates with TanStack Query for React (details below). This integration provides a wide range of developer tools and paves the way for future live query support in other frameworks.

​

Which package should I choose for queries?

For React or Native Native apps:

• The @powersync/react package is best for most basic use cases, especially when you only need reactive queries with loading and error states.

• For more advanced scenarios, such as query caching and pagination, TanStack is a powerful solution. The @powersync/tanstack-react-query package extends the useQuery hook from @powersync/react and adds functionality from TanStack Query, making it a better fit for advanced use cases or performance-optimized apps.

If you have a Vue app, use the Vue-specific package: @powersync/vue.

​

React Hooks

npm: @powersync/react

The @powersync/react package provides React hooks for use with the JavaScript Web SDK or React Native SDK. These hooks are designed to support reactivity, and can be used to automatically re-render React components when query results update or to access PowerSync connectivity status changes.

The main hooks available are:

• useQuery: This allows you to access the results of a watched query. The response includes isLoading, isFetching and error properties.

• useStatus: Access the PowerSync connectivity status. This can be used to update the UI based on whether the client is connected or not.

• useSuspenseQuery: This hook also allows you to access the results of a watched query, but its loading and fetching states are handled through Suspense. It automatically converts certain loading/fetching states into Suspense signals, triggering Suspense boundaries in parent components.

The full API Reference and example code can be found here:

React hooks for PowerSync | PowerSync JavaScript SDK Docs

​

PowerSync <> TanStack Query

PowerSync integrates with TanStack Query (formerly React Query) through the @powersync/tanstack-react-query package.

npm: @powersync/tanstack-react-query

This package wraps TanStack’s useQuery and useSuspenseQuery hooks, bringing many of TanStack’s advanced asynchronous state management features to PowerSync web and React Native applications, including:

• Loading and error states via useQuery

• React Suspense support: useSuspenseQuery automatically converts certain loading states into Suspense signals, triggering Suspense boundaries in parent components.

• Caching queries: Queries are cached with a unique key and reused across the app, so subsequent instances of the same query won’t refire unnecessarily.

• Built-in support for pagination

​

Example Use Case

When navigating to or refreshing a page, you may notice a brief UI “flicker” (10-50ms). Here are a few ways to manage this with TanStack Query:

• First load: When a page loads for the first time, use a loading indicator or a Suspense fallback to handle queries. See the examples.

• Subsequent loads: With TanStack’s query caching, subsequent loads of the same page won’t refire queries, which reduces the flicker effect.

• Block navigation until components are ready: Using useSuspenseQuery, you can ensure that navigation from page A to page B only happens after the queries for page B have loaded. You can do this by combining useSuspenseQuery with the <Suspense /> element and React Router’s v7_startTransition future flag, which blocks navigation until all suspending components are ready.

​

Usage and Examples

For more examples and usage details, see the package README.

The full API Reference can be found here:

TanStack React Query | PowerSync JavaScript SDK Docs

​

Vue Composables

npm: @powersync/vue

The powersync/vue package is a Vue-specific wrapper for PowerSync. It provides Vue composables that are designed to support reactivity, and can be used to automatically re-render components when query results update or to access PowerSync connectivity status changes.

The main hooks available are:

• useQuery: This allows you to access the results of a watched query. The response includes isLoading, isFetching and error properties.

• useStatus: Access the PowerSync connectivity status. This can be used to update the UI based on whether the client is connected or not.

The full API Reference and example code can be found here:

Vue composables for PowerSync | PowerSync JavaScript SDK Docs