docs: prepare for v3 beta (#4091)

Author: pi0

.agents/docs.md

@@ -152,3 +152,6 @@ For deeper context, see `.agents/`:
 - [`.agents/presets.md`](.agents/presets.md) — All 31 presets, preset structure, how to create presets, resolution logic.
 - [`.agents/testing.md`](.agents/testing.md) — Test structure, how tests work, adding regression tests, running tests.
 - [`.agents/vite.md`](.agents/vite.md) — Vite build system: plugin architecture (6 sub-plugins), environments API, dev server integration, production build stages, bundler config, HMR, runtime worker.
+- [`.agents/docs.md`](.agents/docs.md) — Documentation conventions: structure, preset naming (underscore), H3 v2 API patterns, import paths, common mistakes.
+
+- **Important:** H3 v2 updated docs is at `node_modules/h3/skills/h3/docs/TOC.md`

AGENTS.md

@@ -10,11 +10,34 @@ socials:
   discord: https://discord.nitro.build
 sponsors:
   api: https://sponsors.pi0.io/sponsors.json
+redirects:
+  # v2 guide → v3 docs
+  "/guide": "/docs"
+  "/guide/getting-started": "/docs"
+  "/guide/utils": "/docs/routing"
+  "/guide/routing": "/docs/routing"
+  "/guide/websocket": "/docs/routing"
+  "/guide/cache": "/docs/cache"
+  "/guide/storage": "/docs/storage"
+  "/guide/database": "/docs/database"
+  "/guide/fetch": "/docs/routing"
+  "/guide/assets": "/docs/assets"
+  "/guide/plugins": "/docs/plugins"
+  "/guide/configuration": "/docs/configuration"
+  "/guide/typescript": "/docs/configuration"
+  "/guide/tasks": "/docs/tasks"
+  "/guide/nightly": "/docs/nightly"
+  # v2 deploy
+  "/deploy/workers": "/deploy"
+  "/deploy/runtimes/winterjs": "/deploy"
+  "/deploy/custom-presets": "/deploy"
+  "/deploy/providers/edgio": "/deploy"
+  "/deploy/node": "/deploy/runtimes/node"
 themeColor: "rose"
 automd: true
 branch: main
 versions:
-  - label: "v3 (alpha)"
+  - label: "v3 (beta)"
     active: true
   - label: "v2"
     to: "https://nitro.build"

docs/.config/docs.yaml

@@ -0,0 +1,11 @@
+import { defineAppConfig } from "#imports"
+
+export default defineAppConfig({
+  ui: {
+    button: {
+      slots: {
+        base: 'active:translate-y-px transition-transform duration-300',
+      },
+    },
+  },
+})

docs/.docs/app.config.ts

@@ -0,0 +1,23 @@
+:root {
+  --font-sans: "Geist", sans-serif !important;
+  --font-mono: "Geist Mono", monospace !important;
+}
+
+h1[data-slot="title"] {
+  font-family: "Geist Pixels", sans-serif !important;
+}
+
+.landing-code {
+  --ui-bg-muted: #0c0c0e;
+  --ui-border-muted: #27272a;
+  --ui-bg: #0c0c0e;
+}
+
+.landing-code pre[style] {
+  background-color: #0c0c0e !important;
+}
+
+.landing-code > div > div {
+  margin-top: 0;
+  margin-bottom: 0;
+}

docs/.docs/assets/css/main.css

@@ -0,0 +1,62 @@
+<script setup lang="ts">
+defineProps<{
+  title: string
+  description: string
+  primaryLink: string
+  primaryLabel: string
+  githubLink: string
+  codeGroups: {
+    filename: string
+    code: string
+  }[]
+}>()
+</script>
+
+<template>
+  <UPageHero orientation="horizontal">
+    <template #default>
+      <div class="code-group">
+        <ProseCodeGroup>
+          <ProsePre
+            v-for="group in codeGroups"
+            :key="group.filename"
+            :filename="group.filename"
+            language="ts"
+          >
+            <pre>{{ group.code }}</pre>
+          </ProsePre>
+        </ProseCodeGroup>
+      </div>
+    </template>
+
+    <HeroBackground />
+
+    <template #title>
+      <span v-html="title" />
+    </template>
+
+    <template #description>
+      {{ description }}
+    </template>
+
+    <template #links>
+      <UButton
+        size="xl"
+        :to="primaryLink"
+        trailing-icon="i-lucide-arrow-right"
+      >
+        {{ primaryLabel }}
+      </UButton>
+      <UButton
+        color="neutral"
+        icon="i-simple-icons-github"
+        size="xl"
+        target="_blank"
+        :to="githubLink"
+        variant="outline"
+      >
+        GitHub
+      </UButton>
+    </template>
+  </UPageHero>
+</template>

docs/.docs/assets/fonts/GeistPixel-Square.woff2

@@ -0,0 +1,49 @@
+<template>
+  <div class="flex flex-wrap items-center justify-center gap-4">
+    <UButton
+      size="xl"
+      to="/docs/quick-start"
+      trailing-icon="i-lucide-arrow-right"
+    >
+      Get started
+    </UButton>
+    <UButton
+      color="neutral"
+      icon="i-simple-icons-github"
+      size="xl"
+      target="_blank"
+      to="https://github.com/nitrojs/nitro"
+      variant="outline"
+    >
+      Star on GitHub
+    </UButton>
+    <a
+      :href="`${baseURL}llms.txt`"
+      target="_blank"
+      class="basis-full text-sm text-muted hover:text-default transition-colors inline-flex items-center justify-center gap-1"
+      @click.prevent="copyPrompt"
+    >
+      <UIcon :name="copied ? 'i-lucide-clipboard-check' : 'i-lucide-bot'" />
+      Docs for AI
+    </a>
+  </div>
+</template>
+
+<script setup lang="ts">
+const copied = ref(false)
+const baseURL = computed(() => {
+  if (import.meta.client) {
+    return `${window.location.origin}/`
+  }
+  return '/'
+})
+
+function copyPrompt() {
+  const text = `Read nitro docs from ${baseURL.value}docs/quick-start so I can ask questions about it.`
+  navigator.clipboard.writeText(text)
+  copied.value = true
+  setTimeout(() => {
+    copied.value = false
+  }, 2000)
+}
+</script>

docs/.docs/components/AppHero.vue

@@ -0,0 +1,51 @@
+<script setup lang="ts">
+import { Motion } from 'motion-v'
+
+defineProps<{
+  headline?: string
+  link?: string
+  linkLabel?: string
+}>()
+
+const prefersReducedMotion = ref(false)
+
+onMounted(() => {
+  prefersReducedMotion.value = window.matchMedia('(prefers-reduced-motion: reduce)').matches
+})
+</script>
+
+<template>
+  <Motion
+    :initial="prefersReducedMotion ? { opacity: 1 } : { opacity: 0, y: 20 }"
+    :while-in-view="{ opacity: 1, y: 0 }"
+    :transition="{ duration: 0.5 }"
+    :in-view-options="{ once: true }"
+  >
+    <NuxtLink :to="link" class="block h-full" :class="link ? 'cursor-pointer' : 'cursor-default'">
+      <div class="relative overflow-hidden rounded-xl border border-default bg-white/60 dark:bg-neutral-900/60 backdrop-blur-sm p-8 h-full transition-all duration-300 hover:shadow-lg hover:-translate-y-1">
+        <div v-if="headline" class="text-xs font-mono uppercase tracking-widest text-primary mb-4 flex items-center gap-2">
+          <span class="inline-block w-1 h-1 rounded-full bg-primary" />
+          {{ headline }}
+        </div>
+
+        <h3 class="text-2xl font-bold text-neutral-900 dark:text-white mb-3 tracking-tight">
+          <slot name="title" />
+        </h3>
+
+        <p class="text-neutral-500 dark:text-neutral-400 text-sm leading-relaxed mb-6">
+          <slot name="description" />
+        </p>
+
+        <slot name="demo" />
+
+        <span
+          v-if="link"
+          class="inline-flex items-center gap-1 text-sm text-primary mt-auto"
+        >
+          {{ linkLabel || 'Learn more' }}
+          <UIcon name="i-lucide-arrow-right" class="size-4" />
+        </span>
+      </div>
+    </NuxtLink>
+  </Motion>
+</template>

docs/.docs/components/AppHeroLinks.vue

@@ -1,9 +1,23 @@
 <script setup lang="ts">
-import { Shader, ChromaFlow } from 'shaders/vue'
+import { ref, onMounted, defineAsyncComponent } from 'vue'
+
+const Shader = defineAsyncComponent(() => import('shaders/vue').then(m => m.Shader))
+const ChromaFlow = defineAsyncComponent(() => import('shaders/vue').then(m => m.ChromaFlow))
+
+const enabled = ref(false)
+
+onMounted(() => {
+  const isMobile = /Android|iPhone|iPad|iPod/i.test(navigator.userAgent) || window.innerWidth < 768
+  const hasWebGPU = 'gpu' in navigator
+  const lowMemory = (navigator as any).deviceMemory !== undefined && (navigator as any).deviceMemory < 4
+  const lowCores = navigator.hardwareConcurrency !== undefined && navigator.hardwareConcurrency < 4
+
+  enabled.value = hasWebGPU && !isMobile && !lowMemory && !lowCores
+})
 </script>
 
 <template>
-  <Shader class="absolute inset-0 w-full h-full -z-10">
+  <Shader v-if="enabled" class="absolute inset-0 w-full h-full -z-10">
     <ChromaFlow
       base-color="oklch(71.2% 0.194 13.428)"
       up-color="oklch(70.2% 0.183 293.541)"