@wrikka/solid-framework 0.0.0-stage → 0.15.0

package/src/app/types/index.ts

@@ -0,0 +1,273 @@
+/**
+ * App Domain Types
+ * Framework-level configuration shared by vite plugin, CLI and runtime
+ */
+
+import type { RenderMode } from "#render/types";
+
+/**
+ * Per-route rendering/cache rules — the routeRules equivalent.
+ * Patterns support `*` (one segment) and `**` (any depth).
+ */
+export interface RouteRule {
+	/**
+	 * Render strategy — `data-only` runs the route loader on the server
+	 * and ships a CSR shell with the data preloaded (TanStack Start's
+	 * `ssr: 'data-only'` equivalent)
+	 */
+	mode?: RenderMode | "ssg" | "prerender" | "data-only" | "ppr";
+	headers?: Record<string, string>;
+	/**
+	 * Cache/ISR — maxAge is the revalidate window (seconds) for
+	 * prerendered routes and the Cache-Control max-age
+	 */
+	cache?: { maxAge?: number; swr?: boolean; tags?: string[] };
+	/**
+	 * Per-route middleware — runs after config.middleware when this rule
+	 * matches the request pathname. Return a Response to short-circuit.
+	 */
+	middleware?: AppMiddleware[];
+	/**
+	 * Security headers for matched routes — `true` applies the safe
+	 * default set (nosniff, frame DENY, referrer policy, HSTS);
+	 * `csp` enables a nonce-based Content-Security-Policy whose nonce
+	 * is exposed as context.state.cspNonce and applied to the
+	 * hydration script
+	 */
+	security?: SecurityHeaders | boolean;
+	/**
+	 * Rate limit — fixed-window token bucket per client key.
+	 * `rpm` requests per `window` ms (default 60/60s); `key` customizes
+	 * the bucket key (default: client ip + pattern)
+	 */
+	rateLimit?: {
+		rpm?: number;
+		window?: number;
+		key?: (ctx: { request: Request }) => string;
+	};
+	/**
+	 * A/B split — `weight` fraction of clients are rewritten to
+	 * `route` (sticky via `__ab_<pattern>` cookie)
+	 */
+	variant?: { route: string; weight: number };
+	/**
+	 * Sitemap metadata for matched routes — priority/changefreq/
+	 * lastmod merge into the generated sitemap.xml entries
+	 */
+	sitemap?: {
+		priority?: number;
+		changefreq?: string;
+		lastmod?: string;
+	};
+}
+
+export interface SecurityHeaders {
+	/** CSP directives — {nonce} is replaced per request */
+	csp?: string | Record<string, string[]>;
+	/** X-Frame-Options — default DENY when security is enabled */
+	frameOptions?: "DENY" | "SAMEORIGIN";
+	/** Referrer-Policy — default strict-origin-when-cross-origin */
+	referrerPolicy?: string;
+	/** Strict-Transport-Security — default "max-age=31536000; includeSubDomains" */
+	hsts?: string;
+	/** X-Content-Type-Options: nosniff — default true */
+	noSniff?: boolean;
+}
+
+export type RouteRules = Record<string, RouteRule>;
+
+/** Per-request state bag middleware writes into and render reads */
+export interface MiddlewareContext<
+	TState extends Record<string, unknown> = Record<string, unknown>,
+> {
+	request: Request;
+	url: URL;
+	/** Shared state — exposed on the render context and route loaders */
+	state: TState;
+	/** Params from the matched file route, when available */
+	params?: Record<string, string>;
+}
+
+/**
+ * Server middleware — runs before routing/rendering. Return a Response
+ * to short-circuit (redirect, auth deny), otherwise call through.
+ * Generic over the shared state bag so downstream loaders/actions
+ * consume `state` type-safely via useRouteState<T>()
+ */
+export type AppMiddleware<
+	TState extends Record<string, unknown> = Record<string, unknown>,
+> = ((
+	ctx: MiddlewareContext<TState>,
+) => undefined | Response | Promise<undefined | Response>) & {
+	/** Execution order — lower runs first; default 0 */
+	order?: number;
+};
+
+/** Typed middleware factory — identity helper for inference */
+export const createMiddleware = <
+	TState extends Record<string, unknown> = Record<string, unknown>,
+>(
+	fn: AppMiddleware<TState>,
+): AppMiddleware<TState> => fn;
+
+/** Wrap a middleware with an explicit execution order */
+export const ordered = <
+	TState extends Record<string, unknown> = Record<string, unknown>,
+>(
+	order: number,
+	fn: AppMiddleware<TState>,
+): AppMiddleware<TState> => Object.assign(fn, { order });
+
+/** Framework plugin — the Nuxt-module equivalent */
+export interface FrameworkPlugin {
+	name: string;
+	/** Mutate/patch resolved config at startup */
+	config?: (
+		config: SolidFrameworkConfig,
+	) => Partial<SolidFrameworkConfig> | undefined;
+	/** Called when the file-route manifest is built (dev/build) */
+	routesResolved?: (manifest: unknown) => void;
+	/** Source transform hook inside the vite plugin */
+	transform?: (code: string, id: string) => string | null | undefined;
+}
+
+export interface ImagesConfig {
+	/** Endpoint path — default "/_image" */
+	endpoint?: string;
+	/**
+	 * Transformer port — receives parsed params, returns the optimized
+	 * image Response. Default redirects to the original asset.
+	 */
+	transformer?: (params: {
+		src: string;
+		width?: number;
+		quality?: number;
+		format?: string;
+		request: Request;
+	}) => Promise<Response> | Response;
+	/**
+	 * Remote image allowlist (SSRF guard) — absolute `src` URLs are only
+	 * fetched when the host matches a pattern ("cdn.example.com" or
+	 * "*.example.com"). When unset, only same-origin sources resolve.
+	 */
+	remotePatterns?: string[];
+}
+
+export interface SolidFrameworkConfig {
+	/** Routes directory — default "src/routes" */
+	routesDir: string;
+	/** Default render mode when no route rule matches — default "stream" */
+	renderMode: RenderMode;
+	/** Path-pattern rules — `rules: { "/blog/**": { mode: "prerender" } }` */
+	rules: RouteRules;
+	/** @deprecated renamed to `rules` — routeRules is Nuxt's name */
+	routeRules?: RouteRules;
+	/** Path prefixes served by web-server API routes — default ["/api"] */
+	apiPrefixes: string[];
+	/** Default document metadata */
+	head: {
+		title?: string;
+		lang?: string;
+		/**
+		 * Asset preload hints — entry chunks/styles emitted into <head> on
+		 * every HTML response; pair with the build's preload-manifest.json
+		 */
+		preloads?: string[];
+	};
+	/** Auto-import framework APIs in .tsx/.ts sources */
+	autoImports: boolean;
+	/** Server/client entry files */
+	entries: { server: string; client: string };
+	/** Extra public env prefixes exposed to the client — default ["PUBLIC_"] */
+	publicEnvPrefixes: string[];
+	/** Server middleware chain — runs before the render pipeline */
+	middleware?: AppMiddleware[];
+	/** Framework plugins */
+	plugins?: FrameworkPlugin[];
+	/**
+	 * Layers — base configs merged shallow-first; this config wins.
+	 * Compose app presets: `extends: [shopLayer]`
+	 */
+	extends?: Partial<SolidFrameworkConfig>[];
+	/**
+	 * Observability hooks — `instrumentation.ts` convention:
+	 *   export const register = () => initTelemetry();
+	 *   export const onRequest = (e) => span(e);
+	 * register() runs once at server boot; onRequest runs after
+	 * every response with {method, path, status, ms}
+	 */
+	instrumentation?: {
+		register?: () => void | Promise<void>;
+		onRequest?: (event: {
+			method: string;
+			path: string;
+			status: number;
+			ms: number;
+		}) => void;
+		/** Thrown errors reach onError before the 500 response */
+		onError?: (event: { method: string; path: string; error: unknown }) => void;
+	};
+	/**
+	 * Multi-zone — requests under `prefix` proxy to `target` origin
+	 * (another app/zone); prefix is stripped before forwarding
+	 */
+	zones?: { prefix: string; target: string }[];
+	/** Image optimization endpoint config */
+	images?: ImagesConfig;
+	/**
+	 * Build-time prerendering — after the SSR build, listed routes are
+	 * rendered through the built server entry and written to outDir as
+	 * static HTML. crawlLinks discovers additional pages via anchors.
+	 */
+	prerender?: {
+		routes?: string[];
+		crawlLinks?: boolean;
+		/** Output directory for static pages — default "<root>/dist" */
+		outDir?: string;
+	};
+	/**
+	 * Production static file serving — directories tried in order for
+	 * GET requests before the render fallback (e.g. ["dist", "public"])
+	 */
+	static?: { dirs: string[]; immutablePrefix?: string };
+	/**
+	 * PWA — emit sw.js (precache + cache-first GET strategy) and an
+	 * optional manifest.webmanifest into the client build
+	 */
+	pwa?: {
+		/** Extra URLs precached at install — "/" is always included */
+		precache?: string[];
+		manifest?: {
+			name?: string;
+			shortName?: string;
+			startUrl?: string;
+			display?: string;
+			background?: string;
+			theme?: string;
+			icons?: { src: string; sizes: string; type?: string }[];
+		};
+	};
+	/**
+	 * i18n routing — locale-prefixed paths (`/en/about`), stripped
+	 * before route matching; locale exposed via useLocale()
+	 */
+	i18n?: {
+		locales: string[];
+		defaultLocale: string;
+		strategy?: "prefix" | "prefix_except_default";
+	};
+}
+
+export interface RouteConventions {
+	error?: string;
+	loading?: string;
+	notFound?: string;
+	layout?: string;
+}
+
+export interface ResolvedRoute {
+	path: string;
+	file: string;
+	conventions: RouteConventions;
+	rule?: RouteRule;
+}

