Assets docs (#1037)

Author: diegoimbert

changelog/2025-07-10-assets/index.md

@@ -0,0 +1,18 @@
+---
+slug: assets
+version: v1.505.0
+title: Assets
+tags: ['assets', 'storage', 'scripts', 'flows']
+description: Visualize your data flow and automatically track where your assets are used
+features:
+  - Assets are automatically parsed from your code
+  - Read / Write mode is infered from code context
+  - Add S3 file assets easily through the editor bar
+  - Flow graph displays asset nodes as input or output depending on the infered read / write mode
+  - You can manually select the Read / Write mode for an asset when it is ambiguous in the code
+  - Passing a resource or an s3 file object as input of a flow will display it as an input asset in the run preview
+  - Assets page to see where your assets are used
+  - Explore database / S3 Object Preview button 
+  - Unified URI syntax (res://path/to/res, s3://storage/path/to/file.csv, etc)
+docs: /docs/core_concepts/assets
+---

docs/core_concepts/52_assets/asset_nodes.png

@@ -0,0 +1,65 @@
+# Assets
+
+Windmill auto detects when you reference assets directly in your code. Assets are referenced with URIs and include:
+
+- S3 Objects : s3://storage/path/to/file.csv
+- Resources : res://path/to/resource
+- Variables : var://path/to/variable
+
+![Assets in script editor](./assets_in_script_editor.png 'Assets in script editor')
+
+As of writing this, assets are supported for the following languages:
+
+- Python
+- JavaScript / TypeScript
+- DuckDB
+
+When the asset is a database resource or an S3 file, an explore button will appear next to the asset.
+
+Read / Write mode is infered from code context.
+For example, a `COPY (...) TO file` statement is always `Write`.
+Sometimes the Read / Write mode cannot be inferred, in which case you are able to manually select it.
+
+You can use the Add Resource / Variable / S3 Object buttons in the editor bar for convenience :
+
+<video
+	className="border-2 rounded-lg object-cover w-full h-full dark:border-gray-800"
+	autoPlay
+	controls
+	id="main-video"
+	src="/videos/assets_demo.mp4"
+/>
+<br />
+
+The python and Typescript/Javascript clients now support the new URI syntax :
+
+```python
+wmill.get_resource('res://path/to/resource')
+wmill.get_variable('var://path/to/variable')
+wmill.load_s3_file('s3://storage/path/to/file.csv')
+
+# Not using the URI syntax still works for back-compatibility,
+# and is detected as an asset
+wmill.load_s3_file('storage/path/to/file.csv')
+```
+
+## Asset nodes in flows
+
+In flows, your assets will show up as asset nodes, making data flow easy to visualize :
+
+![Asset nodes](./asset_nodes.png 'Asset nodes')
+
+The Read/Write mode is used to show the asset as an input or output node.
+
+When running a flow and passing an asset as an input, it will appear as an input of the flow in the preview graph :
+
+![Flow input assets](./flow_input_assets.png 'Flow input assets')
+
+## Tracking where your assets are used
+
+Assets are stored in the database upon script / flow deployment.
+You can see a list of all assets used in your workspace by going to the Assets tab in the sidebar.
+
+Clicking on the `usages` link will show the list of scripts and flows that use the asset.
+
+![Assets page](./assets_page.png 'Assets page')

docs/core_concepts/52_assets/assets_in_script_editor.png

@@ -217,6 +217,11 @@ On top of its editors to build endpoints, flows and apps, Windmill comes with a
 		description="Have AI complete code on Windmill."
 		href="/docs/core_concepts/ai_generation"
 	/>
+	<DocCard
+		title="Assets"
+		description="Visualize your data flow and automatically track where your assets are used"
+		href="/docs/core_concepts/assets"
+	/>
 </div>
 
 ## Hosting & advanced

docs/core_concepts/52_assets/assets_page.png

@@ -251,7 +251,7 @@ const sidebars = {
 							label: 'Engine benchmarks',
 							link: {
 								type: 'doc',
-								id: 'misc/benchmarks/competitors/results/index',
+								id: 'misc/benchmarks/competitors/results/index'
 							},
 							items: [
 								{
@@ -381,6 +381,7 @@ const sidebars = {
 				'core_concepts/collaboration/index',
 				'core_concepts/ai_generation/index',
 				'core_concepts/workspace_settings/index',
+				'core_concepts/assets/index',
 				{
 					type: 'category',
 					label: 'Integrations',
@@ -858,7 +859,7 @@ const sidebars = {
 						'apps/app_configuration_settings/components_groups',
 						'apps/react_components',
 						'apps/default_app/index',
-						'apps/app_e-commerce',
+						'apps/app_e-commerce'
 					],
 
 					collapsed: true