Feat/tutorials #44

HeinrichvonStein · 2024-11-28T14:07:23Z

This PR adds a Tutorial section to the docs as well as a new Coolify + PowerSync integration guide.

Mintlify dev server running on an EC2 instance: server

Specific pages:

Not too sure about the videos and possible storage implications. Open to any suggestions

benitav · 2024-11-28T14:55:03Z

is it correct that this is still in draft status? just checking about it since typically we update that status to review if it's ready for review.

Chriztiaan · 2024-11-29T08:23:07Z

tutorials/code-changes/supabase-connector-performance.mdx

@@ -0,0 +1,271 @@
+---


I guess it would have been cool if we chose one of these two implementations as the default, but maybe it's fine to have a baseline connector example of a supabase connector and give the options to improve it with these two snippets.

We could yes. My thinking behind it was that the examples provide an easy way for users to get started and see example implementations - which are inherently basic and not performance optimized. Should they require better performance or some other improvement, they can have a look at the tutorials to see how that could be done.

It also provides an easy and concise way for users to see what needs to be changed should they want to make that specific improvement.

benitav · 2024-11-29T12:44:04Z

"Code examples" isn't a very useful tutorial grouping IMO - won't all tutorials be/include code examples? I think a grouping by topic would be more intuitive e.g. backend database, client side, self hosting, because that's how users faced with a problem will likely navigate/filter. Maybe I need to better understand what other groups we are envisioning aside from code examples.

benitav · 2024-11-29T12:47:16Z

tutorials/code-changes/aws-s3-storage-adapter.mdx

+title: "Use AWS S3 for attachment storage"
+description: "In this tutorial, we will show you how to use AWS S3 for attachment storage by modifying the [React Native To-Do List example app](https://github.com/powersync-ja/powersync-js/tree/main/demos/react-native-supabase-todolist)."
+sidebarTitle: "AWS S3 attachment storage"
+---


to orient the user state what makes this different from the example app - i.e. there Supabase storage is used

We mention React Native here, but will the same/similar also apply to web? If so we should state that, so that web users also know whether this could be relevant to them

@benitav The deps I added are only applicable for React Native so I'm unsure what deps would be required for web and we would probably have a similar tutorial for web-based projects.

benitav · 2024-11-29T12:49:12Z

tutorials/code-changes/aws-s3-storage-adapter.mdx

