@depup/nitro 3.0.260311-beta-depup.0

package/skills/nitro/docs/examples/vite-ssr-vue-router.md

@@ -0,0 +1,616 @@
+# SSR with Vue Router
+
+> Server-side rendering with Vue Router in Nitro using Vite.
+
+<code-tree>
+
+```json [package.json]
+{
+  "type": "module",
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite dev",
+    "preview": "vite preview"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^6.0.4",
+    "nitro": "latest",
+    "unhead": "^2.1.3",
+    "vite": "beta",
+    "vite-plugin-devtools-json": "^1.0.0",
+    "vue": "^3.5.27",
+    "vue-router": "^4.6.4"
+  }
+}
+```
+
+```json [tsconfig.json]
+{
+  "extends": "nitro/tsconfig"
+}
+```
+
+```js [vite.config.mjs]
+import vue from "@vitejs/plugin-vue";
+import { defineConfig } from "vite";
+import devtoolsJson from "vite-plugin-devtools-json";
+import { nitro } from "nitro/vite";
+
+export default defineConfig((_env) => ({
+  plugins: [patchVueExclude(vue(), /\?assets/), devtoolsJson(), nitro()],
+  environments: {
+    client: { build: { rollupOptions: { input: "./app/entry-client.ts" } } },
+    ssr: { build: { rollupOptions: { input: "./app/entry-server.ts" } } },
+  },
+}));
+
+// Workaround https://github.com/vitejs/vite-plugin-vue/issues/677
+function patchVueExclude(plugin, exclude) {
+  const original = plugin.transform.handler;
+  plugin.transform.handler = function (...args) {
+    if (exclude.test(args[1])) return;
+    return original.call(this, ...args);
+  };
+  return plugin;
+}
+```
+
+```vue [app/app.vue]
+<script setup lang="ts">
+import { RouterLink, RouterView } from "vue-router";
+import "./styles.css";
+</script>
+
+<template>
+  <nav>
+    <ul>
+      <li>
+        <RouterLink to="/" exact-active-class="active">Home</RouterLink>
+      </li>
+      <li>
+        <RouterLink to="/about" active-class="active">About</RouterLink>
+      </li>
+    </ul>
+  </nav>
+  <RouterView />
+</template>
+
+<style scoped>
+nav {
+  background: white;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
+  padding: 1rem;
+}
+
+nav ul {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  gap: 2rem;
+  max-width: 800px;
+  margin: 0 auto;
+}
+
+nav a {
+  color: #666;
+  text-decoration: none;
+}
+
+nav a:hover {
+  color: #333;
+}
+
+nav a.active {
+  color: #646cff;
+}
+</style>
+```
+
+```ts [app/entry-client.ts]
+import { createSSRApp } from "vue";
+import { RouterView, createRouter, createWebHistory } from "vue-router";
+import { routes } from "./routes.ts";
+
+async function main() {
+  const app = createSSRApp(RouterView);
+  const router = createRouter({ history: createWebHistory(), routes });
+  app.use(router);
+
+  await router.isReady();
+  app.mount("#root");
+}
+
+// eslint-disable-next-line unicorn/prefer-top-level-await
+main();
+```
+
+```ts [app/entry-server.ts]
+import { createSSRApp } from "vue";
+import { renderToString } from "vue/server-renderer";
+import { RouterView, createMemoryHistory, createRouter } from "vue-router";
+import { createHead, transformHtmlTemplate } from "unhead/server";
+
+import { routes } from "./routes.ts";
+
+import clientAssets from "./entry-client.ts?assets=client";
+
+async function handler(request: Request): Promise<Response> {
+  const app = createSSRApp(RouterView);
+  const router = createRouter({ history: createMemoryHistory(), routes });
+  app.use(router);
+
+  const url = new URL(request.url);
+  const href = url.href.slice(url.origin.length);
+
+  await router.push(href);
+  await router.isReady();
+
+  const assets = clientAssets.merge(
+    ...(await Promise.all(
+      router.currentRoute.value.matched
+        .map((to) => to.meta.assets)
+        .filter(Boolean)
+        .map((fn) => (fn as any)().then((m: any) => m.default))
+    ))
+  );
+
+  const head = createHead();
+
+  head.push({
+    link: [
+      ...assets.css.map((attrs: any) => ({ rel: "stylesheet", ...attrs })),
+      ...assets.js.map((attrs: any) => ({ rel: "modulepreload", ...attrs })),
+    ],
+    script: [{ type: "module", src: clientAssets.entry }],
+  });
+
+  const renderedApp = await renderToString(app);
+
+  const html = await transformHtmlTemplate(head, htmlTemplate(renderedApp));
+
+  return new Response(html, {
+    headers: { "Content-Type": "text/html;charset=utf-8" },
+  });
+}
+
+function htmlTemplate(body: string): string {
+  return /* html */ `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Vue Router Custom Framework</title>
+</head>
+<body>
+  <div id="root">${body}</div>
+</body>
+</html>`;
+}
+
+export default {
+  fetch: handler,
+};
+```
+
+```ts [app/routes.ts]
+import type { RouteRecordRaw } from "vue-router";
+
+export const routes: RouteRecordRaw[] = [
+  {
+    path: "/",
+    name: "app",
+    component: () => import("./app.vue"),
+    meta: {
+      assets: () => import("./app.vue?assets"),
+    },
+    children: [
+      {
+        path: "/",
+        name: "home",
+        component: () => import("./pages/index.vue"),
+        meta: {
+          assets: () => import("./pages/index.vue?assets"),
+        },
+      },
+      {
+        path: "/about",
+        name: "about",
+        component: () => import("./pages/about.vue"),
+        meta: {
+          assets: () => import("./pages/about.vue?assets"),
+        },
+      },
+      {
+        path: "/:catchAll(.*)",
+        name: "not-found",
+        component: () => import("./pages/not-found.vue"),
+        meta: {
+          assets: () => import("./pages/not-found.vue?assets"),
+        },
+      },
+    ],
+  },
+];
+```
+
+```ts [app/shims.d.ts]
+declare module "*.vue" {
+  import type { DefineComponent } from "vue";
+  const component: DefineComponent<{}, {}, any>;
+  export default component;
+}
+```
+
+```css [app/styles.css]
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  background: #f5f5f5;
+  color: #333;
+}
+
+main {
+  max-width: 800px;
+  margin: 0 auto;
+  padding: 2rem;
+}
+
+h1 {
+  font-size: 2.5rem;
+  margin-bottom: 0.5rem;
+}
+
+.card {
+  background: white;
+  border-radius: 8px;
+  padding: 2rem;
+  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+  margin: 2rem 0;
+}
+
+button {
+  background: rgb(83, 91, 242);
+  color: white;
+  border: none;
+  padding: 0.5rem 1rem;
+  border-radius: 4px;
+  font-size: 1rem;
+  cursor: pointer;
+}
+
+button:hover {
+  background: #535bf2;
+}
+
+.subtitle {
+  color: #666;
+  font-size: 1.1rem;
+  margin-bottom: 2rem;
+}
+```
+
+```vue [app/pages/about.vue]
+<template>
+  <main>
+    <h1>About</h1>
+    <div class="card">
+      <p>This is a simple Vue Router demo app built with Vite Plugin Fullstack.</p>
+      <p>It demonstrates basic routing and server-side rendering.</p>
+    </div>
+  </main>
+</template>
+```
+
+```vue [app/pages/index.vue]
+<script setup lang="ts">
+import { ref } from "vue";
+
+const count = ref(0);
+
+function increment() {
+  count.value++;
+}
+</script>
+
+<template>
+  <main>
+    <div class="hero">
+      <h1>Vue Router Custom Framework</h1>
+      <p class="subtitle">A simple demo app with Vite</p>
+    </div>
+
+    <div class="card counter-card">
+      <p>Count: {{ count }}</p>
+      <button @click="increment">Increment</button>
+    </div>
+  </main>
+</template>
+
+<style scoped>
+.hero {
+  text-align: center;
+  margin-bottom: 2rem;
+}
+
+.hero h1 {
+  color: rgb(100, 108, 255);
+}
+
+.counter-card {
+  text-align: center;
+}
+
+.counter-card h2 {
+  color: #646cff;
+  margin-bottom: 1rem;
+}
+
+.counter-card p {
+  font-size: 1.5rem;
+  font-weight: bold;
+  margin: 1rem 0;
+}
+</style>
+```
+
+```vue [app/pages/not-found.vue]
+<template>
+  <main>
+    <h1>Not Found 404</h1>
+  </main>
+</template>
+```
+</code-tree>
+
+Set up server-side rendering (SSR) with Vue, Vue Router, Vite, and Nitro. This setup enables per-route code splitting, head management with unhead, and client hydration.
+
+## Overview
+
+1. Add the Nitro Vite plugin to your Vite config
+2. Define routes with lazy-loaded components
+3. Create a server entry that renders your app with router support
+4. Create a client entry that hydrates and takes over routing
+5. Create page components
+
+## 1. Configure Vite
+Add the Nitro and Vue plugins to your Vite config. Define both `client` and `ssr` environments:
+
+```js [vite.config.mjs]
+import vue from "@vitejs/plugin-vue";
+import { defineConfig } from "vite";
+import devtoolsJson from "vite-plugin-devtools-json";
+import { nitro } from "nitro/vite";
+
+export default defineConfig((_env) => ({
+  plugins: [patchVueExclude(vue(), /\?assets/), devtoolsJson(), nitro()],
+  environments: {
+    client: { build: { rollupOptions: { input: "./app/entry-client.ts" } } },
+    ssr: { build: { rollupOptions: { input: "./app/entry-server.ts" } } },
+  },
+}));
+
+// Workaround https://github.com/vitejs/vite-plugin-vue/issues/677
+function patchVueExclude(plugin, exclude) {
+  const original = plugin.transform.handler;
+  plugin.transform.handler = function (...args) {
+    if (exclude.test(args[1])) return;
+    return original.call(this, ...args);
+  };
+  return plugin;
+}
+```
+
+The `patchVueExclude` helper prevents the Vue plugin from processing asset imports (files with `?assets` query parameter).
+
+## 2. Define Routes
+
+Create route definitions with lazy-loaded components and asset metadata:
+
+```ts [app/routes.ts]
+import type { RouteRecordRaw } from "vue-router";
+
+export const routes: RouteRecordRaw[] = [
+  {
+    path: "/",
+    name: "app",
+    component: () => import("./app.vue"),
+    meta: {
+      assets: () => import("./app.vue?assets"),
+    },
+    children: [
+      {
+        path: "/",
+        name: "home",
+        component: () => import("./pages/index.vue"),
+        meta: {
+          assets: () => import("./pages/index.vue?assets"),
+        },
+      },
+      {
+        path: "/about",
+        name: "about",
+        component: () => import("./pages/about.vue"),
+        meta: {
+          assets: () => import("./pages/about.vue?assets"),
+        },
+      },
+      {
+        path: "/:catchAll(.*)",
+        name: "not-found",
+        component: () => import("./pages/not-found.vue"),
+        meta: {
+          assets: () => import("./pages/not-found.vue?assets"),
+        },
+      },
+    ],
+  },
+];
+```
+
+Use dynamic imports for lazy-loaded components to enable code splitting. The `meta.assets` function loads route-specific CSS and JS chunks. Define child routes under a root layout component for nested routing.
+
+## 3. Create the Server Entry
+
+The server entry renders your Vue app with router support and head management:
+
+```ts [app/entry-server.ts]
+import { createSSRApp } from "vue";
+import { renderToString } from "vue/server-renderer";
+import { RouterView, createMemoryHistory, createRouter } from "vue-router";
+import { createHead, transformHtmlTemplate } from "unhead/server";
+
+import { routes } from "./routes.ts";
+
+import clientAssets from "./entry-client.ts?assets=client";
+
+async function handler(request: Request): Promise<Response> {
+  const app = createSSRApp(RouterView);
+  const router = createRouter({ history: createMemoryHistory(), routes });
+  app.use(router);
+
+  const url = new URL(request.url);
+  const href = url.href.slice(url.origin.length);
+
+  await router.push(href);
+  await router.isReady();
+
+  const assets = clientAssets.merge(
+    ...(await Promise.all(
+      router.currentRoute.value.matched
+        .map((to) => to.meta.assets)
+        .filter(Boolean)
+        .map((fn) => (fn as any)().then((m: any) => m.default))
+    ))
+  );
+
+  const head = createHead();
+
+  head.push({
+    link: [
+      ...assets.css.map((attrs: any) => ({ rel: "stylesheet", ...attrs })),
+      ...assets.js.map((attrs: any) => ({ rel: "modulepreload", ...attrs })),
+    ],
+    script: [{ type: "module", src: clientAssets.entry }],
+  });
+
+  const renderedApp = await renderToString(app);
+
+  const html = await transformHtmlTemplate(head, htmlTemplate(renderedApp));
+
+  return new Response(html, {
+    headers: { "Content-Type": "text/html;charset=utf-8" },
+  });
+}
+
+function htmlTemplate(body: string): string {
+  return /* html */ `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Vue Router Custom Framework</title>
+</head>
+<body>
+  <div id="root">${body}</div>
+</body>
+</html>`;
+}
+
+export default {
+  fetch: handler,
+};
+```
+
+The server uses `createMemoryHistory()` since there's no browser URL bar—the router navigates to the requested URL before rendering. Assets are loaded dynamically based on matched routes, ensuring only the CSS and JS needed for the current page are included. The `unhead` library manages `<head>` elements, injecting stylesheets and scripts via `transformHtmlTemplate`.
+
+## 4. Create the Client Entry
+
+The client entry hydrates the server-rendered HTML and takes over routing:
+
+```ts [app/entry-client.ts]
+import { createSSRApp } from "vue";
+import { RouterView, createRouter, createWebHistory } from "vue-router";
+import { routes } from "./routes.ts";
+
+async function main() {
+  const app = createSSRApp(RouterView);
+  const router = createRouter({ history: createWebHistory(), routes });
+  app.use(router);
+
+  await router.isReady();
+  app.mount("#root");
+}
+
+// eslint-disable-next-line unicorn/prefer-top-level-await
+main();
+```
+
+The client entry creates a Vue app with `createWebHistory()` for browser-based routing. After the router is ready, it mounts to the `#root` element and hydrates the server-rendered HTML.
+
+## 5. Create the Root Component
+
+The root component provides navigation and renders child routes:
+
+```vue [app/app.vue]
+<script setup lang="ts">
+import { RouterLink, RouterView } from "vue-router";
+import "./styles.css";
+</script>
+
+<template>
+  <nav>
+    <ul>
+      <li>
+        <RouterLink to="/" exact-active-class="active">Home</RouterLink>
+      </li>
+      <li>
+        <RouterLink to="/about" active-class="active">About</RouterLink>
+      </li>
+    </ul>
+  </nav>
+  <RouterView />
+</template>
+
+<style scoped>
+nav {
+  background: white;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
+  padding: 1rem;
+}
+
+nav ul {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  gap: 2rem;
+  max-width: 800px;
+  margin: 0 auto;
+}
+
+nav a {
+  color: #666;
+  text-decoration: none;
+}
+
+nav a:hover {
+  color: #333;
+}
+
+nav a.active {
+  color: #646cff;
+}
+</style>
+```
+
+## Learn More
+
+- [Vue Router Documentation](https://router.vuejs.org/)
+- [Unhead Documentation](https://unhead.unjs.io/)
+- [Renderer](/docs/renderer)
+- [Server Entry](/docs/server-entry)