jskelet 0.1.1 → 0.1.3

package/docs/en/10-deployment.md

@@ -0,0 +1,332 @@
+# 10 — Deployment
+
+This document explains how to put a JSkelet application into production: the
+prod build and start flow, the environment variables you should set, a working
+Docker setup, reverse proxy and `trust proxy` notes, how a health check endpoint
+is added, and how the cache behaves when you scale out. What the build steps do
+is in [08-build.md](./08-build.md), cache behavior in
+[06-caching.md](./06-caching.md).
+
+## The prod flow
+
+```bash
+npm ci
+npm run build     # jskelet build
+npm start         # jskelet start
+```
+
+If `NODE_ENV` is not given, `jskelet build` sets it to `production` and runs all
+steps: fonts, icon sprite, CSS, client JS, images, manifest, precompress.
+
+`jskelet start` first looks for `.jskelet/manifest.json`; if it is missing, it
+runs the build itself. In a Docker image the build has already happened, so this
+is a no-op; the point is that someone running `npm start` directly does not end
+up with an unstyled page.
+
+When the server is ready it prints a single line:
+
+```
+jskelet → http://localhost:3000 (production)
+```
+
+The process is protected by two safety nets: `unhandledRejection` and
+`uncaughtException` are logged and the process stays up. On a news site, an
+error on a single page should not take the whole site down. If you want to hook
+this up to your own error tracking tool (Sentry etc.), you can add your own
+listener to the same events.
+
+## Environment variables
+
+No variable is required; all of them have a sensible default. The ones worth
+considering in production:
+
+| Variable | Recommendation | Why |
+| --- | --- | --- |
+| `NODE_ENV` | `production` | Template cache, reading the manifest once, throwing on a broken route module |
+| `PORT` | `3000` | The port your orchestrator expects |
+| `HOST` | `0.0.0.0` | For external access inside a container (the default) |
+| `PREWARM_MAX` | Depends on site size | Number of pages warmed at startup |
+| `PREWARM_INTERVAL_SECONDS` | `0` or a long value | If you want to keep never-visited pages warm |
+| `DEV_TOKEN` | Staging only | Hides an environment that is not public yet |
+
+The full list and the precedence order of the prewarm settings:
+[07-configuration.md](./07-configuration.md).
+
+Since the CLI runs with `--env-file-if-exists=.env`, a `.env` file is loaded
+automatically if it exists; if not, no error is raised. In a container,
+environment variables are usually injected directly instead of using this file.
+Using both sources together blurs which value actually applies; not shipping a
+`.env` in the prod image is the cleanest option.
+
+**Secret keys must not go into the `clientEnv` list:** those values are embedded
+into the client bundle as plain text ([08-build.md](./08-build.md)).
+
+## Docker
+
+A multi-stage image: the build stage compiles with dev dependencies, the runtime
+stage carries only production dependencies and the build output.
+
+```dockerfile
+# syntax=docker/dockerfile:1
+
+# ---------- build ----------
+FROM node:22-bookworm-slim AS build
+WORKDIR /app
+
+# Dependencies in a separate layer: don't reinstall when sources change.
+COPY package.json package-lock.json ./
+RUN npm ci
+
+# `public/fonts/` must be committed: the build should not need network access.
+COPY . .
+
+ENV NODE_ENV=production
+RUN npx jskelet build
+
+# ---------- runtime ----------
+FROM node:22-bookworm-slim AS runtime
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV PORT=3000
+ENV HOST=0.0.0.0
+
+COPY package.json package-lock.json ./
+# sharp and tailwind are only needed at build time; keep them out of the runtime image.
+RUN npm ci --omit=dev && npm cache clean --force
+
+COPY --from=build /app/jskelet.config.mjs ./jskelet.config.mjs
+COPY --from=build /app/jsconfig.json ./jsconfig.json
+COPY --from=build /app/routes ./routes
+COPY --from=build /app/views ./views
+COPY --from=build /app/lib ./lib
+COPY --from=build /app/public ./public
+COPY --from=build /app/.jskelet ./.jskelet
+
+# Non-root user.
+USER node
+
+EXPOSE 3000
+
+# Health check: assumes you added the route below.
+HEALTHCHECK --interval=30s --timeout=3s --start-period=20s --retries=3 \
+  CMD node -e "fetch('http://127.0.0.1:'+(process.env.PORT||3000)+'/api/healthcheck').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+
+CMD ["npx", "jskelet", "start"]
+```
+
+Notes:
+
+- **`client/` and `styles/` are not needed in the runtime image:** their output
+  is under `public/assets/`. `views/` and `routes/` are needed, because
+  rendering happens at runtime. Copy `lib/` only if your project has one.
+- **`.jskelet/` is needed:** without `manifest.json`, `asset()` cannot find the
+  hashed URLs and `jskelet start` will try to run the build from scratch.
+- **`sharp` is not needed in the runtime image:** it is only for build-time image
+  optimization. `--omit=dev` leaves it out (if it was installed as a
+  devDependency).
+- If you would rather call `jskelet start` without `npx`,
+  `CMD ["node", "node_modules/jskelet/bin/jskelet.mjs", "start"]` works too.
+
+`.dockerignore`:
+
+```
+node_modules
+.git
+.jskelet
+public/assets
+.env
+```
+
+The build stage produces these itself with `npx jskelet build`.
+
+### Deploying from a subdirectory of the repo
+
+The examples in this repo pull jskelet with `"jskelet": "file:../.."` rather
+than from npm. In tools like Coolify, Railway or Render, if you set the "base
+directory" to `examples/marketing`, the build context becomes only that
+directory, `../..` falls outside the context, and installation fails at
+`npm ci`. The correct setting: **base directory `/`**, Dockerfile location
+`/examples/marketing/Dockerfile`. The working example is in
+`examples/marketing/Dockerfile` and assumes the repo root as its context:
+
+```bash
+docker build -f examples/marketing/Dockerfile -t jskelet-marketing .
+docker run --rm -p 3000:3000 -e SITE_URL=https://example.com jskelet-marketing
+```
+
+In your own application jskelet will be an ordinary dependency, so this
+constraint does not apply; the multi-stage image above is enough.
+
+## Health check
+
+The framework does **not** add a ready-made health check endpoint; you have to
+put it in your own route. Since the default `devGateBypass` list contains
+`/api/healthcheck`, using that name is the least surprising option: it stays
+reachable even in an environment with `DEV_TOKEN` set.
+
+```js
+// routes/00-health.mjs
+import { getHtmlCacheSize } from "jskelet";
+
+export default function register(app) {
+  app.get("/api/healthcheck", (req, res) => {
+    res.setHeader("Cache-Control", "no-store");
+    res.json({
+      ok: true,
+      uptime: process.uptime(),
+      cache: getHtmlCacheSize(),
+    });
+  });
+}
+```
+
+The `00-` prefix in the file name makes sure this route is registered before any
+catch-all ([03-routing.md](./03-routing.md)).
+
+If you are going to use a different path, update the `devGateBypass` list,
+otherwise your orchestrator will see a 404 on staging:
+
+```js
+devGateBypass: ["/healthz", "/robots.txt", "/sitemap.xml", "/favicon.ico"]
+```
+
+The warming round does not affect the health check: even if prewarm fails, the
+process stays up and pages are served (cold, but served).
+
+If you need to separate readiness from liveness, you can report the warming
+status too:
+
+```js
+import { prewarmProgress } from "jskelet";
+
+app.get("/api/ready", (req, res) => {
+  const warmedUp = !prewarmProgress.active && prewarmProgress.finishedAt !== null;
+  res.status(warmedUp ? 200 : 503).json({ warmedUp, ...prewarmProgress });
+});
+```
+
+Remember to exclude this endpoint's path from warming with `prewarmSkip` (the
+default `/api/` prefix already covers it).
+
+## Reverse proxy
+
+The Express application sets `trust proxy` to **on**
+(`app.set("trust proxy", true)`). The consequences:
+
+- `req.protocol` is read from the `X-Forwarded-Proto` header, so if the proxy
+  terminates TLS, `https` is returned correctly.
+- `req.ip` is resolved from the `X-Forwarded-For` chain.
+- Absolute URLs produced by `res.redirect()` carry the correct scheme.
+
+This setting **assumes the proxy writes these headers reliably.** If you are
+going to expose the application directly to the internet, remember that a client
+can fabricate `X-Forwarded-*` headers; always run behind a proxy or load
+balancer and make sure the proxy overwrites the incoming `X-Forwarded-For`
+header.
+
+An example nginx configuration:
+
+```nginx
+upstream jskelet {
+  server 127.0.0.1:3000;
+  keepalive 32;
+}
+
+server {
+  listen 443 ssl http2;
+  server_name example.com;
+
+  # Response bodies already arrive compressed; don't compress a second time.
+  gzip off;
+
+  location / {
+    proxy_pass http://jskelet;
+    proxy_http_version 1.1;
+
+    proxy_set_header Host              $host;
+    proxy_set_header X-Real-IP         $remote_addr;
+    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header Connection        "";
+
+    # Forward it to the upstream so we can get a compressed response.
+    proxy_set_header Accept-Encoding   $http_accept_encoding;
+  }
+}
+```
+
+Key points:
+
+- **Do not compress twice.** JSkelet does the brotli/gzip negotiation itself and
+  stores the compressed body for cached pages. Leaving nginx's own `gzip` on can
+  lead to decompressing brotli and re-gzipping it.
+- **Forward `Accept-Encoding`**, otherwise the application will not compress and
+  the ready-made compressed bodies in the cache go unused.
+- `Vary: Accept-Encoding` is written by the application; proxy caches take it
+  into account.
+
+### Together with a CDN
+
+The header written on cacheable pages:
+
+```
+Cache-Control: public, max-age=0, s-maxage=<revalidate>, stale-while-revalidate=60
+```
+
+`max-age=0` disables browser storage, `s-maxage` tells the CDN the duration. So
+the same freshness model works across two layers together: the CDN serves its
+own copy for the duration of `s-maxage`, asks the origin when it expires, and
+the origin answers instantly from its own cache.
+
+The `X-JSkelet-Cache` header makes it easier to diagnose which layer answered;
+read it together with the CDN's own cache header
+([06-caching.md](./06-caching.md)).
+
+Static assets (`/assets/`, `/fonts/`) are marked `immutable`, so they can be
+held indefinitely on the CDN; when the hash changes, so does the URL.
+
+## Scaling
+
+The HTML cache lives **in process memory**. When you run more than one replica:
+
+- Each replica has its own cache; memory usage is multiplied by the replica
+  count (at most 500 entries plus their compressed copies).
+- Each replica runs its own warming round at startup. Set `PREWARM_MAX` and
+  `PREWARM_CONCURRENCY` so that your upstream API can handle the load
+  multiplied by the replica count.
+- `clearHtmlCache()` only affects the process it is called in. If you need to
+  clear all replicas, you have to solve it at the orchestrator level (a restart)
+  or with a broadcast mechanism you write yourself.
+- If there is a CDN in front, most requests never reach the origin and the
+  per-replica cache difference becomes invisible.
+
+To increase the capacity of a single replica, raising the `revalidate`
+durations is usually more effective than adding replicas: as the cache hit rate
+goes up, the work per request drops to almost zero.
+
+## Pre-release checklist
+
+- [ ] `NODE_ENV=production`
+- [ ] `npm run build` ran and produced `.jskelet/manifest.json`
+- [ ] The woff2 files under `public/fonts/` are committed
+      ([08-build.md](./08-build.md))
+- [ ] The `@source` directives in `styles/globals.css` cover all template
+      directories
+- [ ] `hooks.notFound()` is defined and there is a 404 template
+- [ ] `hooks.metadata()` contains `siteUrl` (so relative `canonical`s become
+      absolute)
+- [ ] The `cache().html` patterns match the site's freshness profile
+- [ ] `hooks.prewarmPaths()` puts the most important pages first
+- [ ] CSP and security headers are defined in `headers()`
+- [ ] A health check endpoint exists and is in the `devGateBypass` list
+- [ ] `DEV_TOKEN` is set on staging and **not set** in production
+- [ ] The reverse proxy forwards `Accept-Encoding` and does not do its own
+      compression
+- [ ] There are no secret keys in the `clientEnv` list
+
+## What's next
+
+- Cache settings and prewarm: [06-caching.md](./06-caching.md)
+- All environment variables: [07-configuration.md](./07-configuration.md)
+- Migrating from Next.js: [11-migration.md](./11-migration.md)