package/src/assets/adapters/sharp.ts

@@ -0,0 +1,83 @@
+/**
+ * Sharp Image Transformer
+ * Real image optimization for the /_image endpoint — sharp is loaded
+ * lazily so apps without it installed keep the default redirect
+ * transformer. Usage:
+ *
+ *   createAppServer({
+ *     config: { images: { transformer: createSharpTransformer() } },
+ *   });
+ */
+
+import type { ImageParams } from "../modules/assets/domain/operations";
+
+type SharpLike = (input: Buffer | ArrayBuffer) => SharpPipeline;
+
+interface SharpPipeline {
+	resize(options: { width?: number }): SharpPipeline;
+	toFormat(format: string, options?: { quality?: number }): SharpPipeline;
+	toBuffer(): Promise<Buffer>;
+}
+
+export interface SharpTransformerOptions {
+	/** Fetch override for loading the source image */
+	fetch?: typeof fetch;
+	/** Format allowlist — anything else falls back to the source type */
+	formats?: string[];
+}
+
+const FORMATS = new Set(["webp", "avif", "png", "jpeg", "jpg"]);
+const CONTENT_TYPES: Record<string, string> = {
+	webp: "image/webp",
+	avif: "image/avif",
+	png: "image/png",
+	jpeg: "image/jpeg",
+	jpg: "image/jpeg",
+};
+
+export const createSharpTransformer = (
+	options: SharpTransformerOptions = {},
+) => {
+	const fetchFn = options.fetch ?? fetch;
+	const allowed = new Set(options.formats ?? FORMATS);
+
+	return async (
+		params: ImageParams & { request: Request },
+	): Promise<Response> => {
+		let sharp: SharpLike;
+		try {
+			// Variable specifier — sharp is an optional peer, tsc/bundlers
+			// must not resolve it at build time
+			const specifier = "sharp";
+			const mod = (await import(specifier)) as { default: SharpLike };
+			sharp = mod.default;
+		} catch {
+			return new Response(
+				"[solid-framework] sharp transformer requires the `sharp` package — install it or omit config.images.transformer",
+				{ status: 501 },
+			);
+		}
+
+		// Resolve relative sources against the request origin
+		const sourceUrl = new URL(params.src, params.request.url);
+		const source = await fetchFn(sourceUrl);
+		if (!source.ok) {
+			return new Response("Image source not found", { status: 404 });
+		}
+
+		const format =
+			params.format && allowed.has(params.format) ? params.format : "webp";
+
+		const buffer = await sharp(await source.arrayBuffer())
+			.resize(params.width ? { width: params.width } : {})
+			.toFormat(format, { quality: params.quality ?? 80 })
+			.toBuffer();
+
+		return new Response(new Uint8Array(buffer), {
+			headers: {
+				"Content-Type": CONTENT_TYPES[format] ?? "image/webp",
+				"Cache-Control": "public, max-age=31536000, immutable",
+			},
+		});
+	};
+};

