search

rustwasm / book

The Rust and WebAssembly Book
https://rustwasm.github.io/docs/book/
MIT License
1.73k stars 208 forks source link

Documenting rustwasm without npm #150

Open ApoorvaJ opened 5 years ago

ApoorvaJ commented 5 years ago

Describe what about it does not make sense

The docs are currently unclear about how to use rustwasm without npm.

I read through the docs multiple times and came out with the vague impression that usage without NodeJS is currently impossible. Someone correcting me on Twitter, and a circuitous search through Reddit finally led me to the solution.

There are the following problems here:

  1. There are two books A and B. There is a lot of overlap between the two books and they are hosted on the same domain. This is confusing to the point where I didn't realize for two days that there are two books on the website. The latter book isn't even linked from the home page.
  2. The first book never mentions (as far as I know) that building without npm is possible. This should be clearly stated, especially when so many people are working on servers in Rust.
  3. The second book also doesn't mention this clearly, but it does contain the --no-modules section that achieves what we want.

How could we improve

  1. Combine the two books into one, or at least make them mutually exclusive in terms of information contained.
  2. If two distinct books are kept, then link them both prominently from the home page.
  3. Make it obvious wherever applicable how to build without npm. Also discuss the --no-typescript option prominently.
Pauan commented 5 years ago

I generally agree with what you said, however:

especially when so many people are working on servers in Rust.

Why do you say that?

npm is not only about the server: npm is a general purpose JavaScript package manager, and many npm packages are designed for the browser (and they won't even work on the server).

npm is used just as much by browser developers as it is by server developers. It is the de-facto package manager for the entire JavaScript community.

So even if you plan to use WebAssembly only in the browser, you'll still likely need npm (and Webpack).

alexcrichton commented 5 years ago

Thanks for the report @ApoorvaJ! I was inspired by this to give a fresh review to some wasm-bindgen docs (https://github.com/rustwasm/wasm-bindgen/pull/1285), and we've also had a proposal to deploy all the books into one location rather than across a few to ensure they're appropriately cross-linked and discoverable.

In any case this is definitely something where we want to make sure the intro docs all leave the right impression!