swaits/dioxus
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve CLI docs (#1404)

Browse Source 
* Improve CLI docs

* Fixed all the typos (hopefully).
* Improved the bad English. This encompasses grammar, vocabulary, generally awkward phrases, etc. The result is easier to read and understand, and in some cases shorter.
* Made some formatting improvements. This includes making formatting more consistent, but I changed some of it to be better, at least in my opinion.
* Removed certain unnecessities, the biggest one being the commands documentation. I think this is unnecessary because of the `dx --help` command. It also needs to be updated every time a command gets added/updated/removed. It doesn't really provide much extra insight than `dx --help`.
* Improved plugin documentation. I added a warning to ignore all of it, which is ironic, but the fact is that plugins are probably going to change. But by the time I learned that, I already made some changes to the plugin docs. This includes a better guide on how to get started (although still bad since the plugin system is too messy), and some general changes like the aforementioned English or formatting.
* And more. I can't list it all, but I didn't use any destructive changes. The content might be reformatted (to be shorter or easier to understand), but the meaning isn't lost.

* Fix grammar in packages/cli/docs/src/creating.md

Co-authored-by: Evan Simkowitz <esimkowitz@users.noreply.github.com>

* Update README.md

* Change config example

---------

Co-authored-by: Evan Simkowitz <esimkowitz@users.noreply.github.com>
This commit is contained in:
LeonardandEvan Simkowitz authored and GitHub committed 2023-09-02 17:59:20 -05:00
1 parent a0d1e5de3a
commit 94f76946fc
20 files changed
+308 -488
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

packages/cli/docs/src/configure.md
+85 -96
View File
@@ -1,166 +1,155 @@
# Configure Project
This chapter will teach you how to configure the CLI with the `Dioxus.toml` file.
There's an [example](#config-example) which has comments to describe individual keys.
You can copy that or view this documentation for a more complete learning experience.
This chapter will introduce you to how to configure the CLI with your `Dioxus.toml` file
Be aware that if the config file is present in the folder, some fields must be filled out, or the CLI tool will abort. The mandatory [table headers](https://toml.io/en/v1.0.0#table) and keys will have a '✍' sign beside it.
"🔒" indicates a mandatory item. Some headers are mandatory, but none of the keys inside them are. It might look weird, but it's normal. Simply don't include any keys.
## Structure
The CLI uses a `Dioxus.toml` file in the root of your crate to define some configuration for your `dioxus` project.
Each header has it's TOML form directly under it.
### Application ✍
### Application 🔒
General application confiration:
```
```toml
[application]
# configuration
```
1. ***name*** ✍ - project name & title
2. ***default_platform*** ✍ - which platform target for this project.
Application-wide configuration. Applies to both web and desktop.
1. **name** 🔒 - Project name & title.
```toml
name = "my_project"
```
name = "my-project"
```
2. ***default_platform*** - The platform this project targets
```ß
# current supported platforms: web, desktop
# default: web
2. **default_platform** 🔒 - The platform this project targets
```toml
# Currently supported platforms: web, desktop
default_platform = "web"
```
if you change this to `desktop`, the `dx build` will default building a desktop app
3. ***out_dir*** - The directory to place the build artifacts from `dx build` or `dx service` into. This is also where the `assets` directory will be copied to
```
3. **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.
```toml
out_dir = "dist"
```
4. ***asset_dir*** - The directory with your static assets. The CLI will automatically copy these assets into the ***out_dir*** after a build/serve.
```
4. **asset_dir** - The directory with your static assets. The CLI will automatically copy these assets into the **out_dir** after a build/serve.
```toml
asset_dir = "public"
```
5. ***sub_package*** - The sub package in the workspace to build by default
```
5. **sub_package** - The sub package in the workspace to build by default.
```toml
sub_package = "my-crate"
```
### Web.App ✍
### Web.App 🔒
Configeration specific to web applications:
```
```toml
[web.app]
# configuration
```
1. ***title*** - The title of the web page
```
Web-specific configuration.
1. **title** - The title of the web page.
```toml
# HTML title tag content
title = "dioxus app | ⛺"
```
2. ***base_path*** - The base path to build the appliation 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.
title = "project_name"
```
2. **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.
```toml
# 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"
```
### Web.Watcher ✍
Configeration related to the development server:
```
```toml
[web.watcher]
# configuration
```
1. ***reload_html*** - If this is true, the cli will rebuild the index.html file every time the application is rebuilt
```
Development server configuration.
1. **reload_html** - If this is true, the cli will rebuild the index.html file every time the application is rebuilt
```toml
reload_html = true
```
2. ***watch_path*** - The files & directories to moniter for changes
```
2. **watch_path** - The files & directories to monitor for changes
```toml
watch_path = ["src", "public"]
```
3. ***index_on_404*** - If enabled, Dioxus CLI will serve the root page when a route is not found. *This is needed when serving an application that uses the router*
```
3. **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.
```toml
index_on_404 = true
```
### Web.Resource ✍
### Web.Resource 🔒
Configeration related to static resources your application uses:
```
```toml
[web.resource]
# configuration
```
1. ***style*** - The styles (`.css` files) to include in your application
```
Static resource configuration.
1. **style** - CSS files to include in your application.
```toml
style = [
# include from public_dir.
# Include from public_dir.
"./assets/style.css",
# or some asset from online cdn.
# Or some asset from online cdn.
"https://cdn.jsdelivr.net/npm/bootstrap/dist/css/bootstrap.css"
]
```
2. ***script*** - The additional scripts (`.js` files) to include in your application
```
style = [
# include from public_dir.
"./assets/index.js",
# or some asset from online cdn.
2. **script** - JavaScript files to include in your application.
```toml
script = [
# Include from asset_dir.
"./public/index.js",
# Or from an online CDN.
"https://cdn.jsdelivr.net/npm/bootstrap/dist/js/bootstrap.js"
]
```
### Web.Resource.Dev ✍
### Web.Resource.Dev 🔒
Configeration related to static resources your application uses in development:
```
```toml
[web.resource.dev]
# configuration
```
1. ***style*** - The styles (`.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"
]
```
2. ***script*** - The additional scripts (`.js` files) to include in your application
```
style = [
# include from public_dir.
"./assets/index.js",
# or some asset from online cdn.
"https://cdn.jsdelivr.net/npm/bootstrap/dist/js/bootstrap.js"
]
```
This is the same as [`[web.resource]`](#webresource-), 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.
### Web.Proxy
Configeration related to any proxies your application requires durring development. Proxies will forward requests to a new service
```
```toml
[[web.proxy]]
# configuration
```
1. ***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 404
```
Configuration related to any proxies your application requires during development. Proxies will forward requests to a new service.
1. **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 404
```toml
backend = "http://localhost:8000/api/"
```
This 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 not currently supported).
This 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).
## Config example
This includes all fields, mandatory or not.
```toml
[application]
# App (Project) Name
name = "{{project-name}}"
# App name
name = "project_name"
# The Dioxus platform to default to
default_platform = "web"
@@ -168,23 +157,23 @@ default_platform = "web"
# `build` & `serve` output path
out_dir = "dist"
# the static resource path
# The static resource path
asset_dir = "public"
[web.app]
# HTML title tag content
title = "dioxus | ⛺"
title = "project_name"
[web.watcher]
# when watcher is triggered, regenerate the `index.html`
# When watcher is triggered, regenerate the `index.html`
reload_html = true
# which files or dirs will be monitored
# Which files or dirs will be monitored
watch_path = ["src", "public"]
# include `assets` in web platform
# Include style or script assets
[web.resource]
# CSS style file
@@ -195,12 +184,12 @@ script = []
[web.resource.dev]
# serve: [dev-server] only
# Same as [web.resource], but for development servers
# CSS style file
style = []
# Javascript code file
# JavaScript files
script = []
[[web.proxy]]