Add rx.asset documentation and explain difference between assets and upload directory

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

Author: devin-ai-integration[bot]

docs/assets/overview.md

@@ -15,7 +15,11 @@ when running in production mode. The `assets/` folder should only be used for st
 
 ## Referencing Assets
 
-To reference an image in the `assets/` simply pass the relative path as a prop.
+There are two ways to reference assets in your Reflex app:
+
+### 1. Direct Path Reference
+
+To reference an image in the `assets/` folder, simply pass the relative path as a prop.
 
 For example, you can store your logo in your assets folder:
 
@@ -34,6 +38,53 @@ 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.
 ```
 
+### 2. Using rx.asset Function
+
+The `rx.asset` function provides a more flexible way to reference assets in your app. It supports both local assets (in the app's `assets/` directory) and shared assets (placed next to your Python files).
+
+#### Local Assets
+
+Local assets are stored in the app's `assets/` directory and are referenced using `rx.asset`:
+
+```python demo
+rx.image(src=rx.asset("Reflex.svg"), width="5em")
+```
+
+#### Shared Assets
+
+Shared assets are placed next to your Python file and are linked to the app's external assets directory. This is useful for creating reusable components with their own assets:
+
+```python box
+# my_component.py
+import reflex as rx
+
+# my_script.js is located next to this Python file
+def my_component():
+    return rx.box(
+        rx.script(src=rx.asset("my_script.js", shared=True)),
+        "Component with custom script"
+    )
+```
+
+You can also specify a subfolder for shared assets:
+
+```python box
+# my_component.py
+import reflex as rx
+
+# image.png is located in a subfolder next to this Python file
+def my_component_with_image():
+    return rx.image(
+        src=rx.asset("image.png", shared=True, subfolder="images")
+    )
+```
+
+```md alert
+# Shared assets are linked to your app via symlinks.
+
+When using `shared=True`, the asset is symlinked from its original location to your app's external assets directory. This allows you to keep assets alongside their related code.
+```
+
 ## Favicon
 
 The favicon is the small icon that appears in the browser tab.

docs/assets/upload_and_download_files.md

@@ -10,6 +10,26 @@ In addition to any assets you ship with your app, many web app will often need t
 
 In this section, we will cover all you need to know for manipulating files in Reflex.
 
+## Assets vs Upload Directory
+
+Before diving into file uploads and downloads, it's important to understand the difference between assets and the upload directory in Reflex:
+
+| Feature | Assets | Upload Directory |
+| --- | --- | --- |
+| Purpose | Static files included with your app (images, stylesheets, scripts) | Dynamic files uploaded by users during runtime |
+| Location | `assets/` folder or next to Python files (shared assets) | `uploaded_files/` directory (configurable) |
+| Access Method | `rx.asset()` or direct path reference | `rx.get_upload_url()` |
+| When to Use | For files that are part of your application's codebase | For files that users upload through your application |
+| Availability | Available at compile time | Available at runtime |
+
+```md alert
+# Assets are primarily intended for frontend use
+
+Assets in Reflex are primarily intended for frontend use and are not expected to be read from the backend. When assets are needed in both frontend and backend, they are currently copied to the backend (though this behavior may change in future versions).
+```
+
+For more information about assets, see the [Assets Overview](/docs/assets/overview/).
+
 ## Download
 
 If you want to let the users of your app download files from your server to their computer, Reflex offer you two way.