Add rx.asset documentation and explain difference between assets vs upload directory (#1313)

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

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

* Remove 'simply' from documentation as requested in PR review

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

* Replace markdown table with Reflex table component

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

* Update table to use rx.code with violet styling for quoted items

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

* Fix spacing property in HStack component to use valid value

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

* Change table code block to use python eval instead of demo exec

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

* Change table code block to use python box instead of eval

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

* Change table code block to use python demo instead of box

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

* Restructure table code to use direct expressions with python demo exec

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

* Simplify table code and use python eval to hide code display

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

* Address PR comments: update rx.asset documentation

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

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: Alek Petuskey <[email protected]>
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, 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 in the same directory as 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

@@ -2,6 +2,8 @@
 import reflex as rx
 from pcweb.pages.docs import library
 from pcweb.pages.docs import api_reference
+from pcweb.styles.styles import get_code_style
+from pcweb.styles.colors import c_color
 ```
 
 # Files
@@ -10,6 +12,67 @@ 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:
+
+```python eval
+# Simple table comparing assets vs upload directory
+rx.table.root(
+    rx.table.header(
+        rx.table.row(
+            rx.table.column_header_cell("Feature"),
+            rx.table.column_header_cell("Assets"),
+            rx.table.column_header_cell("Upload Directory"),
+        ),
+    ),
+    rx.table.body(
+        rx.table.row(
+            rx.table.cell(rx.text("Purpose", font_weight="bold")),
+            rx.table.cell(rx.text("Static files included with your app (images, stylesheets, scripts)")),
+            rx.table.cell(rx.text("Dynamic files uploaded by users during runtime")),
+        ),
+        rx.table.row(
+            rx.table.cell(rx.text("Location", font_weight="bold")),
+            rx.table.cell(rx.hstack(
+                rx.code("assets/", style=get_code_style("violet")),
+                rx.text(" folder or next to Python files (shared assets)"),
+                spacing="2",
+            )),
+            rx.table.cell(rx.hstack(
+                rx.code("uploaded_files/", style=get_code_style("violet")),
+                rx.text(" directory (configurable)"),
+                spacing="2",
+            )),
+        ),
+        rx.table.row(
+            rx.table.cell(rx.text("Access Method", font_weight="bold")),
+            rx.table.cell(rx.hstack(
+                rx.code("rx.asset()", style=get_code_style("violet")),
+                rx.text(" or direct path reference"),
+                spacing="2",
+            )),
+            rx.table.cell(rx.code("rx.get_upload_url()", style=get_code_style("violet"))),
+        ),
+        rx.table.row(
+            rx.table.cell(rx.text("When to Use", font_weight="bold")),
+            rx.table.cell(rx.text("For files that are part of your application's codebase")),
+            rx.table.cell(rx.text("For files that users upload or generate through your application")),
+        ),
+        rx.table.row(
+            rx.table.cell(rx.text("Availability", font_weight="bold")),
+            rx.table.cell(rx.text("Available at compile time")),
+            rx.table.cell(rx.text("Available at runtime")),
+        ),
+    ),
+    width="100%",
+)
+```
+
+
+
+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.

docs/wrapping-react/guide.md

@@ -441,28 +441,26 @@ def index():
 
 ## Assets
 
-_Experimental feature added in v0.5.3_.
-
 If a wrapped component depends on assets such as images, scripts, or
-stylesheets, these can kept adjacent to the component code and
-included in the final build using the `rx._x.asset` function.
+stylesheets, these can be kept adjacent to the component code and
+included in the final build using the `rx.asset` function.
 
-`rx._x.asset` returns a relative path that references the asset in the compiled
+`rx.asset` returns a relative path that references the asset in the compiled
 output. The target files are copied into a subdirectory of `assets/external`
 based on the module where they are initially used. This allows third-party
 components to have external assets with the same name without conflicting
 with each other.
 
 For example, if there is an SVG file named `wave.svg` in the same directory as
-this component, it can be rendered using `rx.image` and `rx._x.asset`.
+this component, it can be rendered using `rx.image` and `rx.asset`.
 
 ```python
 class Hello(rx.Component):
     @classmethod
     def create(cls, *children, **props) -> rx.Component:
         props.setdefault("align", "center")
         return rx.hstack(
-            rx.image(src=rx._x.asset("wave.svg"), width="50px", height="50px"),
+            rx.image(src=rx.asset("wave.svg", shared=True), width="50px", height="50px"),
             rx.heading("Hello ", *children),
             **props
         )
@@ -471,4 +469,4 @@ class Hello(rx.Component):
 
 ## Debugging
 
-If you encounter an error while wrapping a component it is recommended to check the Console in the browser developer tools. You can access this by going to inspect element and then clicking on the Console tab on Mac. This is because the Console is where most Javascript errors are logged.
+If you encounter an error while wrapping a component it is recommended to check the Console in the browser developer tools. You can access this by going to inspect element and then clicking on the Console tab on Mac. This is because the Console is where most Javascript errors are logged.