void 0.1.6 → 0.7.0

package/skills/void/docs/guide/pages-routing/overview.md

@@ -0,0 +1,236 @@
+---
+outline: deep
+---
+
+# Pages Routing
+
+Pages routing provides the server-rendered, components-as-pages, collocated-data-loading routing system that is seen in many existing JavaScript meta frameworks. However, pages routing in Void is different from most in that it is **rendering framework agnostic.** It is built on patterns inspired by [Inertia.js](https://inertiajs.com/): The server returns the data, and the component receives it as props. The client-side routing logic is minimal, allowing Void to support any rendering framework Vite can support. Today, React, Vue, Svelte, and Solid have first-party adapters.
+
+Pages mode activates when a `pages/` directory exists. It coexists with `routes/`. Use `pages/` for UI pages and `routes/` for APIs. Components in `pages/` are server-rendered, which means **they run in both Cloudflare Workers and browsers**.
+
+Pages mode is also entirely optional - you can use any client-side router to build a pure client-side SPA that interacts with the backend API via the [typed fetch](../typed-fetch.md) utility.
+
+## Setup
+
+If you start in a scaffoldable empty directory, `void init` can generate this setup for you: it asks whether you want React, Vue, Svelte, or Solid Pages mode, then lets you pick a D1 starter, a PostgreSQL starter, or Static Pages. The database-backed starters write the adapter-aware `vite.config.ts`, `pages/`, and `db/` starter files; Static Pages writes just the basic `pages/` setup so you can grow into server features later.
+
+If you're adding Pages mode manually, install a framework adapter alongside `void`:
+
+::: code-group
+
+```sh [React]
+npm install @void/react
+```
+
+```sh [Vue]
+npm install @void/vue
+```
+
+```sh [Svelte]
+npm install @void/svelte
+```
+
+```sh [Solid]
+npm install @void/solid
+```
+
+:::
+
+Add both plugins to your Vite config:
+
+::: code-group
+
+```ts [React]
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { voidPlugin } from 'void';
+import { voidReact } from '@void/react/plugin';
+
+export default defineConfig({
+  plugins: [voidPlugin(), voidReact()],
+});
+```
+
+```ts [Vue]
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { voidPlugin } from 'void';
+import { voidVue } from '@void/vue/plugin';
+
+export default defineConfig({
+  plugins: [voidPlugin(), voidVue()],
+});
+```
+
+```ts [Svelte]
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { voidPlugin } from 'void';
+import { voidSvelte } from '@void/svelte/plugin';
+
+export default defineConfig({
+  plugins: [voidPlugin(), voidSvelte()],
+});
+```
+
+```ts [Solid]
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { voidPlugin } from 'void';
+import { voidSolid } from '@void/solid/plugin';
+
+export default defineConfig({
+  plugins: [voidPlugin(), voidSolid()],
+});
+```
+
+:::
+
+That is the full setup. You do not need an SSR entry, a client entry, or hydration boilerplate because the adapter generates them for you.
+
+Each adapter plugin includes the framework's Vite plugin (`@vitejs/plugin-react`, `@vitejs/plugin-vue`, `@sveltejs/vite-plugin-svelte`, `vite-plugin-solid`) so you don't need to install or configure it separately. Pass framework plugin options via `voidReact({ react: { ... } })`, `voidVue({ vue: { ... } })`, `voidSvelte({ svelte: { ... } })`, or `voidSolid({ solid: { ... } })` if needed.
+
+## Directory Structure
+
+Pages can be flat files such as `about.vue` or directory-based routes such as `about/index.vue`. Both map to the same route:
+
+<PagesFileTree />
+
+Each page can have a companion `.server.ts` file that runs exclusively on the server. It can export:
+
+- A [**loader**](./loaders), which runs on `GET` and returns the data that becomes the page component's props
+- [**Actions**](./actions-and-forms), which handle mutations from forms and programmatic calls. Export a single `action` or multiple [named actions](./actions-and-forms#named-actions) when a page has several mutations
+
+File-based routing rules are the same as [server routing](../server-routing.md): `[param]` for dynamic segments, `[...param]` for catch-all, `(group)/` for route groups.
+
+## How Navigation Works
+
+Pages uses an Inertia-style protocol under the hood:
+
+| Request               | Response                                                              |
+| --------------------- | --------------------------------------------------------------------- |
+| Initial page load     | Full SSR HTML. Client hydrates automatically.                         |
+| Subsequent navigation | JSON with component name + props. Client component swap or re-render. |
+| Form submission       | Runs action, then returns fresh props or a redirect.                  |
+
+This means the first page load is server-rendered for SEO and performance, while later navigations stay fast without full page reloads.
+
+Use the `Link` component for SPA navigation between pages. It renders an `<a>` tag that intercepts clicks and navigates without a full page reload:
+
+::: code-group
+
+```tsx [React]
+import { Link } from "@void/react";
+
+<Link href="/users">Users</Link>
+<Link href={`/users/${id}`}>View</Link>
+```
+
+```vue [Vue]
+<script setup lang="ts">
+import { Link } from '@void/vue';
+</script>
+
+<template>
+  <Link href="/users">Users</Link>
+  <Link :href="`/users/${id}`">View</Link>
+</template>
+```
+
+```svelte [Svelte]
+<script>
+  import { Link } from "@void/svelte";
+</script>
+
+<Link href="/users">Users</Link>
+<Link href={`/users/${id}`}>View</Link>
+```
+
+```tsx [Solid]
+import { Link } from "@void/solid";
+
+<Link href="/users">Users</Link>
+<Link href={`/users/${id}`}>View</Link>
+```
+
+:::
+
+The `Link` components also support query data, history replacement, document navigation, and cancellable client-side navigation:
+
+```tsx
+<Link href="/users" data={{ page: 2, tag: ['active', 'new'] }}>
+  Filtered users
+</Link>
+
+<Link href="/users" replace>
+  Users
+</Link>
+
+<Link href="/logout" reloadDocument>
+  Sign out
+</Link>
+
+<Link
+  href="/settings"
+  onNavigate={(event) => {
+    if (!confirm('Leave this page?')) {
+      event.preventDefault();
+    }
+  }}
+>
+  Settings
+</Link>
+```
+
+`prefetch` and `reloadDocument` are GET-only. Passing either prop to a mutation link throws. GET `data` is merged into the rendered `href` query string; arrays become repeated keys, `null` and `undefined` are omitted, and nested objects throw.
+
+For programmatic navigation, use `useRouter()`:
+
+```ts
+import { useRouter } from '@void/vue'; // or "@void/react", "@void/svelte", "@void/solid"
+
+const router = useRouter();
+router.visit('/users');
+router.refresh(); // re-fetch current page props
+router.visit('/logout', { method: 'POST' }); // non-GET navigation
+```
+
+## Scroll Restoration
+
+The Void Router automatically saves and restores scroll position during client-side navigation:
+
+- **Back/forward navigation** restores the exact scroll position you were at before navigating away.
+- **Forward navigation** scrolls to the top of the page.
+- **Hash links** (`/docs#api`) scroll to the target element. Same-page hash links (`#section`) skip the server fetch entirely.
+
+This works out of the box with no configuration. If you need to opt out for a specific navigation, pass `preserveScroll: true`:
+
+```ts
+router.visit('/users', { preserveScroll: true });
+```
+
+`Link` also accepts `preserveScroll`:
+
+::: code-group
+
+```tsx [React]
+<Link href="/users" preserveScroll>
+  Users
+</Link>
+```
+
+```vue [Vue]
+<Link href="/users" preserve-scroll>Users</Link>
+```
+
+```svelte [Svelte]
+<Link href="/users" preserveScroll>Users</Link>
+```
+
+```tsx [Solid]
+<Link href="/users" preserveScroll>
+  Users
+</Link>
+```
+
+:::

package/skills/void/docs/guide/pages-routing/view-transitions.md

@@ -0,0 +1,140 @@
+---
+outline: deep
+---
+
+# View Transitions
+
+Pages mode supports the browser's native [View Transition API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API) for animated page transitions. When enabled, navigations are wrapped in `document.startViewTransition()`, which gives you a smooth cross-fade between pages by default. You can customize the effect entirely with CSS.
+
+## Enabling View Transitions
+
+Pass `viewTransitions: true` to the adapter plugin:
+
+::: code-group
+
+```ts [React]
+// vite.config.ts
+export default defineConfig({
+  plugins: [voidPlugin(), voidReact({ viewTransitions: true })],
+});
+```
+
+```ts [Vue]
+// vite.config.ts
+export default defineConfig({
+  plugins: [voidPlugin(), voidVue({ viewTransitions: true })],
+});
+```
+
+```ts [Svelte]
+// vite.config.ts
+export default defineConfig({
+  plugins: [voidPlugin(), voidSvelte({ viewTransitions: true })],
+});
+```
+
+```ts [Solid]
+// vite.config.ts
+export default defineConfig({
+  plugins: [voidPlugin(), voidSolid({ viewTransitions: true })],
+});
+```
+
+:::
+
+This enables view transitions for all navigations, including `Link` clicks, programmatic `router.visit()` calls, and browser back or forward.
+
+## Per-Link Override
+
+Override the global setting on individual links:
+
+::: code-group
+
+```tsx [React]
+{
+  /* Disable transition for this link */
+}
+<Link href="/settings" viewTransition={false}>
+  Settings
+</Link>;
+
+{
+  /* Enable for just this link (even if globally disabled) */
+}
+<Link href="/about" viewTransition>
+  About
+</Link>;
+```
+
+```vue [Vue]
+<!-- Disable transition for this link -->
+<Link href="/settings" :view-transition="false">Settings</Link>
+
+<!-- Enable for just this link (even if globally disabled) -->
+<Link href="/about" view-transition>About</Link>
+```
+
+```svelte [Svelte]
+<!-- Disable transition for this link -->
+<Link href="/settings" viewTransition={false}>Settings</Link>
+
+<!-- Enable for just this link (even if globally disabled) -->
+<Link href="/about" viewTransition>About</Link>
+```
+
+```tsx [Solid]
+{
+  /* Disable transition for this link */
+}
+<Link href="/settings" viewTransition={false}>
+  Settings
+</Link>;
+
+{
+  /* Enable for just this link (even if globally disabled) */
+}
+<Link href="/about" viewTransition>
+  About
+</Link>;
+```
+
+:::
+
+Or programmatically:
+
+```ts
+router.visit('/about', { viewTransition: true });
+router.visit('/settings', { viewTransition: false });
+```
+
+## Customizing with CSS
+
+The default transition is a cross-fade. Customize it using the `::view-transition-old` and `::view-transition-new` pseudo-elements:
+
+```css
+/* Faster transition */
+::view-transition-old(root),
+::view-transition-new(root) {
+  animation-duration: 0.2s;
+}
+
+/* Slide instead of fade */
+::view-transition-old(root) {
+  animation: slide-out 0.3s ease-in;
+}
+::view-transition-new(root) {
+  animation: slide-in 0.3s ease-out;
+}
+```
+
+Assign `view-transition-name` to elements that should animate independently (e.g., a hero image that morphs between pages):
+
+```css
+.hero-image {
+  view-transition-name: hero;
+}
+```
+
+::: tip
+View transitions are progressive enhancement. Browsers that do not support the API fall back to instant navigation with no errors.
+:::

package/skills/void/docs/guide/queues.md

@@ -0,0 +1,140 @@
+---
+outline: deep
+---
+
+# Queues
+
+Void supports Cloudflare Queues for asynchronous message processing from a top-level `queues/` directory.
+
+## Defining queues
+
+Create files in `queues/**/*.ts`; `.mts`, `.js`, and `.mjs` also work. The queue name is inferred from the filename. For example, `queues/emails.ts` creates a queue named `"emails"`, and `queues/order/notifications.ts` creates `"order/notifications"`.
+
+Each queue file should export a default handler wrapped with [`defineQueue`](../reference/api.md#definequeuet-handler). The generic `<T>` parameter defines the message body type. That is the type of each `msg.body` in the batch, and it is also used by the typed `queues` proxy for `send()` calls.
+
+```ts
+// queues/emails.ts
+import { defineQueue } from 'void';
+
+interface Message {
+  to: string;
+  subject: string;
+}
+
+export default defineQueue<Message>(async (batch, env) => {
+  for (const msg of batch.messages) {
+    console.log(`Send to ${msg.body.to}: ${msg.body.subject}`);
+    msg.ack(); // Acknowledge successful processing
+  }
+});
+```
+
+Files or directories starting with `_` are ignored.
+
+## Sending messages
+
+Import the typed `queues` proxy from `void/queues` to send messages. Each queue is available as a property matching its name, with full type safety from the consumer's `defineQueue<T>` generic.
+
+```ts
+// routes/api/orders.ts
+import { defineHandler } from 'void';
+import { queues } from 'void/queues';
+
+export const POST = defineHandler(async (c) => {
+  const order = await c.req.json();
+  // Fully typed: body must match the
+  // Message interface from queues/emails.ts
+  await queues.emails.send({
+    to: order.email,
+    subject: 'Order confirmed',
+  });
+  return c.json({ ok: true });
+});
+```
+
+The binding name is derived automatically: `QUEUE_` + queue name uppercased with non-alphanumeric characters replaced by `_`. For example, `queues/emails.ts` creates binding `QUEUE_EMAILS`.
+
+## Per-message acknowledgment
+
+Each message in the batch has `ack()` and `retry()` methods matching the [Cloudflare Queues API](https://developers.cloudflare.com/queues/configuration/consumer-concurrency/):
+
+```ts
+export default defineQueue<Message>(async (batch, env) => {
+  for (const msg of batch.messages) {
+    try {
+      await processMessage(msg.body);
+      msg.ack(); // Remove from queue
+    } catch {
+      msg.retry({ delaySeconds: 30 }); // Re-deliver after 30s
+    }
+  }
+});
+```
+
+- `msg.ack()`: acknowledge the message and remove it from the queue
+- `msg.retry(options?)`: retry the message, optionally with a `{ delaySeconds }` delay
+- `batch.ackAll()`: acknowledge all messages in the batch
+- `batch.retryAll(options?)`: retry all messages in the batch
+
+The first call wins for each message. Calling `ack()` after `retry()`, or the reverse, does nothing. Messages with no explicit decision are acknowledged if the handler succeeds, or retried if it throws.
+
+The `timestamp` field on each message is a `Date` object.
+
+## Consumer options
+
+Export named constants to configure how Cloudflare delivers batches to your consumer:
+
+```ts
+// queues/emails.ts
+import { defineQueue } from 'void';
+
+interface Message {
+  to: string;
+  subject: string;
+}
+
+export const maxBatchSize = 50;
+export const maxBatchTimeout = 10; // seconds
+export const maxRetries = 5;
+export const retryDelay = 30; // seconds
+
+export default defineQueue<Message>(async (batch, env) => {
+  for (const msg of batch.messages) {
+    console.log(`Send to ${msg.body.to}: ${msg.body.subject}`);
+  }
+});
+```
+
+- `maxBatchSize`: maximum number of messages per batch (default `10`)
+- `maxBatchTimeout`: maximum seconds to wait before delivering an incomplete batch (default `5`)
+- `maxRetries`: maximum number of retries before a message is dead-lettered (default `3`)
+- `retryDelay`: seconds to wait between retries (default `0`)
+
+## Deployment behavior
+
+On deploy, Void includes all discovered queues in the deploy manifest. The platform provisions Cloudflare Queues, configures producer bindings on the user worker, and registers the dispatch worker as the queue consumer for relay delivery.
+
+## Local development
+
+In **default Void mode**, Miniflare delivers queue batches natively — produce a message via the binding and the consumer fires automatically. The worker's `queue()` export serializes the batch and routes it to the same internal `/__queue` handler used in production, so behavior is consistent across environments.
+
+You can also manually dispatch a batch by POSTing to the dev endpoint Void exposes:
+
+```
+POST /__void/queue
+Content-Type: application/json
+{ "queue": "<queue-name>", "messages": [{ "id": "1", "timestamp": <unix_ms>, "body": <any>, "attempts": 1 }] }
+```
+
+The endpoint requires a local dev trigger token. Void prints a paste-ready curl command with the current token when the dev server starts.
+
+```bash
+curl -X POST http://localhost:5173/__void/queue \
+  -H "Content-Type: application/json" \
+  -H "x-void-dev-trigger: <printed-token>" \
+  -d '{"queue":"my-queue","messages":[{"id":"1","timestamp":'"$(date +%s000)"',"body":{"hello":"world"},"attempts":1}]}'
+```
+
+If you set `__VOID_PROXY_TOKEN` in `.dev.vars`, that explicit token takes precedence and the printed curl command uses `x-void-internal: <your-token>` instead.
+
+In **framework mode** (SvelteKit, Nuxt, Analog, Astro, TanStack Start, React Router, vinext), the `/__void/queue` endpoint runs inside the framework adapter's request pipeline (or the dev miniflare for Class A frameworks), so the consumer sees whatever bindings the adapter exposes (D1, KV, R2, queue producers, etc.). Native Miniflare queue delivery is not wired up in framework mode — use the manual dispatch endpoint to exercise a consumer.