tauri-apps / tauri-docs

The source for all Tauri project documentation.

Welcome to the home for Tauri 2.0 documentation - we're excited to have you! ✨

This repo is used to build the docs for the prerelease version of Tauri 2.0 at https://beta.tauri.app.

Get Involved

• Join us on Discord in the #docs channel to ask any questions or give feedback
• Check out the Tauri 2.0 Documentation Roadmap and see if there's anything you'd like to get involved in
• Read the contributing guidelines to learn how to get up and running

Partners

For the complete list of sponsors please visit our website and Open Collective.

License

MIT License

Copyright (c) 2020-2023 Tauri Programme within The Commons Conservancy

tauri-docs's Issues

Add the GitHub extension instructions

This needs to be extended:
https://tauri.studio/docs/development/publishing

with information about this:
https://github.com/tauri-apps/tauri-action

especially notable: you can just ship an app that has a dist (no tauri integration)

Pages from tauri.studio

Security, book, partners and governance should also be moved (and updated) into the docs.

[docs] Missing example for execute API

I am searching for documentation / example of the execute API.

[docs] Supported windows versions?

Hi there,

I've just tried to build my first app via tauri.

I've used a VM with Windows 7 and installed all the necessary tools (uff!).

Now I did npm run build, tauri build, it exited without any errors and gave me a .exe. Hooray!

However, at startup I see this error:

Which made me think: Well, maybe you guys support Windows 10 only?
I couldn't find anything in the docs about supported versions.

Btw: I was able to execute the .exe on a Win10 box, but I only see a white screen there. That's a different issue, most likely I made a mistake somewhere.

Linux build runs perfectly.
Thank you for creating tauri. :)

Staging Site

It would be good to put this up on a staging site so that we can get some members of the team to review it. @khionu / @nklayman - would you be up to throwing this up on now.sh or some free service like that?

@jbolda - maybe an action would be good too.

Thoughts?

[docs] npm vs Yarn confusion and onboarding

https://github.com/tauri-apps/tauri/wiki/04.-MS-Windows-Setup

The documentation makes it sound like tauri cannot function without Yarn, and that npm should not be used, which is completely backwards to everything in the Node.js ecosystem. Node ships with npm and only a small minority of projects use Yarn (let alone require it).

Further, for onboarding new users the ideal scenario would be:

1. Install Node.js and npm
2. npm install -g @tauri/cli
3. tauri my-app-name
4. cd my-app-name && npm start

But my expectations are that it at least be:

1. Install Node.js and npm
2. npm init -y
3. npm install --save-dev tauri
4. Edit your package.json to point the main to index.html
5. Create an index.html
6. npx tauri .

Improve configuration docs

• Have a better way to show JSON props for tauri.conf.json, https://tauri.netlify.app/docs/config can be cleaner;
• Explain Cargo.toml properties.

[docs] Document Windows workaround for issue #212

Issue tauri-apps/tauri#212 is still a problem during windows development,
This is only a problem when devPath in tauri.config.json is a url, and not a static folder.

Since this is an issue upstream, there is little we can do but wait for the issue to be solved in web-view.

An easy work around is adding the following code in main.js or the equivalent file:

if (!window.tauri) {
  require('../src-tauri/tauri.js') // change this path as needed
}

Maybe this should be added to the docs?

Improve API/CLI documentation

Make the whole page cleaner.

Rework content in a user-friendly way

Right now, the website only contains Docusaurus placeholders and raw ideas that need to be refined to be decent.

What needs to be displayed (unordered list):

• reasons to use Tauri;
• more about Tauri, philosophy (details about what matters most for us, like security);
• usage/setup;
• examples/recipes;
• API, both Rust and JS public interface;
• showcase, the awesome community made projects;
• sponsors & donations;
• useful links for community (GitHub, Twitter, Discord, Dev.to, Open Collective, Crowdin).

i18n Workaround

Context

Docusaurus V2 doesn't support i18n yet (see facebook/docusaurus#2651).
The problem is that we're getting more and more non-English users interested in using Tauri and since automatic translation tools are limited, we need to provide a workaround to translate the most important parts of the documentation:

