Guard hooks are always executed on the server when rendered for the first time

[robin-dongbin]

Description

I don't know if I'm mistaken, but the documentation says that when defined as Client-side only data(), the first time guard() is executed is on the client side. But the reality is that guard() is not executed on the client side when it is first rendered

[brillout]

Are you using pre-rendering? Is it called on the server side or not at all?

[robin-dongbin]

It's called on the server side.

[brillout]

Can you elaborate your use case for wanting it to run on the client-side while using SSR (without pre-rendering)?

(See also #1916 Client-only guard() hook for pre-rendered pages.)

[robin-dongbin]

I tried using it in the SPA.
After looking at #1916 and #1600 I think they're basically expressing what I'm trying to say, and at the moment I think it's a documentation error

[robin-dongbin]

By the way, as a newcomer who has just tried vike, I find vike's documentation to give me a sense of confusion, hard to understand and difficult to find relevant information. Is there a plan to rewrite the documentation for 1.0?

I've used next, remix, nuxt. After researching vike for a few days, I think I like the API design of vike more than the others. At the moment it feels like the documentation is a big problem, and it's very tiring to read. If 1.0 needs more marketing like you said, then I feel the documentation should be completely rewritten before marketing.

[brillout]

I tried using it in the SPA.

I see and, indeed, it's similar to #1916 — closing this as duplicate.

I find vike's documentation to give me a sense of confusion, hard to understand and difficult to find relevant information

Except of adding more content and polishing the current content (fixing English mistakes and make it easier to understand), we actually don't plan to restructure the documentation... Do you think there is a structural problem beyond more (polished) content? Critical honest feedback welcome.

Also, we've been improving the search UX but maybe there is still room for improvement.

[robin-dongbin]

@brillout

Just a few personal opinions for reference:

Documentation section

1. Vike's documentation is one of the few documentation pages that use top-level navigation, and to be honest, the top navigation bar is not as user-friendly as the side navigation bar for navigation with a large number of menu items, and I think that's why most documentation pages use side navigation.
2. Lack of complete integrated SSR documentation, without looking at the relevant examples, it is completely impossible to learn how to develop and deploy an SSR application from the documentation.
3. Similarly, the same is true for SPA applications, the relevant knowledge is scattered on different pages, and you need to view and learn in Guides, APIs, Github examples, etc., in order to complete the development and deployment of SPA, SSR and other applications.
4. The deployment page only provides the integration methods of various service providers, on the contrary, the most basic use case I think is that I have a cloud server, how do I deploy a SPA, SSR application.
5. 'Without vike-{react,vue,solid}' is scattered across the pages, which leads to beginner marriage theory. I guess it should be assumed that most users use the plugin by default, and have a full description of the 'Without vike-{react,vue,solid}' case in a separate page.
6. In my experience with other documentation, most of the documentation can learn the basics of the framework by relying only on the Guides section, and only when you need to understand the internals, or more complex use cases, you need to look at the API part. But Vike's documentation makes me feel like Guides aren't even as helpful as looking directly at the API documentation. A lot of knowledge can only be learned in the API documentation.
7. The data fetch section does not provide examples of using a separate API.

Experience the pain points found within two days (and did not fully review the relevant issues or discussions, if there are duplicates, please understand):

1. For SPA applications that only provide a Pre-rendering (SSG) method, I think we should provide a most basic way, just like a basic vite application, just build a index.html.
2. For SSG mode, dynamic path param@id construction should be supported by default
3. For SSR applications, the default server integration should be provided.
4. You should ensure that when the config item ssr:true, the built project can be run directly in the 'dist' directory by default in a way like 'node index.mjs'. When 'ssr:false', you should make sure that there is a 'index.html' in the default state (not prerender) that can be used directly by the web server.

It's just a two-day trial, and it's just my personal experience as a newbie to Vike, and I think I'll come back when 1.0 is released, but at the moment Vike is not available to me.

[brillout]

2. Lack of complete integrated SSR documentation, without looking at the relevant examples, it is completely impossible to learn how to develop and deploy an SSR application from the documentation.
3. The deployment page only provides the integration methods of various service providers, on the contrary, the most basic use case I think is that I have a cloud server, how do I deploy a SPA, SSR application.

👍 #2112

3. Similarly, the same is true for SPA applications, the relevant knowledge is scattered on different pages, and you need to view and learn in Guides, APIs, Github examples, etc., in order to complete the development and deployment of SPA, SSR and other applications.

👍 #2111

5. 'Without vike-{react,vue,solid}' is scattered across the pages, which leads to beginner marriage theory. I guess it should be assumed that most users use the plugin by default, and have a full description of the 'Without vike-{react,vue,solid}' case in a separate page.

👍 #2109

7. The data fetch section does not provide examples of using a separate API.

👍 #2110

1. For SPA applications that only provide a Pre-rendering (SSG) method, I think we should provide a most basic way, just like a basic vite application, just build a index.html.

We believe having a bunch of static index.html is an anti-pattern in a context of a framework. It makes sense for Vite because it's always SPA. But with Vike you can simply use ssr: boolean to toggle between SPA and SSR without modifying your code — that's very helpful if you don't know yet whether you need SSR or not. With a bunch of static index.html files, toggling between SPA and SSR becomes a lot more complex. But, yes, that's something we should maybe clarify in the docs — created #2108.

When 'ssr:false', you should make sure that there is a 'index.html' in the default state (not prerender) that can be used directly by the web server.

👍 #2107

---

The rest is already on the radar:

2. For SSG mode, dynamic path param @id construction should be supported by default

It's on the radar and high prio: #1476.

3. For SSR applications, the default server integration should be provided.

We're currently working on vike-{express,hono,fastify,...} as well as vike-{vercel,cloudflare,github-pages,netlify,...} to make server and deployment integration as easy as possible. Ideally it should just be a matter of installing a Vike extension. (While having server/deployment integrations ejectable in case you need more control.)

4. You should ensure that when the config item ssr:true, the built project can be run directly in the 'dist' directory by default in a way like 'node index.mjs'.

Yes, that will be the case. (You can already try it out with vike-node but note that it isn't stable yet.)

6. In my experience with other documentation, most of the documentation can learn the basics of the framework by relying only on the Guides section, and only when you need to understand the internals, or more complex use cases, you need to look at the API part. But Vike's documentation makes me feel like Guides aren't even as helpful as looking directly at the API documentation. A lot of knowledge can only be learned in the API documentation.

That's very much what we try to achieve with our Guides and API sections but, yes, we probably fail to provide enough information in Guides. Also, maybe we should move some API content to Guides, I'll be more thoughtful about that.

1. Vike's documentation is one of the few documentation pages that use top-level navigation, and to be honest, the top navigation bar is not as user-friendly as the side navigation bar for navigation with a large number of menu items, and I think that's why most documentation pages use side navigation.

I'll disagree on that one, because I think that being able to see all documentation pages at a glance makes navigating the documentation significantly easier. As we add more documentation pages, this will become even more valuable.

---

It's just a two-day trial, and it's just my personal experience as a newbie to Vike, and I think I'll come back when 1.0 is released, but at the moment Vike is not available to me.

Thank you for your feedback. Looking forward to welcome you back after the v1.0 release. In the meantime, let me know if you have any other feedback or suggestions.