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.
There was a problem hiding this comment.
Item 11 in this diagram is in a slightly confusing position. Maybe this diagram could use another arrow from the local file storage block back to the Attachment Queue?
There was a problem hiding this comment.
That might imply that the local storage has anything to do with altering the state. but it's only the Attachment Queue that can alter that state. I can't think of a balanced way to do this tbh.
There was a problem hiding this comment.
I don't have a strong opinion on this. When I was first looking at this diagram, I was (in my mind) viewing this more as a process diagram than a state diagram.
There was a problem hiding this comment.
The numbers and arrows describing different flows/orders is very confusing. Would it be clearer if the download and upload flows were separate diagrams? Or:
Main diagram shows just the user-visible flow: save -> upload -> sync -> download -> stored
Separate section explains the technical mechanism: "How the queue system works", "Data model updates", etc.
Either way, open to alternatives. I just found this non-trivial to follow.
…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
|
Generally happy with the docs, the usage makes sense to me. |
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