Landing / roadmap (pages/index.js)
What is tauri (docs/about/intro.md)
Security (docs/about/security.md)
Governance (docs/about/governance.md)
Getting started

• introduction (docs/getting-started/intro.md)
• setups (docs/getting-started/setup-*.md)

Usage

• intro (docs/usage/intro.md)
• development (docs/usage/development/*.md)
• patterns (docs/usage/patterns/*.md)
• recipes (docs/usage/recipes/**/*.md)
• loading modes (docs/usage/modes.md)

In addition, we'll need to translate the sidebar, table of content, page navigation and page titles.

Specifications

We're going to generate a whole docs website for each supported languages. Each website will live under a different subdomain.

We should provide a dropdown in the header, which involves "swizzling" the header component.
On dropdown value change, we change the current subdomain.

Add Rust debugging instructions

Is your feature request related to a problem? Please describe.
A debugger cannot translate bundled js back to source files. The 'debug' section of the website only describes how to debug via print statements. However, I think tauri could gain more mainstream popularity if users were able to use a debugger on both the rust code and the JS code. (The rust code is easy to attach a debugger already)

Describe the solution you'd like
The packager/bundler (I believe this is https://github.com/tauri-apps/tauri-inliner) should optionally generate a sourcemap. This will allow debuggers to attach to the webview and allow users to step through their JS code.

Here are the sourcemap options https://www.npmjs.com/package/uglify-js#source-map-options

var result = UglifyJS.minify({"file1.js": "var a = function() {};"}, {
    sourceMap: {
        filename: "out.js",
        url: "out.js.map"
    }
});

I will test this out myself in the next few days.

Public API

[This issue content will be updated, it's currently used for writing specifications about our goal]

Rust

Generate the crates documentation (rustdoc) and use the transformation tool (I called it "rustdocusaurus", I was inspired) to extract crates docs and save them into Docusaurus.

JS/TS

For now, the only JS public API involves the JS/Rust bridge which is pretty simple. We'll need to automate the way to extract the information to store them into Docusaurus.

Bad Crowdin CLI behaviour

It looks like Crowdin has been working on a new version of its API; Docusaurus' commands to upload/download translations are broken.

We need to spend a moment to understand what's going wrong here.

Error with build Rust example

Comand : cargo make run
I get the error:

error: failed to run custom build command for `yew v0.17.2`
--- stderr
thread 'main' panicked at 'Yew does not allow the `web_sys` and `std_web` cargo features to be used simultaneously', /home/euuki/.cargo/registry/src/github.com-1ecc6299db9ec823/yew-0.17.2/build.rs:7:9
stack backtrace:
   0:     0x5611b1046d05 - backtrace::backtrace::libunwind::trace::h396c07d2071b43af
                               at /cargo/registry/src/github.com-1ecc6299db9ec823/backtrace-0.3.46/src/backtrace/libunwind.rs:86
   1:     0x5611b1046d05 - backtrace::backtrace::trace_unsynchronized::h7aa0e4bb23d9c158
                               at /cargo/registry/src/github.com-1ecc6299db9ec823/backtrace-0.3.46/src/backtrace/mod.rs:66
   2:     0x5611b1046d05 - std::sys_common::backtrace::_print_fmt::hd15ac5d4adcd355b
                               at src/libstd/sys_common/backtrace.rs:78
   3:     0x5611b1046d05 - <std::sys_common::backtrace::_print::DisplayBacktrace as core::fmt::Display>::fmt::hec5354be8ccc3ecc
                               at src/libstd/sys_common/backtrace.rs:59
   4:     0x5611b1063b5c - core::fmt::write::h3d34909eeb4f225b
                               at src/libcore/fmt/mod.rs:1076
   5:     0x5611b10454b3 - std::io::Write::write_fmt::h1da287b3de55ed16
                               at src/libstd/io/mod.rs:1537
   6:     0x5611b1049210 - std::sys_common::backtrace::_print::h4d206838e1ace354
                               at src/libstd/sys_common/backtrace.rs:62
   7:     0x5611b1049210 - std::sys_common::backtrace::print::h1f778e9940ee5977
                               at src/libstd/sys_common/backtrace.rs:49
   8:     0x5611b1049210 - std::panicking::default_hook::{{closure}}::h704403a56cbf5783
                               at src/libstd/panicking.rs:198
   9:     0x5611b1048f5c - std::panicking::default_hook::ha4567a10dec4ef8d
                               at src/libstd/panicking.rs:218
  10:     0x5611b10497f7 - std::panicking::rust_panic_with_hook::h88a1f16ec8a7bb20
                               at src/libstd/panicking.rs:486
  11:     0x5611b1041085 - std::panicking::begin_panic::h3598f0db20e8a237
                               at /rustc/5c1f21c3b82297671ad3ae1e8c942d2ca92e84f2/src/libstd/panicking.rs:410
  12:     0x5611b10414f5 - build_script_build::main::h85370e4dcdf6f937
                               at /home/euuki/.cargo/registry/src/github.com-1ecc6299db9ec823/yew-0.17.2/build.rs:7
  13:     0x5611b1040cab - std::rt::lang_start::{{closure}}::ha9c6bfcd5e96c3b2
                               at /rustc/5c1f21c3b82297671ad3ae1e8c942d2ca92e84f2/src/libstd/rt.rs:67
  14:     0x5611b1049bc8 - std::rt::lang_start_internal::{{closure}}::h6d21eebfa4beaf70
                               at src/libstd/rt.rs:52
  15:     0x5611b1049bc8 - std::panicking::try::do_call::h560a27b87db38b9c
                               at src/libstd/panicking.rs:297
  16:     0x5611b1049bc8 - std::panicking::try::h453d4afd696011f9
                               at src/libstd/panicking.rs:274
  17:     0x5611b1049bc8 - std::panic::catch_unwind::h211d02671f23030f
                               at src/libstd/panic.rs:394
  18:     0x5611b1049bc8 - std::rt::lang_start_internal::h464df2bbf46c7e7c
                               at src/libstd/rt.rs:51
  19:     0x5611b1040c87 - std::rt::lang_start::heafefdaace759a1b
                               at /rustc/5c1f21c3b82297671ad3ae1e8c942d2ca92e84f2/src/libstd/rt.rs:67
  20:     0x5611b10415fa - main
  21:     0x7f3f3558b0b3 - __libc_start_main
  22:     0x5611b104017e - _start
  23:                0x0 - <unknown>

warning: build failed, waiting for other jobs to finish...
error: build failed
error: build failed
[cargo-make] ERROR - Error while executing command, exit code: 101
[cargo-make] WARN - Build Failed.

I try build example with clear rust
With node Work 👍

$ yarn init
$ yarn add tauri
$  yarn tauri init
$ mkdir example_app/dist
$ touch example_app/dist/index.html (And some simple html and css code line)
$ yarn tauri build --debug

Examples as so no clear. I want build app with backend rust and frontend with rust(this will the best). If I couldn't frontend rust that how other ? What is my frontend part what backend.
In my opinion is needed one very clear tutorial how build app from zero to debug in ONE techonologes (best in Rust :) ) For me on the web page is no clear https://tauri.studio/docs/development/integration
How add frontend filess and connect with src-tauri.
But probably i do some wrong.
In other side very good project and i'm hopefully that will be grows.

Tauri showcase badges & moderation notice

Since Tauri's major concern is about security, we'll provide audits to the projects registered in the showcase for a fee to our OpenCollective.
Those projects will get a badge (displayed in the showcase) as a gage of security:

Tauri's special focus projects (like guijs) will get another badge, like a star (to confirm).

We should also add a notice to let the community know we won't accept illegal/explicit content in the showcase.

Mask functionality

Add docs about Tauri's Mask definition:

https://github.com/tauri-apps/tauri/blob/dev/maskfile.md

Need to define whether it should appear in "Usage" > "Development" or "API" > "CLI".

Headers overlap on mobile

The headers of every page are stacked on mobile, but they overlap.

Add a "Tips" section

Create this section in the docs (Usage > Tips).
This section is supposed to bring useful clues to consumers so they can learn how to deal with some edge-cases, for example.

Add the following items:

And a word of advice: don't rely on remote resources. That will make your app boot slower and if either the user or remote service are offline then infinitely slower.
It's one of the key differences between an app and a website.
Also remote assets are always a vulnerability.

• Make sure to make your app cross-browser compatible since Webview relies on different browser views;
• tauri-apps/vue-cli-plugin-tauri#14 (comment);

Decision about the docs

@tauri-apps/core

The current docs are using Docusaurus V1.14.4 that supports i18n, a required feature.
Docusaurus V2 is still in alpha stage and does not support i18n yet. But, as Jacob told me, it's the next big thing they'll add in V2.
At first, I was thinking about waiting for V2 to support i18n to eventually switch to it but I changed my mind, as we have been recommended to start with V2 by Docusaurus team members. But since this decision isn't mine alone:

• Should we stick to V1?
  This choice would be the best for stability, already setup.
• Should we switch to V2?
  V2 has many interesting features that V1 will never have (theme switch, better templates customization, plugins and better extensibility [like CSS preprocessors]).

If you need to make a choice by seeing what are the differences between the two versions, here is V1: https://docusaurus.io/en/ and here is V2: https://v2.docusaurus.io/

Waiting for your comments!

Supported web technologies for Webview

Nice suggestion coming from Discord:

Perhaps someone could create a Union of the browsers that are represented by Webview? Something like: https://caniuse.com/#compare=ie+10,ie+11,edge+80,firefox+74,chrome+80

Requires investigation, definitely an important information.

Header height is adjusted between load and load of logo

It's a small, but very discernible adjustment, would be good to ensure the height matches the logo so it doesn't "jump".

Fill the cross-compilation page

From https://github.com/jbolda/finatr/blob/next/.github/workflows/release-tauri-app.yml, add some explanations so people easily understand how to make their own workflow.

Move "website" content in the root directory

The actual structure is what it is because it's been initialized with Docusaurus V1. Nevertheless, Docusaurus V2 lets us move the whole content in the root directory.
Let's move it, for the sake of simplicity.

Better contributor guide & tools

The tauri-apps/tauri#564 issue has put a finger on something else that should be improved: having a a nice contributor guide in order to help people getting started quickly and easily so they can contribute to Tauri codebase.

Add the default Docusaurus "search" functionality

Here's the doc to follow: https://v2.docusaurus.io/docs/search

Fix "Getting started" diagram on mobile

Should be rendered vertically on mobile.

Feature request: anchor links on the api/config page

Currently, the config page only have anchors on the main headings. It would be useful if we could anchor the inner properties aswell (seems like the anchorify class does nothing). I've tried to do it but there's a lot of relative positioning in there, so it needs a rewrite I guess.

Homepage

Layout:

• a hero, I'd like to have a short but awesome animation to explain Tauri to newcomers;
• the most important features, small sentences with illustrations;
• ...?
• the roadmap.

[patterns]: New pattern -> devtool

So, with guijs and theia, we've seen a new pattern begin to emerge, and I think we should start thinking about adding a new pattern page. It is a "lowish-security" pattern, because we are currently shipping shell-script orchestrators in order to be able to kill spawned threads.

Nevertheless, it is a powerful and very useful pattern.

code of conduct

We currently have a code of conduct link in the footer which links to the main repo markdown file page. I assume we want to have the code of conduct translated so this should likely become it's own page. Also, items in the footer are not available for translation so we may need to move the link to a translatable location.

README

We definitely need a README here, to define the scope of this repository and inform devs how to get started with it.

Add install instructions for linux distributions that are not using apt, e.g. arch, fedora, etc

It would be quite useful to add install instructions for other linux distributions as well, because the names of the needed packages are completly different and there are quite a lot of people out there who using stuff that isn't based on debian.

[docs] Electron not FLOSS?

Hi! The comparison table says that Tauri is FLOSS while Electron is not:

https://github.com/tauri-apps/tauri#comparison-between-tauri-1-and-electron-5

There's no further explanation and this is really confusing to me. Electron is licensed under the MIT:

https://github.com/electron/electron/blob/master/LICENSE

MIT is both a Free Software license under the FSF as well as an Open Source license under the OSI. Indeed, it is the license Tauri uses.

Is this a typo, are you using a different definition of "FLOSS" or does Electron have additional licensing terms that do not make it free/libre/open source?

Enable documentation versioning

Sooner or later, we'll need to enable the docs versioning: https://v2.docusaurus.io/docs/versioning/

Since we're not stable yet, I'm unsure this should be done ASAP. But let's keep that in a corner of our heads.

Better information about not using a devserver

https://tauri.studio/docs/usage/development/development

We need to tell people they can use "devPath": "../dist" - if they aren't using their own devserver.

[docs] differences in dev and bundle, running an exec process

Very cool library I just wrote a post looking at similar

Looking at the docs I can't find a difference with dev and bundle for running a bundled binary like:

"build": {
    "distDir": ".",
    "devPath": "http://localhost:3666",
    "beforeDevCommand": "vue ui --headless --port 3666",
    "beforeBuildCommand": "vue ui --headless --port 3666"
  },

The dev works fine but the release hangs, I'm assuming it''s waiting for the server to exit. Do I need to include it as an "externalBinary" instead or run it as a spawned exec process? I'm not Rust savy, more node.js hopefully this isnt a stupid question.

Thanks!

Rust docs publishing automation

Rust API docs should be automatically pushed on Tauri releases.

Tauri license compliance reports

Add a section dedicated to license compliance reports, for both Rust & JS dependencies.

• need to determine whether it should be in "About", "Docs" or "API";
• generate Rust report with cargo about;
• generate JS report (https://www.npmjs.com/package/nlf, https://fossa.com/).

[docs]How the project supports CORS

As the title
And https://github.com/tauri-apps/tauri/blob/7e2854007a/cli/tauri.js/src/template/defaultConfig.ts whether his config description can be added to Wiki

Add a "Troubleshooting" section

Contains all frequently encountered issues and how to solve them.
The most prominent problem solver being:

cargo upgrade
cargo install tauri-bundler --force

need to make sure xcode is installed on MacOS

Need to add this to the docs
xcode-select --install

Retrieve docs from the Wiki

All docs from the current Wiki should be moved to the website. Also, we need to ensure that every links are updated.
Contents may have to be updated, reworked and detailed.

Patterns page

Integrate Mermaid JS into the docs (tip: facebook/docusaurus#1258) so we can reuse the patterns page https://tauri.studio/en/patterns.

Make roadmap more intuitive

Colors explaining a feature state from the roadmap is not explicit enough and not good enough for accessibility.

Since Docusaurus doesn't provide icons font, we need to pick one first.

Global style improvements and layout

The goal is to have a better customization over the default Docusaurus template.

• understand why Rust syntax highlighting is missing.

[building] - turn off panics

While discussing errors, @wusyong recommended this approach:

tauri-apps/tauri#613 (comment)

Basically on release stop errors from propegating (because during reversing this information can be very useful to the attacker).

[profile.release]
panic = "abort"

Recipes/cookbook => "How to"

The "Usage" section refers to the way one can read examples and learn techniques to use in their projects.

The goal is to have human readable (and intuitive) intentions associated to code in those pages.
We can already extract some parts from the existing "Usage" pages and develop them into dedicated pages (so the current content is less condensed and we can take time to explain things clearly).

Depending on the amount of docs we'll have in the end, we may need to create subdirectories to group those "recipes".

Generate and store JS documentation + automation

Just like for the Rust side, the idea is to have the JS API documentation generated and stored automatically as MarkDown.

[docs] Running yarn tauri info before yarn tauri init produces error

// Context from Discord #help

The wiki section 05. Tauri Integration tells you to run yarn tauri info in step 2 and yarn tauri init in step 3. Overall, the implied order of operations leading up to and through step 2 is:

mkdir my-project
cd my-project
yarn init
yarn add tauri
yarn tauri info

This produces the following error: tauri Couldn't find recognize the current folder as a part of a Tauri project.

If I run yarn tauri init before yarn tauri info I get the expected result per the wiki: Operation system...Node.js environment...Rust environment...etc. This would suggest that the correct order of operations is something like:

mkdir my-project
cd my-project
yarn init
yarn add tauri
yarn tarui init        // Inserted
yarn tauri info

At least, that order worked for me, but I don't actually know what the root cause of the error was.