Provide a public document context for SSG...

[natemoo-re]

Provide a public document context for SSG...

[eyelidlessness]

Well that hammock really helped! Turns out I didn't need any kind of context or per-page or per-document setup for this. I just needed to make a couple changes in tsconfig.json to allow me to use top-level await!

[eyelidlessness]

On that note at some point after launch I plan to break a significant amount of my site/build off into open source libraries and do some deep dive writing about my motivation for the set of tools I chose and how I got them to play nice.

Microsite is definitely going to be a central theme because it’s the core that let me get everything else I wanted for my project. Once I’m there I’d be happy for anything I release or post to be incorporated into examples or docs to help anyone else wanting any part of my weird combination of preferred DX/build priorities.

[eyelidlessness]

I guess I should add that the alternatives are I discover I’ve configured myself into my own hell or I gotta put some babel into my mix. Both are real potentials

[natemoo-re]

This is an interesting idea!

Two things stick out to me:

Type safety is a major concern for me, and anything automated/implicit could lead to magic and assumptions; definitely an argument against automating any of this, probably easier to target doc-global and/or a very specific API for context overall. Or a useDocument/usePage hook but I’m losing it even suggesting that 🙃

It would definitely be useful to have somewhere to place global Provider components for every page, since that's a really common use case and custom Document doesn't support it right now. I am thinking an entry point like Next's pages/_app.js? Users could add any custom Provider components there, which would allow them to manually pass down anything from Document.prepare, but Microsite wouldn't do it automatically.

Would that potentially cover this use case? One big issue I see is that it's not clear how those Providers should interact with hydration... Would these only be static? Would users understand that requirement?

In fact I might even want to go one step further and suggest a general API/DX improvement over the Next/Gatsby style interface (which should be backwards compatible unless I’ve failed to think of something), and say that props supplied in a custom document or getStaticProps could automatically provide context consumable by deeper components. This would address very similar issues I had with those doc/page APIs that don’t allow per-component data fetching at build time.

Something like a useStaticProps hook could be a really nice DX improvement!

[eyelidlessness]

I am thinking an entry point like Next's pages/_app.js? Users could add any custom Provider components there, which would allow them to manually pass down anything from Document.prepare, but Microsite wouldn't do it automatically.

The familiar API would definitely benefit newbies and adoption. I’m personally always confused by the different special page worlds and what’s allowed or not (though definitely have better reflexes knowing the Microsite internals). IMO it’s less important where it lives, more important that it’s clear how to use and has a clear type safe interface for use (so pages don’t get magic from app or doc or whatever).

Would that potentially cover this use case? One big issue I see is that it's not clear how those Providers should interact with hydration... Would these only be static? Would users understand that requirement?

Yes I think it would cover my use case!

As far as hydration I’m hesitant to suggest another server/client boundary. But this does have some additional risks I didn’t think about earlier, specifically serializability. Right now Next says you can’t even pass static props if they’re not primitive (they won’t even handle normal JSON-serialization values like Date or anything with a toJSON method which is IMO a bug). So my use case is dead in the water right there as I couldn’t pass a function much less a context. To be fair I think some serializable constraints are reasonable for hydration though I think Next is too restrictive.

I think the easiest approach would definitely be another server/client boundary but I’m so hesitant to introduce one. If that is the answer I’d want to make sure it has a clearly different call site. And here it really starts butting up against the type safety goal again :/

I’m gonna go do some hammock driven development on this and give it a good think instead of just braindumping. I’m glad you’re open to the idea!

[natemoo-re]

Awesome! Closing for now but I will definitely be thinking about something like _app for other similar use cases.

[eyelidlessness]

Totally understand keeping the issues cleaned up but I’m gonna probably want to offer a PR documenting the solution I came up with for my static-only use case as soon as I can prove out that I can still hydrate the runtime for twoslash, once I have a content need for that functionality (so far I’ve been able to get away with just plain Shiki highlighting and I must say it’s wonderful!).

Not that I think it’s the final answer here but if it can save someone a few days of hunting for a solution when top-level await might be all they need I’d love to help there.