Improved Attachment Utilities in the JavaScript SDKs

Attachment support is now built into @powersync/common, used by all our platform SDKs (Web, React Native, and Node.js). The standalone @powersync/attachments package is now deprecated.

Overview

Attachments (e.g. files, photos) are synced differently from regular data: PowerSync syncs small metadata records while files live in storage (S3, Supabase, etc.), and an offline-first queue handles uploads, downloads, and retries. The SDKs' attachment helpers implement that pattern — local and remote storage adapters, queue, and state management. Building this into the SDKs means fewer dependencies, one consistent API across Web, React Native, and Node.js, and closer alignment with how our Dart, Kotlin, and Swift SDKs handle attachments. For file storage on the device, we also ship the right adapter with each SDK: IndexedDB (browser storage) for Web, the local filesystem for Node.js, and a separate React Native package for device storage (Expo or bare R/N).

What this adds

• Built-in attachment support in @powersync/common and platform SDKs, so you no longer depend on the separate @powersync/attachments package.

• Platform-specific adapters for on-device storage: Web uses IndexedDB (via the Web SDK); Node and React Native each ship their own storage adapter. The SDK also accepts custom local and remote storage adapters.

• Consistency with other SDKs: The JS attachment API is a port of the same functionality used in our Swift, Dart, and Kotlin SDKs (including support for a meta_data column and persistence in the attachments table) which should improve maintenance and feature parity going forward.

Availability

These changes shipped in the following releases:

• @powersync/web v1.33.0

• @powersync/react-native v1.30.0

• @powersync/node v0.17.0

Going forward, new attachment feature work will happen in the built-in implementation. The @powersync/attachments package will be maintained for critical bug fixes only and should be considered deprecated.

Documentation

Alongside the new helpers we refreshed the Attachments / Files docs. The docs now walk through the full flow (save file → upload → sync → download on other devices), explain the core concepts clearly, and make it easier to get started with complete examples.

Getting started

• Docs: Attachments / Files — setup instructions and code examples for Web, React Native and Node.js.

• Demos: The React Native Todo List and React Web Todo List demos use the new attachment functionality and can be used as references when getting started.

• Migration from @powersync/attachments: See the migration notes in our docs.

• React Native: Install @powersync/attachments-storage-react-native for on-device file storage (see the React Native section in the docs).

• Capacitor (limited support): Attachment support for the Capacitor SDK is limited at this stage. You can use the Web SDK’s persistence APIs for attachments, but a filesystem-based implementation would be preferable and is not yet available. If you need device filesystem storage, you can implement your own local storage adapter using Capacitor’s filesystem APIs.

Feature status (Alpha)

The built-in JavaScript attachment helpers are in Alpha. That means they are not production-ready: APIs may still change and breaking changes can occur without notice. We welcome feedback from the community to help refine these APIs.

Feedback and questions

If you run into issues migrating or have ideas for the new APIs, we'd like to hear from you. Reach out on Discord or open a discussion/issue on GitHub.