Skip to content

docs: revamp the attachment documentation #289

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
khawarizmus wants to merge 21 commits into
base: main
Choose a base branch
from
Open

docs: revamp the attachment documentation #289

Show file tree
Hide file tree
Changes from 16 commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
8be592d
docs(WIP): revamped the attachment documentation
Nov 19, 2025
0e1d577
docs: Add attachment flow diagram and update imports for js attachments
Nov 20, 2025
1ddbd42
docs: added Kotlin code examples
Nov 20, 2025
7ac538f
docs: added Flutter code examples
Nov 20, 2025
89e69a2
docs: add Swift code examples
Nov 20, 2025
00987c1
docs: add deprecation warnings
Nov 20, 2025
f3c095d
docs: update import paths and correct Kotlin attachment links
Nov 20, 2025
b272c2c
docs: update attachment documentation to include PDF attachments and …
Nov 20, 2025
8c4ac84
docs: added some suggestions in
Nov 24, 2025
795b29d
docs: add new patterns and detailed examples for watching multiple at…
Nov 26, 2025
80b8360
docs: remove the filename requirements for now
Nov 28, 2025
fa3cf60
docs: standardize fileExtension formatting in attachment examples
Nov 28, 2025
06f9c77
Merge branch 'main' into attachments
khawarizmus Nov 28, 2025
ecf209b
docs: update attachment-related documentation structure and redirect …
Dec 1, 2025
c15b213
docs: clarify example for implementing custom storage adapter for IPFS
Dec 2, 2025
509ddf7
docs: update React Native storage adapter documentation with installa…
Jan 19, 2026
ea7ccd1
fix: correct import statement formatting
Jan 20, 2026
fc9aff0
Merge branch 'main' into attachments
Feb 2, 2026
b1dec98
Addressed various comments and added the blog post as a resources
Feb 2, 2026
dae51c6
Update blog post link in attachments-files.mdx to reflect the correct…
Feb 4, 2026
0059b68
Refactor attachments documentation: correct import syntax, update att…
Feb 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 16 additions & 9 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -216,7 +216,6 @@
"group": "Supabase",
"pages": [
"integration-guides/supabase-+-powersync",
"integration-guides/supabase-+-powersync/handling-attachments",
"integration-guides/supabase-+-powersync/realtime-streaming",
"integration-guides/supabase-+-powersync/rls-and-sync-rules",
"integration-guides/supabase-+-powersync/local-development"
Expand Down Expand Up @@ -424,14 +423,6 @@
"tutorials/client/sdks/web/next-js"
]
},
{
"group": "Attachments / Files",
"pages": [
"tutorials/client/attachments-and-files/overview",
"tutorials/client/attachments-and-files/aws-s3-storage-adapter",
"tutorials/client/attachments-and-files/pdf-attachment"
]
},
{
"group": "Performance",
"pages": [
Expand Down Expand Up @@ -693,6 +684,22 @@
{
"source": "/client-sdk-references/kotlin-multiplatform/libraries/room",
"destination": "/client-sdk-references/kotlin/libraries/room"
},
{
"source": "/tutorials/client/attachments-and-files/overview",
"destination": "/usage/use-case-examples/attachments-files"
},
{
"source": "/tutorials/client/attachments-and-files/aws-s3-storage-adapter",
"destination": "/usage/use-case-examples/attachments-files"
},
{
"source": "/tutorials/client/attachments-and-files/pdf-attachment",
"destination": "/usage/use-case-examples/attachments-files"
},
{
"source": "/integration-guides/supabase-+-powersync/handling-attachments",
"destination": "/usage/use-case-examples/attachments-files"
}
]
}
Binary file added images/attachments/attachments-flow.png
View file
Open in desktop
Copy link
Contributor

@stevensJourney stevensJourney Nov 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor Author

@khawarizmus khawarizmus Nov 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

@stevensJourney stevensJourney Nov 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

@Chriztiaan Chriztiaan Jan 21, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading