This chapter will teach you how to configure the CLI with the
Dioxus.toml file.There's an example which has comments to describe individual keys.You can copy that or view this documentation for a more complete learning experience.
"🔒" indicates a mandatory item.Some headers are mandatory, but none of the keys inside them are.In that case, you only need to include the header, but no keys.It might look weird, but it's normal.
Each header has its TOML form directly under it.
Application-wide configuration. Applies to both web and desktop.
- name 🔒 - Project name & title.
name = "my_project"
- default_platform 🔒 - The platform this project targets
# Currently supported platforms: web, desktop default_platform = "web"
- out_dir - The directory to place the build artifacts from dx build or dx serve into. This is also where the assets directory will be copied into.
out_dir = "dist"
- asset_dir - The directory with your static assets. The CLI will automatically copy these assets into the out_dir after a build/serve.
asset_dir = "public"
- sub_package - The sub package in the workspace to build by default.
sub_package = "my-crate"
- title - The title of the web page.
# HTML title tag content title = "project_name"
- base_path - The base path to build the application for serving at. This can be useful when serving your application in a subdirectory under a domain. For example, when building a site to be served on GitHub Pages.
# The application will be served at domain.com/my_application/, so we need to modify the base_path to the path where the application will be served base_path = "my_application"
Development server configuration.
reload_html - If this is true, the cli will rebuild the index.html file every time the application is rebuilt
reload_html = true
watch_path - The files & directories to monitor for changes
watch_path = ["src", "public"]
index_on_404 - If enabled, Dioxus will serve the root page when a route is not found.This is needed when serving an application that uses the router.However, when serving your app using something else than Dioxus (e.g. GitHub Pages), you will have to check how to configure it on that platform.In GitHub Pages, you can make a copy of index.html named 404.html in the same directory.
index_on_404 = true
Static resource configuration.
style - CSS files to include in your application.
style = [ # Include from public_dir. "./assets/style.css", # Or some asset from online cdn. "https://cdn.jsdelivr.net/npm/bootstrap/dist/css/bootstrap.css" ]
script = [ # Include from asset_dir. "./public/index.js", # Or from an online CDN. "https://cdn.jsdelivr.net/npm/bootstrap/dist/js/bootstrap.js" ]
This is the same as
[web.resource], but it only works in development servers.For example, if you want to include a file in a dx serve server, but not a dx serve --release server, put it here.
Configuration related to any proxies your application requires during development. Proxies will forward requests to a new service.
- backend - The URL to the server to proxy. The CLI will forward any requests under the backend relative route to the backend instead of returning 404This will cause any requests made to the dev server with prefix /api/ to be redirected to the backend server at http://localhost:8000. The path and query parameters will be passed on as-is (path rewriting is currently not supported).
backend = "http://localhost:8000/api/"
This includes all fields, mandatory or not.