package/src/assets/index.ts

@@ -0,0 +1,6 @@
+// Public API - @wrikka/solid-framework/assets
+
+export * from "./adapters/sharp";
+export * from "./modules/assets";
+export * from "./presentation";
+export * from "./types";

package/src/assets/modules/assets/domain/index.ts

@@ -0,0 +1 @@
+export * from "./operations";

package/src/assets/modules/assets/domain/operations/image.ts

@@ -0,0 +1,67 @@
+/**
+ * Image Endpoint Operations
+ * /_image URL builder + request parsing — the optimization endpoint
+ * used by <Image optimize> (nuxt/image /_ipx equivalent)
+ */
+
+export const IMAGE_ENDPOINT = "/_image";
+
+export interface ImageParams {
+	src: string;
+	width?: number;
+	quality?: number;
+	format?: string;
+}
+
+export const imageUrl = (
+	src: string,
+	params: Omit<ImageParams, "src"> = {},
+	endpoint = IMAGE_ENDPOINT,
+): string => {
+	const query = new URLSearchParams({ src });
+	if (params.width) query.set("w", String(params.width));
+	if (params.quality) query.set("q", String(params.quality));
+	if (params.format && params.format !== "auto")
+		query.set("fmt", params.format);
+	return `${endpoint}?${query.toString()}`;
+};
+
+/** Build a srcset of /_image URLs for candidate widths */
+export const imageSrcset = (
+	src: string,
+	widths: number[],
+	format?: string,
+	endpoint = IMAGE_ENDPOINT,
+): string =>
+	widths
+		.map((w) => `${imageUrl(src, { width: w, format }, endpoint)} ${w}w`)
+		.join(", ");
+
+/** Parse an incoming /_image request into params — null when invalid */
+export const parseImageRequest = (url: URL): ImageParams | null => {
+	const src = url.searchParams.get("src");
+	if (!src) return null;
+	const w = url.searchParams.get("w");
+	const q = url.searchParams.get("q");
+	const fmt = url.searchParams.get("fmt");
+	return {
+		src,
+		...(w ? { width: Number(w) } : {}),
+		...(q ? { quality: Number(q) } : {}),
+		...(fmt ? { format: fmt } : {}),
+	};
+};
+
+/**
+ * Default transformer — no image binary processing built in; redirect
+ * to the original asset so apps can front it with a CDN or plug a real
+ * transformer (sharp/wasm) via config.images.transformer
+ */
+export const defaultImageTransformer = (params: ImageParams): Response =>
+	new Response(null, {
+		status: 302,
+		headers: {
+			Location: params.src,
+			"Cache-Control": "public, max-age=31536000, immutable",
+		},
+	});

