Difficulties when upgrading to the V1 design

[ChristophP]

Description

We attempted upgrading to the V1 design partially to be able to use new features and also the docs mostly show the examples in the new design. We encountered several problems to upgrade, some could be worked around after trying out some things, other not so easily indicating some subtle differences between v0 and v1. In order to provide some feedback and help others encountering the same issues. I will collect them here.

1. Errors with wrong Node Env

Why does this happen? In our setup we are setting the NODE_ENV to local (changing it wouldn't be easy because our setup relies on NODE_ENV to be certain values for for example the DB connection to work, a weird case on our part admittedly). In version 0.4.160-0.4.163 warnings around bad NODE_ENV values are hard errors.

Fix: @brillout kindly changed that to be warnings in 0.4.164

2. onRenderClient is not called when Page is not used client-side

Why does this happen? When using partial hydration (i.e. not hydrating the full page client side but only parts) we do not want the full Page to be sent to the client. Setting it to server only via meta.env or not using it at all implicitly and silently makes onRenderClient not be called when the page loads. Thus making it a choice between sending all of the JS to the client or not having any hydration at all.

Workaround: Because if the V1 design ability to create new settings we can work around it like this: Create a dummy +Page with a component like this (() => "keep this"). We do this to signal to Vike that we need onRenderClient to to be called. Then we create a new setting in +config and call it ServerPage: { env: { server: true, client: false } } and use pageContext.config.ServerPage instead if pageContext.Page to render our server-side code allowing us to only render the parts on the client we need. Upside: it allows to do partial hydration with a small workaround, Downside: We have to actually know the implicit behavior of Vike here and create a Page just to make Vike think we do not want the html-only behavior here.

Request: The workaround works. Would be nice though if there was a setting to control whether the mode is html-only or not. Pages that are conscious about sending minimal JS (island architecture) to the client are quite popular. The heuristic that's currently used might not fit all scenarios and the exact behavior seems to be undocumented.

3. .gitignored plus-files are not detected when there are other plus files exist that are checked into git

Why does this happen? Vike seems to ignore gitignored plus files in V1. The logic seems like it does read gitignored plus files but only if there are no other plus files that aren't gitignored. This seems to be the logic. In our case we have a mix of "hardcoded" and generated pages. The hardcoded ones are checked into git of course. The generated ones aren't. Prior to the V1 design both types of files were picked up.

Workaround: We could force all of the plus files to be generated but it wouldn't make a lot of sense from our perspective since some files are "user files" and others are "framework files". We could do some trickery like keeping the framework files in a different place and copy them into the Vike root at build time but that would be pretty messy.

Request: Would be nice if there was a also setting to control whether gitignored files should be scanned and possible in which directory/directories to allow for mixing of checked-in and gitignored plus files. A note in the docs about the current behavior might also be good.

[brillout]

Downside: We have to actually know the implicit behavior of Vike here and create a Page just to make Vike think we do not want the html-only behavior here.

I agree it isn't ideal. The less implicit heuristics the better, but there are reasons why this heuristic is in place. That said, I think there are opportunities to make things simpler.

Pages that are conscious about sending minimal JS (island architecture) to the client are quite popular.

I agree that'd be nice. It just isn't the highest priority right now. (There are already a lot of high priorties and a lot of tickets, of which many are complex).

The general expectation here is that folks who want to achieve advanced use cases (that cannot be implemented using other frontend frameworks) need to 1. invest time into digging and 2. sponsor the Vike project. While I definitely appreciate the bronze sponsorship of Burda (thank you! 💚), it's difficult to justify prioritizing use cases that are far from trivial and that are beneficial to only few users.

the logic

I was actually thinking of Burda when I implemented that logic, as I was under the impression that everything is generated.

In our case we have a mix of "hardcoded" and generated pages.

Hm, I'm not sure yet what a solution could be (there are may subtle trade-offs). (FYI using $ git instead of fast-glob is a major improvement that unblocks many users.)

[brillout]

The general expectation here is that folks who want to achieve advanced use cases (that cannot be implemented using other frontend frameworks) need to 1. invest time into digging and 2. sponsor the Vike project. While I definitely appreciate the bronze sponsorship of Burda (thank you! 💚), it's difficult to justify prioritizing use cases that are far from trivial and that are beneficial to only few users.

My point was only about how Vike prioritizes new feature requests. I'm definitely open for feature requests, it's just that I'm thinking that we should be a little bit careful by having some kind of constellation that works for everyone.

The V1 design shouldn't have any feature regression (which is actually the case AFAIK). In other words: anything that works with the old design should also work with the V1 design. If you believe to have stumbled upon a V1 design regression, then let me know and I'll dig into it. (I ain't sure if I was clear about that in the past - apologies if I wasn't. FYI the crawling regression is unrelated to the V1 design.)

As for the crawling issue, let me know if you still have that issue and I'll think of a solution. In general, feel free to keep me updated how things go.

[ChristophP]

Hi @brillout ,

so the main hurdles for upgrading to the V1 design remain to be these points 2. and 3. from the initial post

2. Being able to use client-side JS for parts of the page but not the whole

I think we may be able to work around the issue with the workaround as described above.

• creating a dummy page (to make Vike call onRenderClient)
• having our actual page as a server-only ServerPage setting

If I understood it correctly I believe +client.js would not help us here because we need access to the pageContext (which to my knowledge client.js does not allow) to call hydration code for certain parts of the page that the server sends to the client.

3. A clean solution for the crawling issue

I haven’t really found a solution to the crawling issue so far. I guess one sort of hackish way would be to keep the source files of the static pages elsewhere and copy them into the folder at build time. Would probably work but feels like a weird workaround. It would be nicer to a have clean solution or a configurable way to specify where page files would be.

[brillout]

Point 2

Yes, creating a dummy page should do the trick.

And, indeed, +client.js doesn't have access to pageContext.

I agree that a more explicit way to control whether the page is considered "client-side renderable" would be nice. Is the workaround annoying for you? (I'm thinking if you generate the dummy page automatically then maybe the workaround is fine for you.) Let me know if it's annoying and I'll think of a more explicit way to control.

Point 3

I created a feature request for it: #1655. I labeled it needed-by-sponsor and thus implement it sooner rather than later (feel free to let me know how urgent it is for you).

[ChristophP]

Hi @brillout ,
thanks for you reply. Sorry for my late reply, I was on vacation last week.

Point 2

Is the workaround annoying for you? (I'm thinking if you generate the dummy page automatically then maybe the workaround is fine for you.) Let me know if it's annoying and I'll think of a more explicit way to control.

The workaround will be ok for us and not too much trouble. Something we can implement in a way that won't affect BurdaForward userland. So that'll work for now without hassle.

I agree that a more explicit way to control whether the page is considered "client-side renderable" would be nice.

Yes, long to medium term that would be nice

Point 3

I created a feature request for it: #1655. I labeled it needed-by-sponsor and thus implement it sooner rather than later (feel free to let me know how urgent it is for you).

That would indeed be great to have since otherwise it would force us to work around it by copying around files. I will comment on the feature request.

[brillout]

Alright, let me implement #1655 then. ETA today.

[brillout]

c1b0884 implements #1655 and is pre-released as 0.4.172-commit-c1b0884 use pre-release 0.4.172-commit-c1dcd5f instead (see my comment below).

// vite.config.js

import vike from 'vike/plugin'

export default {
  plugins: [
    vike({
      crawl: { git: false }
    })
  ]
}

It's marked as experimental and it isn't documented (yet), because it's going to be moved from vite.config.js to the upcoming vike.config.js. The setting itself will stay and can be considered stable.

[brillout]

Point 2

c1dcd5f implements a new setting clientHooks. This should address the shortcomings you described at point 2.

Both settings clientHooks and crawl.git are pre-released in 0.4.172-commit-c1dcd5f.

[ChristophP]

Hi @brillout ,

I couldn't get much coding done last week due to an internal conference, but this week I tried the V1 upgrade once again.

It worked very smoothly, both the clientHooks settings and the crawl option work very well and allow us to migrate to the V1 design, which is great. Also nice how these new settings allow partial hydration and generated pages in general. I like how the settings with V1 compose nicely together and can be overridden locally. Nice job. :-)

Thanks for implementing the new settings so quickly in the past week.

[brillout]

I'm glad to hear that :-)

Let me know if there is anything else! (Btw. if you could nudge management a bit about restarting the sponsoring that'd be nice 😇.)

[ChristophP]

I nudged him and wrote you on Discord.