docs: introducing core concepts

[clearlysid]

I'm still thinking about:

1. what all to cover?
2. to what depth should we cover them?
3. should we provide external links as a "further reading" suggestion?

[netlify[bot]]

✅ Deploy Preview for tauri-docs-starlight ready!

Name	Link
🔨 Latest commit	284eda6bdbd690318cd666d6650e95ad2817e656
🔍 Latest deploy log	https://app.netlify.com/sites/tauri-docs-starlight/deploys/64f320229ea3ef00077bd2d0
😎 Deploy Preview	https://deploy-preview-1456--tauri-docs-starlight.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[lorenzolewis]

This is awesome! Thank you very much!

To answer your questions:

what all to cover?

I'd also cover:

• SSG: What is it? Why is it the only Tauri supports? (@simonhyll can you clarify if this is the ONLY thing that Tauri supports? Or is this just what's preferred over SPA?)
• SPA: Why is it nice to have?
• SSR: What is it? Why does Tauri NOT support it?

to what depth should we cover them?

I would reference https://diataxis.fr/explanation/ as it gives some really good pointers on this and it's the framework we're basing our docs off of

should we provide external links as a "further reading" suggestion?

Absolutely! I really like the level of detail you have right now and I think a "you can learn more at [insert link here]" would be amazing.

---

A few bits of feedback from a quick overview, but I'm sure @simonhyll would have some more notes on the content:

• I'd recommend moving this into https://github.com/tauri-apps/tauri-docs/tree/next/src/content/docs/blog as a blog post.
  • Anytime we're talking about "Concepts" then I'd love to start covering them in blog posts.
  • This also lets us more clearly highlight that this information is accurate as of a certain point in time.
  • It also lets us highlight awesome contributors like yourself as community contributors ;)
• I'd link out to this page we're getting ready to merge in to guide the reader on how to set up Tauri correctly for their frontend framework: https://github.com/tauri-apps/tauri-docs/blob/74f1ca2fa276506f10551c7f68a88799937f3124/src/content/docs/2/guide/frontend/index.mdx

After some of that is in then I'll jump in with a content review to help with the phrasing if you'd like, then we'll ask the team for a technical review to get it on through 🥳

[simonhyll]

• SSG as in Static Site Generation is the only format Tauri supports. This simply means that Tauri doesn't officially support generating new HTML/CSS/JS etc at runtime. You build your frontend at compile time and serve it as a folder for Tauri to ingest. This is opposed by SSR, where you instead at runtime generate the HTML/CSS/JS. This is not opposed to the concept of SPA, which is its own thing and more related to navigation history and DOM manipulation and is therefore a technique for handling the frontend itself, not a method of serving the frontend, if that makes sense.
• SPA is nice to have because it gets rid of all white flashes of page reloading in addition to loading faster and saving the environment by minimising wasteful CPU usage on making a complete re-render of the page instead of just loading the bare minimum of assets (looking at you Starlight)
• SSR is not supported because SSR is per definition a new backend. When using Tauri you are choosing to let Tauri be your backend. By choosing SSR you're switching out the Tauri backend with your own server implementation. Tauri doesn't support Python, Node.js or anything else officially. To run something like a Express or Next.js server you'd need to bake a Node.js runtime into your binary, which effectively turns your amazing Tauri app into effectively being an Electron app but with worse support for javascript. To do things the Tauri way, you have to let Tauri be your backend, which means you have to rely on SSG. There is an effort being made to support something like Actix/Axum in the Rust end combined with a custom uri scheme, so somewhere there is a dream about making some manner of SSR possible, but any solution that relies on e.g. Node.js will never be officially supported since we're not trying to recreate Electron.

As for where this information should be put I would love for it to be covered in the Core Concepts to some degree, but maybe at a more glossary level so people just get a brief understanding of what it's about, same as we might do for the concepts of Frontend vs Backend. Understanding SSG/SSR/SPA I would call core concepts. However, I think longer discussions as to what they entail exactly, pros and cons and such are better covered in a blog post. So I would vote for just brief titles about them with short descriptions as to what they entail, maybe mention why Tauri does/doesn't support them, then make a longer blog post (or one each) where you can really go in-depth as to what they are and how they work.

[lorenzolewis]

Btw @clearlysid , open to this PR being in the spirit of glossary level like @simonhyll mentioned or to be the more full-fledged blog post covering all the concepts and "why's", whichever you're most comfortable with

[lorenzolewis]

Hey @clearlysid ! Checking in on this one and seeing if you're still interested in continuing forward with it. No worries on the answer either way and hope all is well 🤗

[clearlysid]

To be honest, I'd be a little worried about diving too deep in the terminology land within the Tauri docs. I think the Glossary angle makes perfect sense.

Imo even better than writing blog posts, we should try to link out to other external source/reading material/videos that explain the concept in detail. That way the docs can remain laser focused on being relevant to Tauri, while still allowing learning opportunities for those who could use it.

If you're aligned, I'll submit a few changes by the weekend and we can hopefully close this next week ✅

[clearlysid]

Actually, now that I think about it. It might even be wiser to simply call this a "Glossary" instead of "Core Concepts".

[simonhyll]

Personally I prefer the term Core Concepts since Glossary feels more like explaining words, and while that's closer to the shorter format we want the spirit of the article is to introduce people to concepts that are critical to know about in order to develop with Tauri, sort of a non-optional to skip section about what people must be aware of in order to understand the rest of the site and project as a whole to facilitate more efficient communication between developers, we we're all on the same page. A glossary could be expanded to just be "people dont know this word, add it to the glossary", but Core Concepts isn't quite that fluid in terms of what should be included.

That's at least how I see it. Plus the term Core Concepts sounds cooler lol.

[clearlysid]

Thanks for the feedback. Please expect an updated draft from me by this weekend 🙌

[lorenzolewis]

Thanks @clearlysid ! I also think that once we see some more of the content then it's a lot easier for us to figure out the right place to slot it and to label it as.