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 libraries, including TanStack Query for React and TanStack DB for reactive data management across multiple frameworks.

​

Which package should I choose for queries?

For React or React 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 Query 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.
• For reactive data management and live query support across multiple frameworks, consider TanStack DB. PowerSync works with all TanStack DB framework adapters (React, Vue, Solid, Svelte, Angular).

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

​

TanStack

PowerSync integrates with multiple TanStack libraries:

​

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

​

TanStack DB

TanStack DB is a reactive client store that provides blazing-fast in-memory queries, optimistic updates, and cross-collection queries. When combined with PowerSync, you get the best of both worlds: TanStack DB’s powerful query capabilities with PowerSync’s battle-tested offline-first and multi-tab capable sync engine. TanStack DB Features:

• Blazing Fast In-Memory Queries: Built on differential data flow, TanStack DB’s live queries update incrementally (rather than re-running entire queries), making queries incredibly fast, even for complex queries across multiple collections.
• Reactive Data Flow: Live queries automatically update when underlying data changes, triggering component re-renders only when necessary.
• Optimistic Updates: Mutations apply instantly to the local state, providing immediate user feedback. TanStack DB maintains separate optimistic state that overlays on top of synced data, and automatically rolls back if the server request fails.
• Cross-Collection Queries: Live queries support joins across collections, allowing you to load normalized data and then denormalize it through queries.

Framework Support: PowerSync works with all TanStack DB framework adapters:

• React (@tanstack/react-db)
• Vue (@tanstack/vue-db)
• Solid (@tanstack/solid-db)
• Svelte (@tanstack/svelte-db)
• Angular (@tanstack/angular-db)

Documentation: For detailed documentation, examples, and API reference, see the TanStack DB PowerSync Collection documentation.

​

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