@wrikka/solid-framework 0.0.0-stage → 0.15.0

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @wrikka/solid-framework
+
+Unified SolidJS fullstack meta-framework — file routes, loaders, actions, streaming SSR, islands, server functions, auth, realtime, stores, query, hooks, devtools with Clean Architecture.
+
+## Quick start
+
+```ts
+// vite.config.ts
+import { solidFramework } from "@wrikka/solid-framework/vite";
+import solid from "vite-plugin-solid";
+
+export default defineConfig({
+	plugins: [solidFramework({ config: { renderMode: "stream" } }), solid({ ssr: true })],
+});
+```
+
+```ts
+// solid.config.ts — one def feeds both entries
+import { defineApp } from "@wrikka/solid-framework/app";
+
+export default defineApp({
+	render: () => <App />,
+	server: {
+		ops: { ready: () => db.ping(), metrics: true }, // /_health /_ready /_metrics
+		ai: { mcp: { token: env.MCP_TOKEN } },           // /llms.txt + /_server/mcp
+	},
+});
+```
+
+```tsx
+// src/routes/users/[id].tsx — a page is ONE export
+import { page } from "@wrikka/solid-framework/app";
+
+export default page({
+	params: (p) => ({ id: String(p.id) }),          // validate params
+	search: (q) => ({ page: Number(q.page ?? 1) }), // typed ?query
+	load: ({ params }) => db.user(params.id),
+	head: ({ data }) => ({ title: data()?.name }), // per-route SEO
+	component: ({ data, params, search }) => (
+		<p>{data()?.name} #{params.id} (page {search.page})</p>
+	),
+});
+```
+
+```tsx
+// src/entry-server.tsx              // src/entry-client.tsx
+import app from "../solid.config";   import app from "../solid.config";
+import { serve } from "@wrikka/solid-framework/app";
+import { hydrate } from "@wrikka/solid-framework/app";
+
+export default serve(app);           await hydrate(app);
+```
+
+Inside components, one hook covers the route surface:
+
+```tsx
+const r = useRoute<User, { id: string }, AuthState, { page: number }>();
+r.data()?.name   // loader data     r.params.id      // route params
+r.search.page    // typed query     r.state.user     // middleware bag
+r.retry()        // re-run loader   r.navigate("/x") // client nav (View Transitions)
+```
+
+## Feature highlights (0.4.0)
+
+- **8 render modes per route** — ssr / stream / csr / data-only / ssg / prerender / ppr / islands via `config.rules`
+- **Routing** — params, splats, groups `(grp)`, intercepted `(.)name` soft-nav modal, parallel `@slot` + `<Outlet name>`, typed `RoutePath`
+- **Server functions** — stream + batch + live queries, `FnResult` typed error union, `InferServerFn`
+- **Cache** — tagged `useCache`, `revalidateTag`/`revalidatePath`, ISR+SWR, pluggable `CacheStore` (memory/fs/edge-kv)
+- **Auth** — signed cookie sessions, role guards, OAuth2 helpers, pluggable session stores
+- **Realtime** — WebSocket channels + presence + rooms, SSE live queries with resume
+- **Ops** — `/_health` `/_ready` `/_metrics`, `instrumentation.ts` auto-discovery, request-id logging
+- **AI surface** — `/llms.txt` route manifest + `/_server/mcp` JSON-RPC endpoint
+- **Multi-zone** — `config.zones` prefix proxy; deploy adapters for fetch/cloudflare/deno/node
+- **Nav polish** — View Transitions on by default (`transition={false}` opt-out), `<Link prefetch="intent|viewport|render|shell">` warms loader too, `link.relative("../x")`
+- **One `page()` def** — `search` (typed `?query`), `head` (reactive SEO), `actions` (named forms via `<Form name>` or `r.submit`), `guard` chain, `meta`, `error`/`loading`/`shell` slots, `poll`, `streaming` flag
+- **`useRoute()` superset** — `data`, `params`, `search`, `state`, `meta`, `preload(path)`, `submit(name, fields)`, `snapshot()`
+- **Env** — `defineApp({ env })` validates at boot; `useEnv()` typed, server keys throw on the client
+- **Remote islands** — `<RemoteIsland src="https://…/_island/X">` embeds fragments from any origin
+- **Codemods** — `solid migrate` rewrites flat route exports → `page()` (`--dry` to preview), `solid adopt` prints the adoption scaffold
+- **DX** — devtools overlay (routes/queries/events/islands), `/_devtools` page, CLI `preview|config|generate|test|test-nav|doctor|routes|add`
+
+## Subpaths
+
+| Subpath | Surface |
+|---------|---------|
+| `@wrikka/solid-framework/app` | app server, file routes, loaders/actions, auth, db, cache, config, flash, fonts, i18n |
+| `@wrikka/solid-framework/server` | server functions, realtime (SSE + WS), scheduler, sessions, metrics, platform adapters |
+| `@wrikka/solid-framework/router` | standalone router |
+| `@wrikka/solid-framework/stores` · `/query` · `/hooks` | client primitives |
+| `@wrikka/solid-framework/render` | render pipeline, islands, RSC-lite |
+| `@wrikka/solid-framework/head` | head manager, SEO tags, `preloadTags` |
+| `@wrikka/solid-framework/devtools` | observability |
+| `@wrikka/solid-framework/vite` | vite plugin (prebuilt dist) |
+| `@wrikka/solid-framework/cli` | `solid dev|build|start|preview|config|generate|test|test-nav|migrate|adopt|doctor|watch|eject|routes|add` |
+| `@wrikka/solid-framework/internal` | runtime plumbing (server entries, manifests) |
+| `@wrikka/solid-framework/testing` | test helpers (`testRoute`, etc.) |
+
+## Requirements
+
+- bun >= 1.3.10 (or node >= 20 for library consumption)
+- solid-js ^1.9 (peer)
+- optional peers: drizzle-orm, monaco-editor, jsqr, qrcode (only for their adapters)
+
+License: MIT