Development experience improvements for workspaces

[orf]

Hello, I really like Dioxus, but there are a number of small, niggly issues that I keep bumping against. I know you're iterating fast, but I wanted to collect my experiences adding Dioxus to an existing project here.

Despite these issues below, Dioxus fucking rocks 🚀. It's fantastic, honestly. Once set up it is so simple to build amazing things, I really love it. But I wanted to highlight some specific issues I encountered when setting up a new project that might be confusing to those who are new to Dioxus, or are returning after not having used it in a while:

• The search result component in the docs is quite confusing: perhaps we should include the page subtitle?
• Search results in docs pull up results for unsupported versions of Dioxus
• dx new should include some specific descriptions of the different template types, the names are not super descriptive.
• The latest tailwind docs have an incorrect npx command: it should be npx tailwindcss -i ./input.css -o ./assets/tailwind.css --watch (the ./assets/ part is changed from ./public/)
• Workspaces are still confusing: every project I've used Dioxus with has been in the context of a workspace - I want to add a web/native frontend to a project that includes a CLI and/or a library
  • The workspace template should be used for a new workspace, not if you're in a existing workspace
  • Custom build profiles don't seem to work: WASM optimizations need to be set on the release profile, not a specific wasm-release profile
  • You apparently need to cd into a specific package directory to run dx serve, but it seems to work without

Full story

The first issue is that the docs say 0.6.0 is an alpha version, but 0.6.0 seems to be out? It came out very recently, but it's confusing.

I saw that there is a new workspace template (this is fantastic!), but after running dx new I'm greeted with the following list of options. The problem is that I've got no idea what jumpstart is - I can figure out what "barebones" and "workspace" likely is, but what's jumpstart? Including some descriptions on these would be good.

I selected "workspace" because, well, I'm in a workspace. But this added the dioxus installation as a new workspace under my current workspace! The crates are spread out, which is quite nice.

Ok, no problem. I can merge the crates into my workspace. All the docs say I need to cd into the workspace member directory then run dx serve - but it's not clear why. When working in a workspace this is kind of annoying.

Ok, so let's try to use the -p flag instead:

$ dx serve -p web
   0.418s ERROR Loading crate
   0.418s ERROR Found package NodeIndex(499)
   0.418s ERROR failed to read `dioxus/settings.toml` config file
   0.418s ERROR Autodetecting platform from feature asset
...
   0.419s ERROR Multiple platforms are enabled. Please specify a platform with `--platform <platform>` or set a single default platform using a cargo feature.
   0.419s ERROR   - (MacOS, "desktop")
   0.419s ERROR   - (Web, "web")
   0.420s ERROR err=Other(No platform was specified and could not be auto-detected. Please specify a platform with `--platform <platform>` or set a default platform using a cargo feature.)

Weird - the package has a default feature set, but that's fine. We can run with --platform=web and it works.

But when building it outputs an error despite passing --platform - the error doesn't seem to actually stop the build, but it's confusing:

$ dx build -p web --platform=web
   0. 0s  INFO Building project...
   0.331s ERROR Multiple platforms are enabled. Please specify a platform with `--platform <platform>` or set a single default platform using a cargo feature.
   0.331s ERROR   - (MacOS, "desktop")
   0.331s ERROR   - (Web, "web")
   1.32s  INFO Compiling [  1/214]: build-script-build
   1.32s  INFO Compiling [  3/214]: unicode_ident

Ok. So let's try building with optimizations. The build config docs say to set some pretty standard values for the release profile, but I only want to use them for the WASM build and not for the general workspace build. So I copy them to a wasm-release profile:

[profile.wasm-release]
inherits = "release"
opt-level = "z"
...

and build:

$ dx build -p web --platform=web --profile=wasm-release
   ...
   1.105s  INFO Build completed successfully! 🚀 path="/xxx/target/dx/web/debug/web/public"

Hmm - it built in debug mode? Ok, let's try with --release:

$  dx build -p web --platform=web --profile=wasm-release -r
   ...
   2.213s  INFO Build completed successfully! 🚀 path="/xxx/target/dx/web/release/web/public"

This seems to ignore the --profile argument and just build in release?

