From e244159661e288ace0cf61d9282891b3ebd43b2f Mon Sep 17 00:00:00 2001 From: Evan Almloff Date: Wed, 21 Jun 2023 14:58:03 -0700 Subject: [PATCH 1/2] add missing items to Dioxus.toml documentation --- docs/src/configure.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/src/configure.md b/docs/src/configure.md index 95408580c..30c390033 100644 --- a/docs/src/configure.md +++ b/docs/src/configure.md @@ -24,6 +24,7 @@ We use `toml` to define some info for `dioxus` project. ``` asset_dir = "public" ``` +5. ***sub_package*** - the sub package in the workspace to build ### Application.Tools @@ -58,6 +59,11 @@ Web platform application config: # 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 in a domain. For example when building a site to be served on github pages. + ``` + # The application will be served at domain.com/my_application/ + base_path = "my_application" + ``` ### Web.Watcher @@ -72,6 +78,10 @@ Web platform `dev-server` watcher config: ``` 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* + ``` + index_on_404 = true + ``` ### Web.Resource From b242afc17b4a1d48f5da6f041d7dd3cb39db7205 Mon Sep 17 00:00:00 2001 From: Evan Almloff Date: Wed, 21 Jun 2023 15:42:48 -0700 Subject: [PATCH 2/2] clean up some wording in the documentation --- docs/src/cmd/README.md | 6 +- docs/src/cmd/build.md | 10 ++-- docs/src/cmd/clean.md | 6 +- docs/src/cmd/serve.md | 38 +++++-------- docs/src/cmd/translate.md | 25 +++++--- docs/src/configure.md | 116 +++++++++++++++++++++----------------- docs/src/creating.md | 29 +++++----- docs/src/installation.md | 12 ++-- 8 files changed, 126 insertions(+), 116 deletions(-) diff --git a/docs/src/cmd/README.md b/docs/src/cmd/README.md index c642b475f..dae226577 100644 --- a/docs/src/cmd/README.md +++ b/docs/src/cmd/README.md @@ -2,7 +2,7 @@ In this chapter we will introduce all `dioxus-cli` commands. -> you can also use `dioxus --help` to get cli help info. +> You can also use `dioxus --help` to get cli help info. ``` dioxus @@ -16,11 +16,11 @@ OPTIONS: -v Enable verbose logging SUBCOMMANDS: - build Build the Rust WASM app and all of its assets + build Build the Dioxus application and all of its assets clean Clean output artifacts config Dioxus config file controls create Init a new project for Dioxus help Print this message or the help of the given subcommand(s) serve Build, watch & serve the Rust WASM app and all of its assets - translate Translate some source file into Dioxus code + translate Translate some html file into a Dioxus component ``` \ No newline at end of file diff --git a/docs/src/cmd/build.md b/docs/src/cmd/build.md index e81973f2d..1fb892475 100644 --- a/docs/src/cmd/build.md +++ b/docs/src/cmd/build.md @@ -15,7 +15,7 @@ OPTIONS: --release [default: false] ``` -You can use this command to build project to `out_dir` : +You can use this command to build a project: ``` dioxus build --release @@ -23,14 +23,14 @@ dioxus build --release ## Target platform -Use option `platform` choose build target platform: +Use the `platform` option to choose your target platform: ``` # for desktop project dioxus build --platform desktop ``` -`platform` only supports `desktop` & `web`. +`platform` currently only supports `desktop` & `web`. ``` # for web project @@ -39,9 +39,9 @@ dioxus build --platform web ## Build Example -You can use `--example {name}` to build a example code. +You can use the `example` option to select a example to build: ``` -# build `example/test` code +# build the `test` example dioxus build --exmaple test ``` \ No newline at end of file diff --git a/docs/src/cmd/clean.md b/docs/src/cmd/clean.md index 2f889c1a8..bbb3a132e 100644 --- a/docs/src/cmd/clean.md +++ b/docs/src/cmd/clean.md @@ -1,16 +1,16 @@ # Clean -`dioxus clean` will call `target clean` and remove `out_dir` directory. +`dioxus clean` will clear the build artifacts (the out_dir and the cargo cache) ``` dioxus-clean -Clean output artifacts +Clean build artifacts USAGE: dioxus clean ``` -you can use this command to clean all build cache and the `out_dir` content. +# Example ``` dioxus clean diff --git a/docs/src/cmd/serve.md b/docs/src/cmd/serve.md index dc2d14593..41abf5350 100644 --- a/docs/src/cmd/serve.md +++ b/docs/src/cmd/serve.md @@ -1,6 +1,6 @@ # Serve -The `dioxus serve` can start a dev server (include hot-reload tool) to run the project. +The `dioxus serve` can start a dev server with hot-reloading ``` dioxus-serve @@ -13,53 +13,43 @@ OPTIONS: --example [default: ""] --platform [default: "default_platform"] --release [default: false] + --hot-reload [default: false]ß ``` -You can use this command to build project and start a `dev server` : +You can use this command to build project and start a dev server: ``` dioxus serve ``` -## Target platform - -Use option `platform` choose build target platform: - -``` -# for desktop project -dioxus serve --platform desktop -``` - -`platform` only supports `desktop` & `web`. - -`dev-server` only for `web` project. - -``` -# for web project -dioxus serve --platform web -``` - ## Serve Example -You can use `--example {name}` to start a example code. +You can use the `example` option to serve a example: ``` -# build `example/test` code +# serve the `test` example dioxus serve --exmaple test ``` ## Open Browser -You can add `--open` flag to open system default browser when server startup. +You can add the `--open` option to open system default browser when server startup: ``` dioxus serve --open ``` +## RSX Hot Reloading + +You can add the `--hot-reload` flag to enable [rsx hot reloading](https://dioxuslabs.com/docs/0.3/guide/en/getting_started/hot_reload.html). This will allow you to reload some rsx changes without a full recompile: + +``` +dioxus serve --open +``` ## Cross Origin Policy -use `cross-origin-policy` can change corss-origin header in serverside. +You can add the `cross-origin-policy` option to change cross-origin header to: ``` Cross-Origin-Opener-Policy: same-origin diff --git a/docs/src/cmd/translate.md b/docs/src/cmd/translate.md index 415a88fba..7237e1dcf 100644 --- a/docs/src/cmd/translate.md +++ b/docs/src/cmd/translate.md @@ -1,16 +1,16 @@ # Translate -`dioxus translate` can translate some source file into Dioxus code. +`dioxus translate` can translate some `html` file into a Dioxus compoent ``` dioxus-translate -Translate some source file into Dioxus code +Translate some source file into a Dioxus component USAGE: dioxus translate [OPTIONS] [OUTPUT] ARGS: - Output file, stdout if not present + Output file, defaults to stdout if not present OPTIONS: -c, --component Activate debug mode @@ -19,20 +19,31 @@ OPTIONS: ## Translate HTML to stdout +You can use the `file` option to set path to the `html` file to translate: + ``` dioxus transtale --file ./index.html ``` -## Output in a file +## Output rsx to a file + +You can pass a file to the traslate command to set the path to write the output of the command to: ``` -dioxus translate --component --file ./index.html component.rsx +dioxus translate --file ./index.html component.rsx ``` -set `component` flag will wrap `dioxus rsx` code in a component function. +## Output rsx to a file + +Setting the `component` option will create a compoent from the HTML: + +``` +dioxus translate --file ./index.html --component +``` ## Example +This HTML: ```html