package/src/assets/modules/assets/domain/operations/index.ts

@@ -0,0 +1,2 @@
+export * from "./image";
+export * from "./manifest";

package/src/assets/modules/assets/domain/operations/manifest.ts

@@ -0,0 +1,29 @@
+/**
+ * Asset Manifest Operations
+ * Resolve build-manifest entries to URLs and generate srcset candidates
+ */
+
+import type { AssetManifest } from "#assets/types";
+
+/**
+ * Resolve a source path to its built URL via the Vite manifest;
+ * falls back to the source path itself when unmapped (dev mode)
+ */
+export const assetUrl = (src: string, manifest: AssetManifest = {}): string =>
+	manifest[src]?.file ?? src;
+
+/**
+ * Build a srcset string for width-based responsive images.
+ * Convention: the asset pipeline serves `/<path>?w=<width>[&fmt=<format>]`
+ */
+export const buildSrcset = (
+	src: string,
+	widths: number[],
+	format?: string,
+): string =>
+	widths
+		.map(
+			(width) =>
+				`${src}?w=${width}${format && format !== "auto" ? `&fmt=${format}` : ""} ${width}w`,
+		)
+		.join(", ");

package/src/assets/modules/assets/index.ts

@@ -0,0 +1 @@
+export * from "./domain";