Ok, so something is werid. Let's just roll back to a single crate and not use the workspace template. I do this, then after running dx serve -p web I'm immediately greeted with this error:

$ dx serve -p web
...
15:25:16 [cargo] error: Asset at /assets/tailwind.css doesn't exist: No such file or directory (os error 2
  --> crates/web/src/main.rs:21:29
   |
21 | const TAILWIND_CSS: Asset = asset!("/assets/tailwind.css");
   |                             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = note: this error originates in the macro `asset` (in Nightly builds, run with -Z macro-backtrace for more info

Ok, I know why (I need to run the tailwind daemon or somesuch), but I go to the docs and search for tailwind. the results are relevant, but the actual content is useless:

Ok, so I click the first result for Tailwind and I'm taken to the cookbook page for version 0.4.3?

The second result takes me to the docs for 0.6.0. There it says to run npx tailwindcss -i ./input.css -o ./public/tailwind.css --watch, and add this:

use dioxus::prelude::*;

// Urls are relative to your Cargo.toml file
const TAILWIND_URL: Asset = asset!("/assets/tailwind.css");

But this doesn't seem to work - the watch command writes to public/tailwind.css not assets/tailwind.css.

Changing the command to npx tailwindcss -i ./input.css -o ./assets/tailwind.css --watch works.

[DogeDark]

Firstly, issues like this are super helpful, thank you! Including your story and progression through Dioxus provides a different viewpoint that we don't normally have.

The Dioxus website states that 0.6 is alpha because it hasn't been "officially" released from a public standpoint. This will be updated once we publish the release notes on social media.

The release profiles issue seems like a bug. Dioxus by default uses its own profiles for development, but it should be using yours if --profile is provided. If --profile and --release are provided, Dioxus has to choose a default as --release is its own profile.

I don't have any thoughts about the other issues aside from saying that we can definitely improve or fix them!

In case we do need it, would you mind providing us with the OS you are using?

[orf]

Firstly, issues like this are super helpful, thank you! Including your story and progression through Dioxus provides a different viewpoint that we don't normally have.

Thank you ❤️! I was worried it would come across as unhelpful and "not really an issue".

In case we do need it, would you mind providing us with the OS you are using?

Sure! I'm using the latest MacOS, with the latest rust and the latest wasm toolkit (I forget the exact name, sorry!).

The release profiles issue seems like a bug.

I won't be able to work on this until the weekend, but I can try and reproduce it then.

This will be updated once we publish the release notes on social media.

Regarding the 0.6.0 release, that's quite confusing: dx version says I'm on 0.6.0, and the crate is at version 0.6.0.

I'd really try and sync the crate release with the docs release: there is nothing worse than installing something then browsing the docs, only to see that the docs haven't been updated.

The docs become useless in this case: how do I trust the docs match what I'm using? There's a big yellow warning saying it's an alpha version: how does that differ from what I'm using?

So essentially from a new user point of view, there are no docs.

[orf]

And I'd like to add one more step to my journey notes here if you don't mind:

I ended up getting everything running nicely, and I'm working on some server functions.

I need to add a dependency that is only included in the server build, not the WASM build.

The docs don't specify anything about how to achieve this, but I remember finding a way to do this in an older version of Dioxus by using a "server" feature.

So I added a "server" feature and included the dependency based on that. After running "dx serve", the frontend seems to build fine but the cli outputs "server build failed with error 101" a thousand times a second. I stopped for the night there. When I have access to that machine I'll file a separate bug for this.

Overall Dioxus is honestly amazing, but if I could sum up the issues above it would be that the onboarding experience and documentation lack instructions on common paths that developers take - things like:

• how to add a dependency only for your server function
• how to integrate Dioxus in an existing workspace
• how to integrate with tailwind

should be clearly highlighted, searchable and (for the last part) 100% correct.

Otherwise you end up in this hellhole of hard to debug and strange WASM/toolchain errors, and you're not sure if it's you, the docs or Dioxus at fault.

[ealmloff]

I opened some pull requests that fix some of the documentation issues:

• https://github.com/DioxusLabs/docsite/pull/331 adds documentation about managing features for optional dependencies

• https://github.com/DioxusLabs/docsite/pull/338 fixes the tailwind guide