package/docs/en/11-migration.md

@@ -0,0 +1,360 @@
+# 11 — Migrating from Next.js
+
+This document explains how to move a project using the Next.js App Router over
+to JSkelet: a table of concept and API equivalents, an explicit list of what
+cannot be migrated, and a step-by-step plan. JSkelet's surface was deliberately
+modeled on the subset of Next that people actually use — concepts like the
+`next.config` syntax, the Metadata API, `notFound()`, `revalidate` and `cache()`
+will feel familiar. The *reasons* behind the differences are in
+[02-architecture.md](./02-architecture.md).
+
+## Equivalence table
+
+### Configuration
+
+| Next.js | JSkelet | Note |
+| --- | --- | --- |
+| `next.config.mjs` | `jskelet.config.mjs` | Same spirit, smaller surface ([07](./07-configuration.md)) |
+| `headers()` | `headers()` | Same shape: `{ source, headers: [{ key, value }] }` |
+| `redirects()` | `redirects()` | `permanent` → 308, otherwise 307; can be overridden with `statusCode` |
+| `rewrites()` | `rewrites()` | There are `beforeFiles` / `afterFiles` phases; no `fallback` |
+| `compress: true` | Automatic | brotli + gzip via `node:zlib` |
+| `images.deviceSizes` | `images.widths` | Build-time webp generation ([08](./08-build.md)) |
+| `NEXT_PUBLIC_*` | `clientEnv: [...]` | Which key is exposed is clear from the config, not from the name |
+| `experimental.*` | — | None |
+
+### Routing and rendering
+
+| Next.js | JSkelet | Note |
+| --- | --- | --- |
+| `app/page.js` (file-based routing) | `app.get(...)` inside `routes/*.mjs` | The order is written explicitly ([03](./03-routing.md)) |
+| `app/[slug]/page.js` | `app.get("/:slug", route(...))` | Express pattern syntax |
+| `params`, `searchParams` | `ctx.params`, `ctx.query` | The controller's single argument |
+| `layout.js` | `views/layout.ejs` + `hooks.layoutContext()` | A single layout; no nested layouts |
+| Server component (RSC) | Controller + EJS template + `views/components/**` | A function returns an HTML string |
+| Client component (`"use client"`) | Island (`data-island` + `mount`) | The whole page is not hydrated ([05](./05-islands.md)) |
+| `notFound()` | `notFound()` | Same name, same control flow |
+| `redirect()` | `redirect()` (307) | For permanent, `permanentRedirect()` (308) |
+| `not-found.js` | `hooks.notFound()` | Returns a page definition |
+| `error.js` | Express error handler | The framework returns minimal HTML for a 500 |
+| `loading.js` / Suspense | — | The server HTML is complete; no skeleton needed |
+| Streaming SSR | — | The response is a single chunk |
+| `generateMetadata()` | Controller `metadata` + `hooks.metadata()` | Same field names ([04](./04-rendering.md)) |
+| `generateStaticParams()` | `hooks.prewarmPaths()` | Warming at startup time, not build time |
+| Route Handlers (`route.js`) | A plain Express handler | `app.get/post(...)` |
+| Middleware (`middleware.ts`) | Express middleware + config `rewrites`/`headers`/`redirects` | `app.use(...)` |
+
+### Data and cache
+
+| Next.js | JSkelet | Note |
+| --- | --- | --- |
+| `export const revalidate = 60` | `route(controller, { revalidate: 60 })` | Or `cache().html` ([06](./06-caching.md)) |
+| ISR (prerender written to disk) | In-memory TTL cache + stale-while-revalidate | Nothing is written to disk |
+| `fetch(..., { next: { revalidate } })` | — | The cache is at page level |
+| `unstable_cache` | — | No cross-request data cache; there is a page cache |
+| React `cache()` | `cache()` | Same behavior: in-request memoization |
+| `revalidatePath()` | `clearHtmlCache()` | There is currently no per-key invalidation |
+| `cookies()`, `headers()` | `ctx.req.headers`, `ctx.req.cookies`* | Direct access to the Express object |
+| `dynamic = "force-dynamic"` | Not passing `revalidate` | Which means the cache is off |
+
+\* Express 5 does not parse cookies on its own; add `cookie-parser` or read the
+header manually.
+
+### Components and helpers
+
+| Next.js | JSkelet | Note |
+| --- | --- | --- |
+| `next/link` | `link({ href, text })` — `jskelet/tags` | `title` automatic, `rel`/`target` automatic for external links |
+| `next/link` prefetching | `navigation: { prefetch, prerender }` | Speculation Rules; no client runtime ([07](./07-configuration.md)) |
+| `next/image` | `image({ src, alt, priority })` — `jskelet/tags` | `srcset` from the build manifest |
+| `next/font/google` | `fonts: [{ family, weights }]` | Self-hosted woff2, committed |
+| `@phosphor-icons/react` | `icon({ name, weight })` — `jskelet/tags` | Build-time SVG sprite |
+| `react-dom` preconnect/preload | `preconnect: [...]` + `headHints()` | ([04](./04-rendering.md)) |
+| `clsx` | `cx()` — `jskelet/html` | — |
+| `cn()` (clsx + tailwind-merge) | `cn()` — `jskelet/html` | Same behavior |
+| JSX automatic escaping | `esc()` — `jskelet/html` | **You have to call it yourself** |
+| React Context | `createStore()` — `jskelet/client` | Minimal pub/sub |
+| `useState` / `useEffect` | Plain JS inside the island's `mount()` | — |
+| `useSyncExternalStore` | `store.subscribe()` | — |
+| `<Script>` | A `<script>` in the layout, or an island | — |
+
+### What has no equivalent
+
+Account for these from the start in your migration plan:
+
+- **React itself.** Components turn into functions that return HTML strings. No
+  JSX, no hooks, no virtual DOM.
+- **TypeScript.** The project is plain JS + JSDoc. With `checkJs: true` in
+  `jsconfig.json` you get type checking from the editor.
+- **Nested layouts.** There is a single layout; you share common sections with
+  EJS `include` or component functions.
+- **Streaming / Suspense / partial prerendering.** The response is produced as a
+  single chunk.
+- **Client-side routing.** Navigation is a real page load. Because the server
+  HTML comes from the cache it is very fast in practice, but there are no SPA
+  transitions. What closes the gap is the `navigation` section:
+  prefetch/prerender prepares the document before the click, and
+  `viewTransition` smooths the transition
+  ([07](./07-configuration.md)).
+- **Server Actions.** Form submissions are ordinary `app.post(...)` handlers.
+- **Per-path invalidation (`revalidatePath`).** For now there is clearing the
+  whole cache (`clearHtmlCache()`) or waiting for the TTL to expire.
+- **Automatic image optimization (at request time).** Optimization happens at
+  build time and only covers local images under `public/`; remote images are
+  emitted as-is.
+
+## A side-by-side example
+
+**Next.js (App Router):**
+
+```jsx
+// app/news/[slug]/page.jsx
+import { notFound } from "next/navigation";
+import Image from "next/image";
+import { getArticle } from "@/lib/api";
+
+export const revalidate = 300;
+
+export async function generateMetadata({ params }) {
+  const article = await getArticle(params.slug);
+  return {
+    title: article?.title,
+    description: article?.summary,
+    alternates: { canonical: `/news/${params.slug}` },
+  };
+}
+
+export default async function Page({ params }) {
+  const article = await getArticle(params.slug);
+  if (!article) notFound();
+
+  return (
+    <article className="wrapper">
+      <h1 className="text-3xl font-bold">{article.title}</h1>
+      <Image src={article.cover} alt={article.title} priority width={1200} height={630} />
+      <div dangerouslySetInnerHTML={{ __html: article.body }} />
+    </article>
+  );
+}
+```
+
+**JSkelet:**
+
+```js
+// routes/50-news.mjs
+import { getArticle } from "@/lib/api.js";
+
+export default function register(app, { route, notFound }) {
+  app.get(
+    "/news/:slug",
+    route(
+      async ({ params }) => {
+        const article = await getArticle(params.slug);
+        if (!article) notFound();
+
+        return {
+          view: "pages/article",
+          data: { article },
+          metadata: {
+            title: article.title,
+            description: article.summary,
+            canonical: `/news/${params.slug}`,
+            openGraph: { type: "article", image: article.cover },
+          },
+        };
+      },
+      { revalidate: 300 },
+    ),
+  );
+}
+```
+
+```ejs
+<%# views/pages/article.ejs %>
+<article class="wrapper">
+  <h1 class="text-3xl font-bold"><%= article.title %></h1>
+  <%- image({ src: article.cover, alt: article.title, priority: true, width: 1200, height: 630 }) %>
+  <div><%- article.body %></div>
+</article>
+```
+
+Wrapping `getArticle` with `cache()` makes sure that if
+`hooks.layoutContext()` asks for the same article in the same render, only a
+single upstream request is made ([06-caching.md](./06-caching.md)).
+
+## Step-by-step plan
+
+### 1. Set up the skeleton (half a day)
+
+Run `npx jskelet init` in a new directory and watch `jskelet dev` come up. Leave
+the existing Next project as it is; let the migration run in parallel.
+
+Carry over the `paths` aliases from your `jsconfig.json` — prefixes like `@/`
+work the same way both on the server and in the bundle
+([02-architecture.md](./02-architecture.md)).
+
+### 2. Translate `next.config.mjs` (1-2 hours)
+
+The `headers()`, `redirects()` and `rewrites()` sections are copied almost
+verbatim. Check the pattern syntax: JSkelet supports the `:slug`, `:path*`,
+`/a-:b` and `/:path*.svg` forms; more complex `path-to-regexp` expressions are
+not supported and produce a warning ([07-configuration.md](./07-configuration.md)).
+
+Move your `NEXT_PUBLIC_*` variables into the `clientEnv` list and simplify their
+names (the prefix no longer carries meaning).
+
+### 3. Move the data layer (the easiest step)
+
+The API client and data functions under `lib/` usually do not depend on React;
+they are copied as-is. Make two changes:
+
+- Use `import { cache } from "jskelet"` instead of React's `cache()`.
+- Call `reportUpstreamFailure({ status, path })` on failed upstream responses.
+  This prevents pages produced with missing data from being written to the cache
+  ([06-caching.md](./06-caching.md)).
+
+### 4. Set up the layout (half a day)
+
+Translate `app/layout.jsx` into `views/layout.ejs`. Copying the framework's
+default layout (`node_modules/jskelet/src/templates/layout.ejs`) and editing it
+is the fastest path.
+
+If you fetch data inside `layout.jsx` (navigation, site settings), move it into
+`hooks.layoutContext()`: it runs in parallel with the body render, and every
+field it returns becomes a layout local.
+
+Put your global metadata defaults (`titleTemplate`, `siteUrl`, `description`)
+into `hooks.metadata()`.
+
+### 5. Translate the components (the longest step)
+
+Every React component turns into a function:
+
+```jsx
+// Before
+export function Badge({ label, tone = "neutral", className }) {
+  return <span className={cn("rounded px-2 py-1", TONES[tone], className)}>{label}</span>;
+}
+```
+
+```js
+// After — views/components/badge.js
+import { attrs, cn, esc } from "jskelet/html";
+
+export function badge({ label, tone = "neutral", class: className }) {
+  return `<span${attrs({ class: cn("rounded px-2 py-1", TONES[tone], className) })}>${esc(label)}</span>`;
+}
+```
+
+Things to watch out for:
+
+- **Escaping is now on you.** JSX escaped automatically; here you must call
+  `esc()` when printing external data.
+- **`className` → `class`.** Since `class` is a reserved word in JS, rename it in
+  the props as `class: className`.
+- **An `html` field instead of children.** Nested content is passed as a string.
+- Every function you place under `views/components/**` as a named export can be
+  used in templates without importing it
+  ([04-rendering.md](./04-rendering.md)).
+
+Keep components small and pure; leave data fetching in the controller.
+
+### 6. Migrate the pages (hours per page)
+
+Every `page.jsx` splits into a controller plus an EJS template. File them with
+the order in mind:
+
+```
+routes/
+├── 00-health.mjs        health check
+├── 10-pages.mjs         static paths: /, /about
+├── 50-news.mjs          /news/:slug
+└── 99-catch-all.mjs     /:slug  (if any, last of all)
+```
+
+The places where you used `generateStaticParams()` turn into
+`hooks.prewarmPaths()`. If you have a function that produces the sitemap, use
+the same one.
+
+Move your `export const revalidate` values either into `route()`'s second
+argument or, to manage them from a single place, into `cache().html` patterns.
+
+### 7. Turn client components into islands (hours per page)
+
+Every `"use client"` component becomes an island. The process:
+
+1. Move the component's **static** output into the server template. Everything
+   visible on first render must be in the HTML.
+2. Write the remaining behavior inside `mount(element, props)`: `useState`
+   becomes a local variable, `useEffect` a direct call, event handlers
+   `on()`/`onClick()`.
+3. Pass props as JSON with `data-island-props`.
+4. Add it to the `registerAll()` map in the entry.
+5. Choose the binding strategy: the default (visibility), `data-island-eager`
+   (global behavior) or `data-island-idle` (heavy and non-critical).
+
+For components using Context, `createStore()` is the closest equivalent
+([05-islands.md](./05-islands.md)).
+
+**This is where the biggest win of this step lies:** the hydrated area is not
+the whole page, only the parts that are genuinely interactive.
+
+### 8. Move the CSS (1-2 hours)
+
+If your Tailwind configuration is already in v4 format, `styles/globals.css`
+stays almost the same. The one critical addition is the `@source` directives:
+
+```css
+@import "tailwindcss" source(none);
+
+@source "../views";
+@source "../client";
+@source "../routes";
+@source "../lib";
+```
+
+Without these, the classes used in templates (especially variants like
+`data-[state=open]:…`) are silently dropped
+([08-build.md](./08-build.md)).
+
+If you use `next/font`, add `fonts: [{ family, weights }]` and write the
+`@font-face` blocks by hand; the generated files sit under `public/fonts/` with
+stable names.
+
+### 9. Verify and measure
+
+- Browse with `jskelet dev` and confirm there are no errors in the dev overlay.
+- On the report page (`/__jskelet/dev/report`), look at each page's Web Vitals
+  measurements, SSR size and island status ([09-dev-tools.md](./09-dev-tools.md)).
+- Clear the missing-icon warnings.
+- Compare the sizes in the `jskelet build` output with your old Next bundle.
+- Check that the `X-JSkelet-Cache` header returns `HIT` on the pages you expect.
+
+### 10. Go live
+
+Go through the checklist in [10-deployment.md](./10-deployment.md). Keeping the
+old Next setup alongside for a while and shifting traffic gradually is useful,
+especially for verifying that the redirect rules are correct.
+
+## Common mistakes during migration
+
+- **Forgetting `esc()`.** Writing `${value}` out of JSX habit means XSS. In
+  templates, mind the distinction between `<%= %>` (escaped) and `<%- %>` (raw).
+- **Opening a new directory without adding `@source`.** The classes are silently
+  dropped.
+- **Putting the catch-all route in the wrong order.** `/:slug` always goes last.
+- **Making the whole page an island.** The win comes from the server HTML being
+  complete; bind the island only to the genuinely interactive part.
+- **Forgetting to pass `revalidate`.** The cache stays off, every request is
+  rendered, and `X-JSkelet-Cache: MISS` is returned.
+- **Not calling `reportUpstreamFailure()`.** When the upstream goes down, the
+  page produced with missing data is served for the entire TTL.
+- **Putting a secret key in `clientEnv`.** The values sit in the bundle as plain
+  text.
+
+## What's next
+
+- The reasons behind the architectural decisions:
+  [02-architecture.md](./02-architecture.md)
+- Details of the island model: [05-islands.md](./05-islands.md)
+- Configuration reference: [07-configuration.md](./07-configuration.md)