Hello World

@@ -40,7 +51,7 @@ set `component` flag will wrap `dioxus rsx` code in a component function.
``` -Translate HTML to Dioxus component code. +Translates into this Dioxus component: ```rust fn component(cx: Scope) -> Element { diff --git a/docs/src/configure.md b/docs/src/configure.md index 30c390033..25a5a365a 100644 --- a/docs/src/configure.md +++ b/docs/src/configure.md @@ -1,80 +1,78 @@ # Configure Project -This chapter will introduce `Dioxus.toml` and anatomy the config file. +This chapter will introduce you to how to configure the CLI with your `Dioxus.toml` file ## Structure -We use `toml` to define some info for `dioxus` project. +The CLI uses a `Dioxus.toml` file in the root of your crate to define some configuration for your `dioxus` project. ### Application -1. ***name*** - project name & title -2. ***default_platform*** - which platform target for this project. +General application confiration: + +``` +[application] +# configuration +``` + +1. ***name*** - Project name ``` - # current support: web, desktop + name = "my-project" + ``` +2. ***default_platform*** - The platform this project targets + ```ß + # current supported platforms: web, desktop # default: web default_platform = "web" ``` - change this to `desktop`, the `dioxus build & serve` will default build desktop app. -3. ***out_dir*** - which directory to put the output file; use `dioxus build & service`, the output will put at this directory, and the `assets` will be also copy to here. + if you change this to `desktop`, the `dioxus build` will default building a desktop app +3. ***out_dir*** - The directory to place the build artifacts from `dioxus build` or `dioxus service` into. This is also where the `assets` directory will be copied to ``` out_dir = "dist" ``` -4. ***asset_dir*** - which direcotry to put your `static, assets` file, cli will automatic copy all file to `out_dir`, so you can put some resource file in there, like `CSS, JS, Image` file. +4. ***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" ``` -5. ***sub_package*** - the sub package in the workspace to build - -### Application.Tools - -You can combine different tools with `dioxus`. - -1. ***binaryen*** - Use the `binaryen` tooling suite. +5. ***sub_package*** - The sub package in the workspace to build by default ``` - # current support: wasm-opt - # default: web - binaryen = { wasm_opt = true } + sub_package = "my-crate" ``` - Use the `wasm_opt = true` key/pair value to activate optimization with wasm-opt. - When building on `release` profile, Dioxus will run `wasm_opt` with `-Oz` option. -2. ***tailwindcss*** - Use the `tailwindcss` standalone binary to generate a Tailwind CSS bundle file. - ``` - tailwindcss = { input = "main.css", config = "tailwind.config.js" } - ``` - You can set two optional keys : - - input: path of the input CSS file (default value is "public/tailwind.css") - - config: path to the config file for Tailwind (default value is "src/tailwind.config.js") - - When building on `release` profile, Dioxus will run `tailwindcss` with the `--minify` option. - - Note : Dioxus will automatically include the generated tailwind file in the `index.html` ### Web.App -Web platform application config: +Configeration specific to web applications: -1. ***title*** - this value will display on the web page title. like `` tag. +``` +[web.app] +# configuration +``` + +1. ***title*** - The title of the web page ``` # 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 in a domain. For example when building a site to be served on github pages. +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. ``` - # The application will be served at domain.com/my_application/ + # 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 -Web platform `dev-server` watcher config: +Configeration related to the development server: -1. ***reload_html*** - a boolean value; when watcher trigger, regenerate `index.html` file. +``` +[web.watcher] +# configuration +``` + +1. ***reload_html*** - If this is true, the cli will rebuild the index.html file every time the application is rebuilt ``` - # when watcher trigger, regenerate the `index.html` reload_html = true ``` -2. ***watch_path*** - which files & directories will be watcher monitoring. +2. ***watch_path*** - The files & directories to moniter for changes ``` watch_path = ["src", "public"] ``` @@ -85,9 +83,13 @@ Web platform `dev-server` watcher config: ### Web.Resource -Include some `CSS Javascript` resources into html file. +Configeration related to static resources your application uses: +``` +[web.resource] +# configuration +``` -1. ***style*** - include some style(CSS) file into html. +1. ***style*** - The styles (`.css` files) to include in your application ``` style = [ # include from public_dir. @@ -96,7 +98,7 @@ Include some `CSS Javascript` resources into html file. "https://cdn.jsdelivr.net/npm/bootstrap/dist/css/bootstrap.css" ] ``` -2. ***script*** - include some script(JS) file into html. +2. ***script*** - The additional scripts (`.js` files) to include in your application ``` style = [ # include from public_dir. @@ -108,9 +110,13 @@ Include some `CSS Javascript` resources into html file. ### Web.Resource.Dev -Only include resources at `Dev` mode. +Configeration related to static resources your application uses in development: +``` +[web.resource.dev] +# configuration +``` -1. ***style*** - include some style(CSS) file into html. +1. ***style*** - The styles (`.css` files) to include in your application ``` style = [ # include from public_dir. @@ -119,7 +125,7 @@ Only include resources at `Dev` mode. "https://cdn.jsdelivr.net/npm/bootstrap/dist/css/bootstrap.css" ] ``` -2. ***script*** - include some script(JS) file into html. +2. ***script*** - The additional scripts (`.js` files) to include in your application ``` style = [ # include from public_dir. @@ -131,9 +137,14 @@ Only include resources at `Dev` mode. ### Web.Proxy -Proxy requests matching a path to a backend server. +Configeration related to any proxies your application requires durring development. Proxies will forward requests to a new service -1. ***backend*** - the URL to the backend server. +``` +[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 ``` backend = "http://localhost:8000/api/" ``` @@ -147,14 +158,13 @@ Proxy requests matching a path to a backend server. # App (Project) Name name = "{{project-name}}" -# Dioxus App Default Platform -# desktop, web, mobile, ssr +# The Dioxus platform to default to default_platform = "web" -# `build` & `serve` dist path +# `build` & `serve` output path out_dir = "dist" -# resource (public) file folder +# the static resource path asset_dir = "public" [web.app] @@ -164,10 +174,10 @@ title = "dioxus | ⛺" [web.watcher] -# when watcher trigger, regenerate the `index.html` +# when watcher is triggered, regenerate the `index.html` reload_html = true -# which files or dirs will be watcher monitoring +# which files or dirs will be monitored watch_path = ["src", "public"] # include `assets` in web platform diff --git a/docs/src/creating.md b/docs/src/creating.md index fa725a4f7..5bb98fd10 100644 --- a/docs/src/creating.md +++ b/docs/src/creating.md @@ -4,35 +4,36 @@ Once you have the Dioxus CLI tool installed, you can use it to create dioxus pro ## Initializing a default project -The `dioxus create` command will create a new directory containing a project template. +First, run the `dioxus create` command to create a new project ready to be used with Dioxus and the Dioxus CLI: + ``` dioxus create hello-dioxus ``` -It will clone a default template from github template: [DioxusLabs/dioxus-template](https://github.com/DioxusLabs/dioxus-template) - +> It will clone a default template from github template: [DioxusLabs/dioxus-template](https://github.com/DioxusLabs/dioxus-template) > This default template is use for `web` platform application. +> +> You can choose to create your project from a different template by passing the `template` argument: +> ``` +> dioxus init hello-dioxus --template=gh:dioxuslabs/dioxus-template +> ``` -then you can change the current directory in to the project: +Next, move the current directory into your new project: ``` cd hello-dioxus ``` > Make sure `wasm32 target` is installed before running the Web project. +> You can install the wasm target for rust using rustup: +> ``` +> rustup target add wasm32-unknown-unknown +> ``` -now we can create a `dev server` to display the project: +Finally, create serve your project with the Dioxus CLI: ``` dioxus serve ``` -by default, the dioxus dev server will running at: [`http://127.0.0.1:8080/`](http://127.0.0.1:8080/) - -## Initalizing from other repository - -you can assign which repository you want to create: - -``` -dioxus init hello-dioxus --template=gh:dioxuslabs/dioxus-template -``` \ No newline at end of file +By default, the CLI serve your site at: [`http://127.0.0.1:8080/`](http://127.0.0.1:8080/) diff --git a/docs/src/installation.md b/docs/src/installation.md index 7151de1ff..b4326d296 100644 --- a/docs/src/installation.md +++ b/docs/src/installation.md @@ -1,12 +1,10 @@ # Installation -There are multiple ways to install the Dioxus CLI tool. Choose any one of the methods below that best suit your needs. +Choose any one of the methods below to install the Dioxus CLI: -## Install from latest master version +## Install from latest git version -We suggest you use `github master` version to install it now. - -We have not yet released the latest version to `crates.io` +To get the most up to date bug fixes and features of the Dioxus CLI, you can install the development version from git. ``` cargo install --git https://github.com/Dioxuslabs/cli @@ -17,8 +15,8 @@ and install it in Cargo's global binary directory (`~/.cargo/bin/` by default). ## Install from `crates.io` version +The published version of the Dioxus CLI is updated less often, but should be more stable than the git version of the Dioxus CLI. + ``` cargo install dioxus-cli ``` - -Make sure to add the Cargo bin directory to your `PATH`. \ No newline at end of file