chore: update file storage guide (supabase#37268)

* chore: update file storage guide

* doc lints

* prettier

* Update apps/docs/content/guides/functions/ephemeral-storage.mdx

Co-authored-by: Charis <[email protected]>

---------

Co-authored-by: Wen Bo Xie <[email protected]>
Co-authored-by: Charis <[email protected]>

Author: 3 people

apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts

@@ -1443,7 +1443,7 @@ export const functions: NavMenuConstant = {
       url: undefined,
       items: [
         { name: 'Background Tasks', url: '/guides/functions/background-tasks' },
-        { name: 'Ephemeral Storage', url: '/guides/functions/ephemeral-storage' },
+        { name: 'File Storage', url: '/guides/functions/ephemeral-storage' },
         { name: 'WebSockets', url: '/guides/functions/websockets' },
         { name: 'Custom Routing', url: '/guides/functions/routing' },
         { name: 'Wasm Modules', url: '/guides/functions/wasm' },

apps/docs/content/guides/functions/ephemeral-storage.mdx

@@ -1,21 +1,52 @@
 ---
 id: 'function-ephemeral-storage'
-title: 'Ephemeral Storage'
-description: 'Read and write from temporary directory'
-subtitle: 'Read and write from temporary directory'
+title: 'File Storage'
+description: 'Use persistent and ephemeral file storage'
+subtitle: 'Use persistent and ephemeral file storage'
 ---
 
-Edge Functions provides ephemeral file storage. You can read and write files to the `/tmp` directory.
+Edge Functions provides two flavors of file storage:
 
-This allows you to:
+- Persistent - backed by S3 protocol, can read/write from any S3 compatible bucket, including Supabase Storage
+- Ephemeral - You can read and write files to the `/tmp` directory. Only suitable for temporary operations
+
+You can use file storage to:
 
-- Process uploaded files temporarily without permanent storage
 - Handle complex file transformations and workflows
+- Do data migrations between projects
+- Process user uploaded files and store them
 - Unzip archives and process contents before saving to database
 
 ---
 
-## Overview
+## Persistent Storage
+
+The persistent storage option is built on top of the S3 protocol. It allows you to mount any S3-compatible bucket, including Supabase Storage Buckets, as a directory for your Edge Functions.
+You can perform operations such as reading and writing files to the mounted buckets as you would in a POSIX file system.
+
+To access an S3 bucket from Edge Functions, you must set the following for environment variables in Edge Function Secrets.
+
+- `S3FS_ENDPOINT_URL`
+- `S3FS_REGION`
+- `S3FS_ACCESS_KEY_ID`
+- `S3FS_SECRET_ACCESS_KEY`
+
+[Follow this guide](https://supabase.com/docs/guides/storage/s3/authentication) to enable and create an access key for Supabase Storage S3.
+
+To access a file path in your mounted bucket from your Edge Function, use the prefix `/s3/YOUR-BUCKET-NAME`.
+
+```tsx
+// read from S3 bucket
+const data = await Deno.readFile('/s3/my-bucket/results.csv')
+
+// make a directory
+await Deno.mkdir('/s3/my-bucket/sub-dir')
+
+// write to S3 bucket
+await Deno.writeTextFile('/s3/my-bucket/demo.txt', 'hello world')
+```
+
+## Ephemeral storage
 
 Ephemeral storage will reset on each function invocation. This means the files you write during an invocation can only be read within the same invocation.
 
@@ -128,30 +159,41 @@ Deno.serve(async (req) => {
 
 ---
 
-## Limitations
+## Using synchronous file APIs
 
-Currently, the synchronous APIs for creating or writing files are not supported:
+You can safely use the following synchronous Deno APIs (and their Node counterparts) _during initial script evaluation_:
 
-```tsx
-// ❌ Not supported
-Deno.writeFileSync('/tmp/file.txt', data)
-Deno.mkdirSync('/tmp/directory')
+- Deno.statSync
+- Deno.removeSync
+- Deno.writeFileSync
+- Deno.writeTextFileSync
+- Deno.readFileSync
+- Deno.readTextFileSync
+- Deno.mkdirSync
+- Deno.makeTempDirSync
+- Deno.readDirSync
 
-// ✅ Supported
-await Deno.writeFile('/tmp/file.txt', data)
-await Deno.mkdir('/tmp/directory')
-```
-
-You can use sync variations of read APIs:
+**Keep in mind** that the sync APIs are available only during initial script evaluation and aren’t supported in callbacks like HTTP handlers or `setTimeout`.
 
 ```tsx
-// ✅ Supported
-const data = Deno.readFileSync('/tmp/file.txt')
+Deno.statSync('...') // ✅
+
+setTimeout(() => {
+  Deno.statSync('...') // 💣 ERROR! Deno.statSync is blocklisted on the current context
+})
+
+Deno.serve(() => {
+  Deno.statSync('...') // 💣 ERROR! Deno.statSync is blocklisted on the current context
+})
 ```
 
 ---
 
 ## Limits
 
+There are no limits on S3 buckets you mount for Persistent storage.
+
+Ephemeral Storage:
+
 - Free projects: Up to 256MB of ephemeral storage
 - Paid projects: Up to 512MB of ephemeral storage