+
+<Warning>
+    The following pre-requisites are required to complete this tutorial:
+    - Clone the [To-Do List example app](https://github.com/powersync-ja/powersync-js/tree/main/demos/react-native-supabase-todolist)


I find it a bit unintuitive saying cloning an app - they need to clone the repo?

benitav · 2024-11-29T12:52:13Z

tutorials/code-changes/aws-s3-storage-adapter.mdx

+        ```
+        </Accordion>
+
+        <Accordion title="Explanation">


I would keep uploadFile, downloadFile, deleteFile expanded - since it's not a lot of text the additional clicks expanding the accordions is more annoying that useful. The user already opted to see the Explanation.

benitav · 2024-11-29T12:54:21Z

tutorials/code-changes/aws-s3-storage-adapter.mdx

+</AccordionGroup>
+
+## The complete files used in this tutorial can be found below:
+<Accordion title="Files">


Since the files are fairly compact already with the tabs (nice), I don't think the accordion adds a lot of value here- again, feels more annoying to have to do the extra click than useful.

benitav · 2024-11-29T12:56:14Z

tutorials/code-changes/supabase-connector-performance.mdx

+<AccordionGroup>
+    <Accordion title="Sequential Merge Strategy">
+        <Note>
+            Shoutout to Christoffer Årstrand for the original implementation of this optimization.


It would be safer to use people's username / handle - since some people might not be comfortable having their name out there

Good catch, didn't think about that. Will update it to use discord handle

benitav · 2024-11-29T12:58:50Z

tutorials/code-changes/supabase-connector-performance.mdx

+title: "Improve Supabase Connector Performance"
+description: "In this tutorial we will show you how to improve the performance of the Supabase Connector for the [React Native To-Do List example app](https://github.com/powersync-ja/powersync-js/tree/main/demos/react-native-supabase-todolist)."
+---
+


This needs an intro to set the stage. All I see is various "strategy" headings, but I don't quickly have an idea what the problem is with the existing implementation, how we're going to solve it, and how all the headings fit in.

Related, it's not clear to me whether I should open any of those accordions, and after opening one I just see a big blob of code, with no explanation/intro/guidance.

Agreed, context is definitely a good thing!
Will add both context and more guidance on the code!

benitav · 2024-11-29T13:06:02Z

Overall, we need to think about cross referencing to these new sections across relevant other topics in the docs. For example, think about users self-hosting and following the current Installation instructions. They might not realize that we have this Coolify tutorial, so when it becomes relevant in the process, we should say something like "using coolify? check out our guide". Another example is whether we should add to/update "Deployment Templates (15 minutes)" on the Self Hosting -> Getting started page to mention this tutorial. Another example is linking to Tutorials on our main page https://docs.powersync.com/intro/powersync-overview - possibly under Examples - then that heading could be renamed. These are just examples I could think of quickly - def not exhaustive.

HeinrichvonStein · 2024-11-29T13:20:19Z

"Code examples" isn't a very useful tutorial grouping IMO - won't all tutorials be/include code examples? I think a grouping by topic would be more intuitive e.g. backend database, client side, self hosting, because that's how users faced with a problem will likely navigate/filter. Maybe I need to better understand what other groups we are envisioning aside from code examples.

The tutorials might include things like "Adding PowerSync to your project" which doesn't really fit into the "Code examples" category. My thinking behind "Code examples" was that those tutorials would show how to make specific changes in the code or focus heavily on code changes rather than the typical "step by step guide". It shows the user how they could modify the code.

I definitely like the idea of more intuitive groupings as suggested.

Edit:
Alternatively, we could group the integration guides and tutorials together as two main headings from which things could branch off of?

cahofmeyr · 2024-12-05T15:27:48Z

@benitav should we also link to these tutorials from other places?

For example link to the S3 one from here https://docs.powersync.com/usage/use-case-examples/attachments-files

And link to the Supabase one from here https://docs.powersync.com/integration-guides/supabase-+-powersync and maybe here https://docs.powersync.com/resources/demo-apps-example-projects

benitav · 2024-12-09T07:00:10Z

Yeah @HeinrichvonStein - I had similar feedback #44 (comment). Let me know if I can leave this with you?

HeinrichvonStein · 2024-12-09T07:51:40Z

@benitav @cahofmeyr Will update the docs accordingly.

rkistner · 2025-01-13T14:31:33Z

tutorials/client/attachment-storage/aws-s3-storage-adapter.mdx

+            EXPO_PUBLIC_AWS_S3_REGION=region
+            EXPO_PUBLIC_AWS_S3_BUCKET_NAME=bucket_name
+            EXPO_PUBLIC_AWS_S3_ACCESS_KEY_ID=***
+            EXPO_PUBLIC_AWS_S3_ACCESS_SECRET_ACCESS_KEY=***


This bit is quite problematic for security - the AWS credentials should never be exposed directly on the client - it could expose access to the entire S3 bucket to the user.

A good workflow with S3 works like this:

Client makes an API call to the app backend, using the client credentials (e.g. a Supabase Edge Function).

The backend API has the S3 credentials. It signs a S3 upload URL, and returns that to the client.

The client uploads to the pre-signed S3 URL.

This workflow keeps the credentials on the server, without the actual attachment data needing to go through the server.

The same can be done for downloading attachments.

The Uppy has some good documentation on uploading to S3 from a client.

Thanks @rkistner We'll take a look.

@michaelbarnes @rkistner I've created #99 for this update.

Hein added 4 commits November 28, 2024 15:36

Add coolify guide

d609e5c

Add S3 storage tutorial

7080cc7

Add supabase connector

c3f54b7

Merge remote-tracking branch 'origin/docs' into feat/tutorials

c9c7ee2

HeinrichvonStein requested a review from benitav November 28, 2024 14:07

HeinrichvonStein marked this pull request as ready for review November 29, 2024 05:18

Chriztiaan reviewed Nov 29, 2024

View reviewed changes

benitav reviewed Nov 29, 2024

View reviewed changes

HeinrichvonStein mentioned this pull request Nov 29, 2024

Feat/coolify self host #37

Closed

Hein added 7 commits December 2, 2024 11:54

Update user handle

f21e78c

Add context and background

3d4f7c3

Formatting and fixes

cff178b

Merge remote-tracking branch 'origin/docs' into feat/tutorials

3b1bcea

Minor update to supabaseConnector

367a5cc

Add groupings

ce7a38c

Merge remote-tracking branch 'origin/docs' into feat/tutorials

2b126af

HeinrichvonStein requested a review from benitav December 3, 2024 15:39

benitav approved these changes Dec 4, 2024

View reviewed changes

Merge branch 'docs' into feat/tutorials

6532b63

HeinrichvonStein merged commit 00e4bd3 into docs Dec 4, 2024
1 check passed

HeinrichvonStein deleted the feat/tutorials branch December 4, 2024 06:27

rkistner reviewed Jan 13, 2025

View reviewed changes

HeinrichvonStein mentioned this pull request Jan 29, 2025

Use edge functions #99

Merged

Feat/tutorials #44

Feat/tutorials #44

Uh oh!

Conversation

HeinrichvonStein commented Nov 28, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

benitav commented Nov 28, 2024

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

benitav commented Nov 29, 2024

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

HeinrichvonStein Dec 2, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

benitav commented Nov 29, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

HeinrichvonStein commented Nov 29, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

cahofmeyr commented Dec 5, 2024

Uh oh!

benitav commented Dec 9, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

HeinrichvonStein commented Dec 9, 2024

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

HeinrichvonStein commented Nov 28, 2024 •

edited

Loading

HeinrichvonStein Dec 2, 2024 •

edited

Loading

benitav commented Nov 29, 2024 •

edited

Loading

HeinrichvonStein commented Nov 29, 2024 •

edited

Loading

benitav commented Dec 9, 2024 •

edited

Loading