docs/better document and clarify Lit SSR plugin usage caveats

[thescientist13]

Related Issue

Was called out in #1336 that this caveat was missing. Could have sworn it was there 🤦

Documentation

N / A

Summary of Changes

1. Properly callout native HTMLElement caveat in Lit SSR
2. Share tip on Lit SSR styles work around using Raw plugin + <style> tag
3. Document pnpm hoisting strategy for lit-labs dependencies

TODO

1. Incorporate additional caveats feedback around rendering strategies
2. Lit SSR styles work around (raw plugin + style tag)
3. pnpm hoisting strategy
4. make HTMLElement limitation more up-front on the website - docs/make Lit SSR HTMLElement caveat more up-front www.greenwoodjs.dev#147

[lschierer]

I am more than a bit confused as to the differences between the rendering strategies and while I realize that much of the confusion is my limitation, not the documentation's, I do think that the text in the prerender section of the lit plugin's readme has contributed to my confusion, as it reads (at least to me) as if there are two prerendering modes, one from lit and one from WCC. From discussion in discord with @thescientist13 its clear that I misunderstood that.

[lschierer]

I'm partly confused about what is possible because https://greenwoodjs.dev/docs/plugins/lit-ssr/ links to https://greenwoodjs.dev/docs/pages/server-rendering/ which has a number of examples using html components, but no mention on either page that these examples won't work with the lit plugin enabled (or they will, but only with the right combination of options?).

[lschierer]

Per the discussion in discord, a caveat that explained that the examples using HTMLElements would need a search/replace substitution to use LitElement would suffice to prevent nearly all the confusion I experienced and resolve the other comments I've left on this PR. The caveat would, unfortunately, probably need to be on both the website on the /docs/plugins/lit-ssr/ page and in the plugin's own readme (or overly literal people like me are likely to miss it).

[thescientist13]

Yeah, good call. I don't expect us to maintain docs examples for every possible WC based library that could be used with Greenwood, Lit was just the main one that also provides good SSR support, but we can at least make this more obvious both from the Lit SSR plugin docs page and the README for sure to make sure developers know they can only use LitElement based classes when opting in to Lit+SSR

[lschierer]

No, you certainly don't want to try to have a caveat that either encompasses all possible web components nor one per web component. That's why I was envisioning the caveat being on the two lit specific documentation pages.

[thescientist13]

Hey @lschierer

Thanks for all the good feedback here, and I have now updated the plugin's README with following additional call-outs:

• Move HTMLElement to be the first bullet of caveats section
• Suggest hoisting patterns for PNPM users
• Update GitHub issue link for CSSStyleSheets limitation and provide link to alternative (interim) work around

I also opened a PR to the website docs to also make the HTMLElement caveat more up front - ProjectEvergreen/www.greenwoodjs.dev#147

---

Also, the observation of having multiple prerender options between Greenwood config and this plugin is indeed confusion, so I think now with this clearer caveat around HTMLElement / LitElement, I think it would just make sense to remove the prerender option from this plugin, and have it just be set from greenwood.config.js, so I opened an issue for that here and will open a standalone PR for that change - #1343 .

---

Thanks again for all your suggestions and feedback and let me know what you think of these changes. 👍

[lschierer]

awesome, looks good :-)

[thescientist13]

Great, appreciate the extra set of eyes on it. 👀