Mirrors/dioxus
2
0
Fork 0
mirror of https://github.com/DioxusLabs/dioxus synced 2025-02-17 06:08:26 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merge pull request #152 from Demonthos/reword-docs

Browse source 
Clean up some wording in the documentation
This commit is contained in:
Jon Kelley 2023-06-28 16:56:19 -07:00 • committed by GitHub
commit deeb714fec
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
8 changed files with 135 additions and 111 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
docs/src/cmd/README.md
View file

@ -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
```

10
docs/src/cmd/build.md
View file

@ -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
```

6
docs/src/cmd/clean.md
View file

@ -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

38
docs/src/cmd/serve.md
View file

@ -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 <EXAMPLE> [default: ""]
--platform <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

25
docs/src/cmd/translate.md
View file

@ -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> Output file, stdout if not present
<OUTPUT> 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
<div>
<h1> Hello World </h1>
@ -40,7 +51,7 @@ set `component` flag will wrap `dioxus rsx` code in a component function.
</div>
```
Translate HTML to Dioxus component code.
Translates into this Dioxus component:
```rust
fn component(cx: Scope) -> Element {

120
docs/src/configure.md
View file

@ -1,83 +1,99 @@
# Configure Project
This chapter will introduce `Dioxus.toml` and anatomize the config 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.
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.
## 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 ✍
General application confiration:
```
[application]
# configuration
```
1. ***name*** ✍ - project name & title
2. ***default_platform*** ✍ - which platform target for this project.
```
# 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"
```
### 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 `<title></title>` 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 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"
```
### 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"]
```
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 ✍
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.
@ -86,7 +102,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.
@ -98,9 +114,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.
@ -109,7 +129,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.
@ -121,9 +141,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/"
```
@ -137,14 +162,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]
@ -154,10 +178,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

29
docs/src/creating.md
View file

@ -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
```
By default, the CLI serve your site at: [`http://127.0.0.1:8080/`](http://127.0.0.1:8080/)

12
docs/src/installation.md
View file

@ -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`.