package/src/assets/presentation/Image.tsx

@@ -0,0 +1,90 @@
+/**
+ * Image Component
+ * Responsive image with srcset, lazy loading and manifest resolution —
+ * the next/image / nuxt/image equivalent
+ */
+
+import type { JSX } from "solid-js";
+import { createSignal } from "solid-js";
+import {
+	assetUrl,
+	buildSrcset,
+	imageSrcset,
+	imageUrl,
+} from "#assets/modules/assets/domain/operations";
+import type { AssetManifest } from "#assets/types";
+
+export interface ImageProps {
+	src: string;
+	alt: string;
+	width?: number;
+	height?: number;
+	/** Candidate widths for srcset — empty disables srcset */
+	widths?: number[];
+	sizes?: string;
+	loading?: "lazy" | "eager";
+	fetchpriority?: "high" | "low" | "auto";
+	format?: "webp" | "avif" | "auto";
+	class?: string;
+	style?: JSX.CSSProperties;
+	manifest?: AssetManifest;
+	/** Route through the /_image optimization endpoint */
+	optimize?: boolean;
+	/** Optimization quality hint (1-100) */
+	quality?: number;
+	/** "blur" shows blurDataURL as a background until the image loads */
+	placeholder?: "blur" | "empty";
+	/** Base64/data-uri preview for placeholder="blur" */
+	blurDataURL?: string;
+	onLoad?: () => void;
+}
+
+export const Image = (props: ImageProps): JSX.Element => {
+	const [loaded, setLoaded] = createSignal(false);
+	const resolved = () => assetUrl(props.src, props.manifest);
+	const src = () =>
+		props.optimize
+			? imageUrl(resolved(), {
+					width: props.width,
+					quality: props.quality,
+					format: props.format,
+				})
+			: resolved();
+	const srcset = () => {
+		if (!props.widths?.length) return undefined;
+		return props.optimize
+			? imageSrcset(resolved(), props.widths, props.format)
+			: buildSrcset(resolved(), props.widths, props.format);
+	};
+
+	const style = (): JSX.CSSProperties => ({
+		...props.style,
+		...(props.placeholder === "blur" && props.blurDataURL && !loaded()
+			? {
+					"background-image": `url(${props.blurDataURL})`,
+					"background-size": "cover",
+					"background-position": "center",
+				}
+			: {}),
+	});
+
+	return (
+		<img
+			src={src()}
+			srcset={srcset()}
+			sizes={props.sizes}
+			alt={props.alt}
+			width={props.width}
+			height={props.height}
+			loading={props.loading ?? "lazy"}
+			fetchpriority={props.fetchpriority}
+			decoding="async"
+			class={props.class}
+			style={style()}
+			onLoad={() => {
+				setLoaded(true);
+				props.onLoad?.();
+			}}
+		/>
+	);
+};

package/src/assets/presentation/index.ts

@@ -0,0 +1 @@
+export * from "./Image";

package/src/assets/types/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Assets Domain Types
+ * Asset manifest and optimized asset components
+ */
+
+export interface AssetManifestEntry {
+	file: string;
+	src?: string;
+	isEntry?: boolean;
+	css?: string[];
+	imports?: string[];
+}
+
+export type AssetManifest = Record<string, AssetManifestEntry>;
+
+export interface ImageVariants {
+	/** widths available for srcset generation */
+	widths: number[];
+	/** output format — served by the asset pipeline/CDN */
+	format?: "webp" | "avif" | "auto";
+}

package/src/cli/bin.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env bun
+/**
+ * solid CLI entry — `bunx solid <command>`
+ */
+
+import { runCli } from "./commands";
+
+process.exit(runCli().code);