Improve assets documentation

Co-Authored-By: Alek Petuskey <[email protected]>

Author: devin-ai-integration[bot]

docs/assets/overview.md

@@ -4,7 +4,7 @@ import reflex as rx
 
 # Assets
 
-Static files such as images and stylesheets can be placed in `assets/` folder of the project. These files can be referenced within your app.
+Static files such as images, stylesheets, fonts, and other resources can be placed in the `assets/` folder of your Reflex project. These files are automatically made available to your application during both development and production.
 
 ```md alert
 # Assets are copied during the build process.
@@ -13,9 +13,39 @@ Any files placed within the `assets/` folder at runtime will not be available to
 when running in production mode. The `assets/` folder should only be used for static files.
 ```
 
+## Types of Assets
+
+Reflex supports various types of static assets:
+
+- **Images**: PNG, JPG, GIF, SVG, WebP, etc.
+- **Stylesheets**: CSS files
+- **Fonts**: TTF, OTF, WOFF, WOFF2
+- **Scripts**: JavaScript files
+- **Data files**: JSON, CSV, etc.
+- **Media**: Audio, video files
+- **Documents**: PDF, etc.
+
+## Asset Directory Structure
+
+The `assets/` directory is located at the root of your Reflex project. You can organize your assets in subdirectories for better management:
+
+```bash
+assets/
+├── images/
+│   ├── logo.png
+│   └── background.jpg
+├── css/
+│   └── custom.css
+├── fonts/
+│   └── custom-font.ttf
+├── js/
+│   └── script.js
+└── favicon.ico
+```
+
 ## Referencing Assets
 
-To reference an image in the `assets/` simply pass the relative path as a prop.
+To reference an asset in your Reflex app, use the path relative to the `assets/` directory, prefixed with a forward slash `/`.
 
 For example, you can store your logo in your assets folder:
 
@@ -34,8 +64,76 @@ rx.image(src="/Reflex.svg", width="5em")
 # Always prefix the asset path with a forward slash `/` to reference the asset from the root of the project, or it may not display correctly on non-root pages.
 ```
 
+## Using Assets in Different Components
+
+Assets can be used in various Reflex components:
+
+### Images
+
+```python
+rx.image(src="/images/logo.png", width="100px")
+```
+
+### CSS Stylesheets
+
+```python
+rx.link(rel="stylesheet", href="/css/custom.css")
+```
+
+### JavaScript Files
+
+```python
+rx.script(src="/js/script.js")
+```
+
+### Background Images in Style Props
+
+```python
+rx.box(
+    width="100%",
+    height="200px",
+    background_image="url('/images/background.jpg')",
+    background_size="cover",
+)
+```
+
+## Shared Assets
+
+For library developers, Reflex provides a way to share assets from your library with applications that use your library. This is done using the `rx.asset()` function:
+
+```python
+rx.image(src=rx.asset(path="my_image.png", shared=True))
+```
+
+When `shared=True`, the asset is expected to be located next to the Python file that references it, not in the app's `assets/` directory. Reflex will automatically create a symlink to make the asset available to the app.
+
+You can also specify a subfolder for shared assets:
+
+```python
+rx.image(src=rx.asset(path="my_image.png", shared=True, subfolder="images"))
+```
+
 ## Favicon
 
 The favicon is the small icon that appears in the browser tab.
 
-You can add a `favicon.ico` file to the `assets/` folder to change the favicon.
+You can add a `favicon.ico` file to the `assets/` folder to change the favicon. Reflex will automatically detect and use this file.
+
+For more modern favicon formats, you can also include:
+
+```html
+<!-- In your head component -->
+<link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png">
+<link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png">
+<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">
+```
+
+## Asset Optimization
+
+When building your app for production with `reflex deploy` or `reflex export`, Reflex will automatically optimize your assets:
+
+- Images may be compressed
+- CSS and JavaScript files may be minified
+- Assets are given unique filenames for cache busting
+
+This optimization helps improve the performance of your application in production.

docs/assets/upload_and_download_files.md

@@ -6,57 +6,80 @@ from pcweb.pages.docs import api_reference
 
 # Files
 
-In addition to any assets you ship with your app, many web app will often need to receive or send files, whether you want to share media, allow user to import their data, or export some backend data.
+In addition to static assets that ship with your app, many web applications need to handle dynamic file operations such as:
 
-In this section, we will cover all you need to know for manipulating files in Reflex.
+- Allowing users to download files from your server
+- Enabling users to upload files to your server
+- Processing uploaded files on the backend
+- Generating files dynamically for download
+
+This section covers everything you need to know about file handling in Reflex.
 
 ## Download
 
-If you want to let the users of your app download files from your server to their computer, Reflex offer you two way.
+Reflex offers multiple ways to let users download files from your server to their computer.
 
-### With a regular link
+### With a Regular Link
 
-For some basic usage, simply providing the path to your resource in a `rx.link` will work, and clicking the link will download or display the resource.
+For basic usage, simply providing the path to your resource in an `rx.link` component will work. Clicking the link will download or display the resource depending on the file type and browser settings.
 
 ```python demo
