foldkit-ssr 0.7.0 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +74 -6
- package/dist/client-DVG9_3rL.mjs.map +1 -1
- package/dist/client-DkwAniQQ.d.mts.map +1 -1
- package/dist/index.d.mts +3 -3
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +6 -5
- package/dist/index.mjs.map +1 -1
- package/dist/vite.d.mts +25 -1
- package/dist/vite.d.mts.map +1 -1
- package/dist/vite.mjs +39 -4
- package/dist/vite.mjs.map +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -411,8 +411,16 @@ export const site = {
|
|
|
411
411
|
} satisfies SiteModule
|
|
412
412
|
```
|
|
413
413
|
|
|
414
|
+
`emit` adds files made from the generated pages, written beside them: what the
|
|
415
|
+
pages reference and the build must also serve, such as the image variants
|
|
416
|
+
their `srcset`s name (`foldkit-media`'s `materialize`). It takes the pages and
|
|
417
|
+
returns `{ file, contents }`s; a path that leaves the output (absolute, `..`)
|
|
418
|
+
or lands on a page, the sitemap, robots or another emitted file is refused, and
|
|
419
|
+
so is one the client build already wrote, a file from `public/` among them.
|
|
420
|
+
|
|
414
421
|
`generateStaticSite(site)` is the same build without Vite: it renders every
|
|
415
|
-
path and returns `{ pages, sitemap?, robots
|
|
422
|
+
path and returns `{ pages, sitemap?, robots?, emitted }`; `writeEmitted(outDir,
|
|
423
|
+
emitted)` writes the emitted files as the plugin does. `fileFor(path, layout)` maps
|
|
416
424
|
one path to the file a host serves it from, so a caller writes the files
|
|
417
425
|
itself; `generateStaticSite` refuses two paths that would claim one file.
|
|
418
426
|
|
|
@@ -702,9 +710,9 @@ and a form cannot carry a CSRF header. `SSR.entry`'s `origins` names the
|
|
|
702
710
|
origins a form may be posted from; a post whose `Origin` (every browser sends
|
|
703
711
|
one on a `POST`) is not among them is answered `403` before its body is read
|
|
704
712
|
or `flags` and `resources` run. A page served with `Referrer-Policy:
|
|
705
|
-
no-referrer` posts `Origin: null` even to its own site; such a post
|
|
706
|
-
when its `Sec-Fetch-Site`,
|
|
707
|
-
`same-origin
|
|
713
|
+
no-referrer` posts `Origin: null` even to its own site; such a post, or one
|
|
714
|
+
with no `Origin` at all, is taken when its Fetch Metadata `Sec-Fetch-Site`,
|
|
715
|
+
which no page or form can set, says `same-origin`, and refused without it. A plan with a server fallback requires `origins`, since a post
|
|
708
716
|
runs `flags`, the config's `resources` and its own as whoever the cookie says
|
|
709
717
|
posted: an entry made without them throws. An entry of your own that calls
|
|
710
718
|
`SSR.handle` checks `Origin` itself.
|
|
@@ -765,6 +773,68 @@ SSR.hydrate(config, plan, { buildId, when, otherwise: 'render', until: Site.answ
|
|
|
765
773
|
The served page stays as it was served while it waits: its links are plain
|
|
766
774
|
links, and nothing it shows becomes live.
|
|
767
775
|
|
|
776
|
+
## A reader's preferences in the first frame
|
|
777
|
+
|
|
778
|
+
A theme, a light or dark choice, a density: a reader expects the page to open
|
|
779
|
+
in what they chose, not in the default and then theirs. Under the rule above,
|
|
780
|
+
the first frame shows whatever the server knew when it rendered.
|
|
781
|
+
|
|
782
|
+
**Rendered per request, the server can know it, from a cookie.** It is the
|
|
783
|
+
[example's](../../examples/foldkit/ssr) count, by the same route:
|
|
784
|
+
|
|
785
|
+
```text
|
|
786
|
+
request cookie ─▶ flags ─▶ init ─▶ Model.theme ─┬─ view draws it
|
|
787
|
+
└─ plan.state carries it, so the browser resumes with it
|
|
788
|
+
```
|
|
789
|
+
|
|
790
|
+
```ts
|
|
791
|
+
import { Option, Record, Schema, pipe } from 'effect'
|
|
792
|
+
import { Cookies } from 'effect/http'
|
|
793
|
+
import { Theme, Themes } from 'foldkit-mixins/theme'
|
|
794
|
+
|
|
795
|
+
const themes = Themes.make(
|
|
796
|
+
{ plain: Theme.make({}), dense: Theme.make({ shape: { density: 0.85 } }) },
|
|
797
|
+
{ initial: 'plain' },
|
|
798
|
+
)
|
|
799
|
+
|
|
800
|
+
/** The kept theme for a request, or the initial one for a missing or unknown cookie. */
|
|
801
|
+
export const readThemeCookie = (cookieHeader: string) =>
|
|
802
|
+
pipe(
|
|
803
|
+
Cookies.parseHeader(cookieHeader),
|
|
804
|
+
Record.get('theme'),
|
|
805
|
+
Option.flatMap(Schema.decodeUnknownOption(themes.Name)),
|
|
806
|
+
Option.getOrElse(() => themes.initial),
|
|
807
|
+
)
|
|
808
|
+
```
|
|
809
|
+
|
|
810
|
+
Read it in `flags: request => …`, keep it in the plan's `state` (leaving it out
|
|
811
|
+
is refused: the view reads a field the browser would not have), and answer
|
|
812
|
+
with `cache-control: private` and `vary: cookie`, as the example does: such a
|
|
813
|
+
page is one reader's, and no shared cache may keep it.
|
|
814
|
+
|
|
815
|
+
What the view draws is then right in the first frame. What it cannot draw is
|
|
816
|
+
`<html>`: `Themes` shows a theme by an attribute there, and `color-scheme`
|
|
817
|
+
lives there. The view renders the application's root only, so:
|
|
818
|
+
|
|
819
|
+
- the host's template carries a head script, `Themes.script(themes)` (and
|
|
820
|
+
`Theme.schemeScript()`). It is static text, so a template that is the same
|
|
821
|
+
for every request holds it, and it reads the name the Command kept in
|
|
822
|
+
`localStorage`;
|
|
823
|
+
- the Command that keeps a choice keeps it twice, the cookie for the server
|
|
824
|
+
and storage for the script: `Themes.choose(themes, name)`, then
|
|
825
|
+
`document.cookie = 'theme=…; Path=/; Max-Age=31536000; SameSite=Lax'`
|
|
826
|
+
(`Secure` on HTTPS);
|
|
827
|
+
- the plan's `boot` applies the Model's theme (`Themes.apply`), so storage that
|
|
828
|
+
was refused or cleared costs one frame, not the visit.
|
|
829
|
+
|
|
830
|
+
**Generated at build time** (`SSR.generate`), there is no reader to ask, and
|
|
831
|
+
every page is built in the default. No change inside the application helps:
|
|
832
|
+
its script runs after the browser may have painted. The head script alone
|
|
833
|
+
draws the first frame, written through the generator's `head`; the Model
|
|
834
|
+
catches up in `boot`. `foldkit-mixins/theme` ships the pairs: `schemeScript`
|
|
835
|
+
and `chooseScheme`, `Themes.script` and `Themes.choose`, `Theme.knobScript`
|
|
836
|
+
and `Theme.chooseKnobs`.
|
|
837
|
+
|
|
768
838
|
## Costs and limits
|
|
769
839
|
|
|
770
840
|
- **`SSR.render` renders the view twice.** That is the view check. A static
|
|
@@ -857,8 +927,6 @@ const Message = defineMessageUnion({
|
|
|
857
927
|
|
|
858
928
|
## See also
|
|
859
929
|
|
|
860
|
-
- [The implementation plan](../../docs/design/ssr-PLAN.md): the decisions and
|
|
861
|
-
why, phase by phase.
|
|
862
930
|
- [What the tests prove](./test/README.md).
|
|
863
931
|
- [What this package asks of Foldkit](../../docs/upstream-foldkit-ssr.md).
|
|
864
932
|
- [Site, Remote and SSR together](../../docs/site-remote-ssr.md): a routed
|