docs: revamp the attachment documentation #289
Conversation
| --- | ||
| title: "Attachments / Files" | ||
| description: Syncing large attachments/files directly using PowerSync is not recommended. | ||
| description: Keep files out of your database and handle attachments in an entirely storage-agnostic way. PowerSync syncs minimal metadata while an offline-first queue automatically handles uploads, downloads, and retries. |
There was a problem hiding this comment.
I don't think we should say "offline-first". Perhaps just "offline"?
There was a problem hiding this comment.
That would make the Queue offline which is not the case. "Offline-first" here means that it's still going to behave fine offline and would automatically sync when back online just like how the rest of PowerSync does.
stevensJourney
left a comment
stevensJourney
left a comment
There was a problem hiding this comment.
I left some minor comments, overall this doc is looks very well written and is a good guide for Attachments.
…tachment types using single and multiple queues
|
|
||
| ### Custom Storage Adapters | ||
|
|
||
| Create adapters for other storage systems: |
There was a problem hiding this comment.
It would be helpful if we can define "other" here - is it other to any of the examples we mention in the relevant sections above?
There was a problem hiding this comment.
Good catch! I have updated that section.
…tion instructions and version requirements
|
These Docs are ready as per the PR powersync-ja/powersync-js#735 and should reflect the latest changes. A final review is welcome. |
| 1- Local files exist at expected paths | ||
| 2- Repairs broken localUri references | ||
| 3- Archives attachments with missing files | ||
| 3- Requeues downloads for synced files with missing local copies |
There was a problem hiding this comment.
Duplicate "3-" labels, and maybe a conventional list using a number period format (like 1.) would read better here.
| ``` | ||
|
|
||
| ```dart Flutter | ||
| WIP need to expose the function publicly |
There was a problem hiding this comment.
NIT: Maybe add a more official "Coming soon" notice, instead of the "WIP".
| <CodeGroup> | ||
|
|
||
| ```bash JavaScript/TypeScript | ||
| Included with web and node and react-native packages, for react-native adapters install @powersync/attachments-storage-react-native. |
There was a problem hiding this comment.
I think moving these installation requirements into a list would be more conventional, since they aren't actual commands and maybe even including links to the SDK installations.
|
|
||
| - **[Supabase Storage Integration](/integration-guides/supabase-+-powersync/handling-attachments)** - Detailed guide for using Supabase Storage | ||
| - **[AWS S3 Storage Adapter Tutorial](/tutorials/client/attachments-and-files/aws-s3-storage-adapter)** - How to implement an S3 adapter | ||
| - **[PDF Attachments](tutorials/client/attachments-and-files/pdf-attachment)** - Complete API reference |
There was a problem hiding this comment.
NIT: matching the absolute links for consistency: /tutorials/client/attachments-and-files/pdf-attachment
Context
This PR revamps the PowerSync attachments documentation to provide clearer, more structured and consistent guidance for developers implementing file handling across all supported platforms.
Notable Changes
TODOs
Code Examples:
Content Review:
Related PR implementation: powersync-ja/powersync-js#735