-rx.link("Download", href="/reflex_banner.png")
+rx.link("Download Image", href="/reflex_banner.png")
 ```
 
-### With `rx.download` event
+This approach works well for:
+- Static files in your assets directory
+- Files that can be displayed in the browser (images, PDFs, etc.)
+- Simple download scenarios
+
+### With `rx.download` Event
 
-Using the `rx.download` event will always prompt the browser to download the file, even if it could be displayed in the browser.
+For more control over the download process, use the `rx.download` event. This approach:
+- Always prompts the browser to download the file (even if it could be displayed)
+- Can be triggered from any UI event or backend event handler
+- Allows renaming the downloaded file
+- Supports dynamically generated content
 
-The `rx.download` event also allows the download to be triggered from another backend event handler.
+#### Basic Download
 
 ```python demo
 rx.button(
-    "Download",
+    "Download Image",
     on_click=rx.download(url="/reflex_banner.png"),
 )
 ```
 
-`rx.download` lets you specify a name for the file that will be downloaded, if you want it to be different from the name on the server side.
+#### Renaming Downloaded Files
+
+You can specify a different filename for the downloaded file:
 
 ```python demo
 rx.button(
     "Download and Rename",
     on_click=rx.download(
         url="/reflex_banner.png",
-        filename="different_name_logo.png"
+        filename="reflex_logo.png"
     ),
 )
 ```
 
-If the data to download is not already available at a known URL, pass the `data` directly to the `rx.download` event from the backend.
+#### Dynamically Generated Downloads
+
+If the data to download is not already available at a known URL, you can pass the `data` directly to the `rx.download` event from the backend:
 
 ```python demo exec
 import random
 
 class DownloadState(rx.State):
     @rx.event
     def download_random_data(self):
+        """Generate and download random data as a CSV file."""
+        # Generate random data
+        data = ",".join([str(random.randint(0, 100)) for _ in range(10)])
+        
+        # Return a download event with the data
         return rx.download(
-            data=",".join([str(random.randint(0, 100)) for _ in range(10)]),
+            data=data,
             filename="random_numbers.csv"
         )
 
@@ -67,24 +90,167 @@ def download_random_data_button():
     )
 ```
 
-The `data` arg accepts `str` or `bytes` data, a `data:` URI, `PIL.Image`, or any state Var. If the Var is not already a string, it will be converted to a string using `JSON.stringify`. This allows complex state structures to be offered as JSON downloads.
+#### Supported Data Types
+
+The `data` parameter of `rx.download` accepts various types:
 
-Reference page for `rx.download` [here]({api_reference.special_events.path}#rx.download).
+- `str`: Text data (will be encoded as UTF-8)
+- `bytes`: Binary data
+- `data:` URI: For inline data
+- `PIL.Image`: Image objects from the Pillow library
+- Any state `Var`: Will be converted to JSON if not already a string
+
+This flexibility allows you to offer complex state structures as JSON downloads:
+
+```python
+@rx.event
+def download_user_data(self):
+    """Download the user's data as a JSON file."""
+    return rx.download(
+        data=self.user_data,  # This could be a dict or any JSON-serializable object
+        filename="user_data.json"
+    )
+```
+
+For more details on `rx.download`, see the [reference page]({api_reference.special_events.path}#rx.download).
 
 ## Upload
 
-Uploading files to your server let your users interact with your app in a different way than just filling forms to provide data.
+File uploads are essential for many web applications. Reflex provides the `rx.upload` component to handle file uploads with features like:
 
-The component `rx.upload` let your users upload files on the server.
+- Drag-and-drop support
+- Multiple file selection
+- File type filtering
+- Upload progress tracking
+- Cancellation support
 
-Here is a basic example of how it is used:
+### Basic Upload Example
+
+Here's a simple example of how to use the upload component:
 
 ```python
+class UploadState(rx.State):
+    """State for handling file uploads."""
+    
+    # Store the uploaded filenames
+    files: list[str] = []
+    
+    @rx.event
+    async def handle_upload(self, files: list[rx.UploadFile]):
+        """Process uploaded files.
+        
+        Args:
+            files: List of uploaded files from the frontend.
+        """
+        for file in files:
+            # Read the file data
+            upload_data = await file.read()
+            
+            # Define the output path
+            outfile = rx.get_upload_dir() / file.filename
+            
+            # Save the file
+            with outfile.open("wb") as file_object:
+                file_object.write(upload_data)
+            
+            # Update the state with the filename
+            self.files.append(file.filename)
+
 def index():
-    return rx.fragment(
-        rx.upload(rx.text("Upload files"), rx.icon(tag="upload")),
-        rx.button(on_submit=State.<your_upload_handler>)
+    """The main view with upload functionality."""
+    return rx.vstack(
+        # Upload component
+        rx.upload(
+            rx.vstack(
+                rx.button("Select Files", color="primary"),
+                rx.text("or drag and drop files here"),
+            ),
+            id="file_upload",
+            border="1px dashed #ccc",
+            padding="2em",
+        ),
+        
+        # Display selected files
+        rx.hstack(rx.foreach(rx.selected_files("file_upload"), rx.text)),
+        
+        # Upload button
+        rx.button(
+            "Upload Files",
+            on_click=UploadState.handle_upload(rx.upload_files(upload_id="file_upload")),
+        ),
+        
+        # Clear selection button
+        rx.button(
+            "Clear Selection",
+            on_click=rx.clear_selected_files("file_upload"),
+        ),
+        
+        # Display uploaded files
+        rx.vstack(
+            rx.heading("Uploaded Files"),
+            rx.foreach(
+                UploadState.files,
+                lambda filename: rx.link(
+                    filename,
+                    href=rx.get_upload_url(filename),
+                    target="_blank",
+                ),
+            ),
+        ),
+        spacing="4",
+        padding="2em",
     )
 ```
 
-For detailed information, see the reference page of the component [here]({library.forms.upload.path}).
+### Upload Process Flow
+
+1. User selects files via the `rx.upload` component (by clicking or drag-and-drop)
+2. Selected files appear in the UI using `rx.selected_files("upload_id")`
+3. User clicks an upload button that triggers an event handler with `rx.upload_files(upload_id="upload_id")`
+4. The event handler receives the files as `list[rx.UploadFile]` objects
+5. The handler processes the files (saving, analyzing, etc.)
+6. The UI updates to reflect the uploaded files
+
+### File Storage and Access
+
+Reflex provides helper functions to manage uploaded files:
+
+#### `rx.get_upload_dir()`
+
+Returns the directory where uploaded files should be saved. By default, this is `./uploaded_files` in your project root, but it can be configured with the `REFLEX_UPLOADED_FILES_DIR` environment variable.
+
+```python
+# Save an uploaded file
+outfile = rx.get_upload_dir() / file.filename
+with outfile.open("wb") as f:
+    f.write(file_data)
+```
+
+#### `rx.get_upload_url(filename)`
+
+Returns the URL to access an uploaded file. This URL is automatically mounted by Reflex at `/_upload/`.
+
+```python
+# Display an uploaded image
+rx.image(src=rx.get_upload_url("my_image.jpg"))
+
+# Create a link to an uploaded file
+rx.link("Download PDF", href=rx.get_upload_url("document.pdf"))
+```
+
+```md alert info
+# File Persistence Warning
+
+When using the Reflex hosting service, the uploaded files directory is not persistent and will be cleared on every deployment. For persistent storage of uploaded files in production, it's recommended to use an external service such as AWS S3, Google Cloud Storage, or similar cloud storage solutions.
+```
+
+### Advanced Upload Features
+
+For more advanced upload scenarios, see the [Upload component reference]({library.forms.upload.path}) which covers:
+
+- Multiple file uploads
+- Single file uploads
+- File type restrictions
+- Upload progress tracking
+- Upload cancellation
+- Custom styling