@jk2908/solas 0.5.3 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.6.0
+
+### Breaking
+
+- Removed the `Solas` runtime namespace exports (`Solas.Config`, `Solas.Runtime`, `Solas.Events`) from the `@jk2908/solas` entry. Runtime constants now live in dedicated internal modules, and generated code no longer reaches through the namespace.
+- Removed the `@jk2908/solas/$` export path. Generated environment entries now import directly from `@jk2908/solas/env/rsc`.
+- Removed the `port` config option from `solas()`. The development port now comes from Vite's `server.port`. `url` remains available as an optional public origin and now resolves from the `url` option → `VITE_APP_URL` → the Vite dev server `host`/`port`.
+
+### Features
+
+- Generated `.solas` files are formatted with oxfmt before writing, and stale generated files are pruned when the codegen stops emitting them.
+- Added a Vitest test suite covering unit, integration, and browser (React Testing Library) tests.
+
+### Fixes
+
+- Generated `entry.rsc.tsx` now emits valid code (`loadManifest` from `env/rsc`) instead of referencing an undefined `Config` import.
+- Fixed the release pipeline by committing the postbuild measurement script.
+
+### Changed
+
+- Pinned `@vitejs/plugin-rsc` to `0.5.34`.
+- Removed the Playwright e2e suite, fixtures, and scripts for now; unit, integration, and browser tests run through Vitest.
+- Declared `engines.node` (`^20.19.0 || >=22.12.0`).
+
+## 0.5.4 - 2026-06-08
+
+- Add a BrowserRouterHistory API to sync app back/forward navigation with browser navigation.
+- Expose BrowserRouterContext.history for gated use in client components
+
 ## 0.5.3 - 2026-06-06
 
 - Ensured `createRuntime(...)` is exported from `@jk2908/solas/env/rsc` for generated RSC entry compatibility.

package/README.md

@@ -2,7 +2,7 @@
 
 Solas is a minimal React meta-framework powered by Vite, created for experimenting with routing, streaming, and prerendering with React Server Components.
 
-Solas is experimental and currently has no automated test suite, so expect rough edges.
+Solas is experimental and under active development, so expect rough edges.
 
 ## Install
 
@@ -201,13 +201,9 @@ That keeps your route params aligned across links, imperative navigation, metada
 
 All Solas options are passed to `solas()` inside `defineConfig`.
 
-## Runtime
-
-Solas uses a runtime for filesystem access, mime lookup, and hashing.
-
-This is not a deployment or packaging adapter. Platform adapters are not available yet.
+### `runtime`
 
-Use the `runtime` config key to select the runtime used by Solas server code.
+Use `runtime` to select the runtime used by Solas server code.
 
 Supported values are `'auto'`, `'node'`, and `'bun'`.
 
@@ -215,104 +211,45 @@ Supported values are `'auto'`, `'node'`, and `'bun'`.
 
 If you already run Vite through Bun, `runtime: 'auto'` is usually enough and Solas will detect Bun automatically.
 
-### Node runtime
-
-If you want to pin Node explicitly, set `runtime: 'node'`:
-
-```ts
-import { defineConfig } from 'vite'
-
-import solas from '@jk2908/solas'
-import react from '@vitejs/plugin-react'
-
-export default defineConfig({
-	plugins: [solas({ runtime: 'node' }), react()],
-})
-```
-
-Use the normal Vite commands with the Node runtime:
-
-```json
-{
-	"scripts": {
-		"dev": "vite dev",
-		"build": "vite build",
-		"preview": "vite preview"
-	}
-}
-```
-
-### Bun runtime
-
-If you want Solas runtime code to execute in Bun, set `runtime: 'bun'`:
-
-```ts
-import { defineConfig } from 'vite'
-
-import solas from '@jk2908/solas'
-import react from '@vitejs/plugin-react'
-
-export default defineConfig({
-	plugins: [solas({ runtime: 'bun' }), react()],
-})
-```
-
-When you use the Bun runtime, run Vite through Bun so the server/runtime code executes in a Bun process:
-
-```json
-{
-	"scripts": {
-		"dev": "bunx --bun vite dev",
-		"build": "bunx --bun vite build",
-		"preview": "bunx --bun vite preview"
-	}
-}
-```
-
 ### `url`
 
-`url` is optional. If you set it, Solas treats it as the public origin for your app.
+Use `url` to set the public origin for your app. It is optional.
 
-Solas resolves it in this order:
+Solas resolves the origin in this order:
 
 - the `url` option passed to `solas()`
 - `VITE_APP_URL`
+- the Vite dev server `host` and `port` (defaults to `http://localhost:8787`)
 
-Solas exposes the resolved value as `import.meta.env.VITE_APP_URL`. If `url` is set, prerender also uses it as the request origin for build-time renders.
+The resolved origin is exposed to your app as `import.meta.env.VITE_APP_URL` and is used for build-time prerender requests and `sitemap` URLs. When `url` is set, it is also used as a trusted origin for CSRF.
 
-In practice, you only need `url` if your app reads `import.meta.env.VITE_APP_URL` or your prerendered output needs a real public origin.
-
-If you do want to set it explicitly, this is the shape:
+You usually only need `url` in production, where the Vite dev server origin is meaningless. For example, to generate a `sitemap.xml` with real URLs:
 
 ```ts
 export default defineConfig(({ mode }) => ({
 	plugins: [
 		solas({
-			url: mode === 'production' ? 'https://example.com' : 'http://localhost:8787',
+			url: mode === 'production' ? 'https://example.com' : undefined,
+			sitemap: true,
 		}),
 	],
 }))
 ```
 
-If you prefer an environment variable, set this instead:
+If you prefer an environment variable, set `VITE_APP_URL` instead:
 
 ```sh
 VITE_APP_URL=https://example.com
 ```
 
-### `port`
-
-Use `port` to change the development server port.
-
-Default: `8787`
+Set the development port with Vite's `server.port`:
 
 ```ts
 export default defineConfig({
-	plugins: [
-		solas({
-			port: 4000,
-		}),
-	],
+	server: {
+		port: 4000,
+	},
+	plugins: [solas(), react()],
 })
 ```
 
@@ -510,13 +447,13 @@ Use `sitemap` to generate a `sitemap.xml` at build time.
 
 Default: `false`
 
-When enabled, Solas writes a sitemap containing all routes with deterministic URLs: static routes, prerendered routes, and dynamic routes resolved via `params`. The origin for each URL comes from `config.url`.
+When enabled, Solas writes a sitemap containing all routes with deterministic URLs: static routes, prerendered routes, and dynamic routes resolved via `params`. The origin for each URL comes from the resolved origin (see Config > `url`).
 
 ```ts
 export default defineConfig(({ mode }) => ({
 	plugins: [
 		solas({
-			url: mode === 'production' ? 'https://example.com' : 'http://localhost:8787',
+			url: mode === 'production' ? 'https://example.com' : undefined,
 			sitemap: true,
 		}),
 	],
@@ -528,10 +465,9 @@ Routes with dynamic segments (`[id]`) or catch-all segments (`[...param]`) are o
 To add routes that Solas cannot discover automatically (for example, catch-all routes backed by a CMS), pass an object with a `routes` function. The function receives the auto-discovered routes and returns the final list:
 
 ```ts
-export default defineConfig(({ mode }) => ({
+export default defineConfig({
 	plugins: [
 		solas({
-			url: mode === 'production' ? 'https://example.com' : 'http://localhost:8787',
 			sitemap: {
 				async routes(existing) {
 					const posts = await getPosts()
@@ -540,7 +476,7 @@ export default defineConfig(({ mode }) => ({
 			},
 		}),
 	],
-}))
+})
 ```
 
 The `routes` function can be async. The callback also lets you filter routes:
@@ -581,6 +517,66 @@ export default defineConfig({
 })
 ```
 
+## Runtime
+
+Solas uses a runtime for filesystem access, mime lookup, and hashing.
+
+This is not a deployment or packaging adapter. Platform adapters are not available yet.
+
+### Node runtime
+
+If you want to pin Node explicitly, set `runtime: 'node'`:
+
+```ts
+import { defineConfig } from 'vite'
+
+import solas from '@jk2908/solas'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+	plugins: [solas({ runtime: 'node' }), react()],
+})
+```
+
+Use the normal Vite commands with the Node runtime:
+
+```json
+{
+	"scripts": {
+		"dev": "vite dev",
+		"build": "vite build",
+		"preview": "vite preview"
+	}
+}
+```
+
+### Bun runtime
+
+If you want Solas runtime code to execute in Bun, set `runtime: 'bun'`:
+
+```ts
+import { defineConfig } from 'vite'
+
+import solas from '@jk2908/solas'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+	plugins: [solas({ runtime: 'bun' }), react()],
+})
+```
+
+When you use the Bun runtime, run Vite through Bun so the server/runtime code executes in a Bun process:
+
+```json
+{
+	"scripts": {
+		"dev": "bunx --bun vite dev",
+		"build": "bunx --bun vite build",
+		"preview": "bunx --bun vite preview"
+	}
+}
+```
+
 ## Scripts
 
 Add scripts to your app:
@@ -619,7 +615,7 @@ When available, Solas checks browser provenance using:
 - `Origin`
 - `Referer`
 
-Solas also considers the effective request origin when your app is behind a proxy by using `X-Forwarded-Host`, `X-Forwarded-Proto`, and `config.url` when present.
+Solas also considers the effective request origin when your app is behind a proxy by using `X-Forwarded-Host` and `X-Forwarded-Proto`.
 
 If you need to allow a trusted third-party browser POST source, configure it explicitly:
 

package/dist/config.d.ts

@@ -0,0 +1,25 @@
+import type { PluginConfig } from './types.js';
+export declare const NAME = "Solas";
+export declare const SLUG: string;
+export declare const PKG_NAME: string;
+export declare const OUT_DIR = "dist";
+export declare const APP_DIR = "app";
+export declare const GENERATED_DIR: string;
+export declare const ENTRY_RSC = "entry.rsc.tsx";
+export declare const ENTRY_SSR = "entry.ssr.tsx";
+export declare const ENTRY_BROWSER = "entry.browser.tsx";
+export declare const ASSETS_DIR: string;
+export declare const PUBLIC_DIR = "public";
+export declare const $: unique symbol;
+export declare const REQUEST_META_KEY: string;
+export declare const LOG_LEVELS: readonly ["debug", "info", "warn", "error", "fatal"];
+export declare const RUNTIMES: readonly ["auto", "node", "bun"];
+export declare const PRERENDER_MODES: readonly ["full", "ppr", false];
+export declare const TRAILING_SLASH_MODES: readonly ["always", "never", "ignore"];
+export declare const RUNTIME_MANIFEST = "runtime-manifest.json";
+/**
+ * Validate the plugin configuration object, throwing an error if invalid
+ * @param input - the unvalidated configuration object
+ * @return the typed and validated configuration object
+ */
+export declare function validate(input: unknown): PluginConfig;

package/dist/config.js

@@ -0,0 +1,152 @@
+import * as Config from './config.js';
+export const NAME = 'Solas';
+export const SLUG = NAME.toLowerCase();
+export const PKG_NAME = `@jk2908/${SLUG}`;
+export const OUT_DIR = 'dist';
+export const APP_DIR = 'app';
+export const GENERATED_DIR = `.${SLUG}`;
+export const ENTRY_RSC = 'entry.rsc.tsx';
+export const ENTRY_SSR = 'entry.ssr.tsx';
+export const ENTRY_BROWSER = 'entry.browser.tsx';
+export const ASSETS_DIR = `_${SLUG}`;
+export const PUBLIC_DIR = 'public';
+export const $ = Symbol(SLUG);
+export const REQUEST_META_KEY = `__${SLUG.toUpperCase()}__`;
+export const LOG_LEVELS = ['debug', 'info', 'warn', 'error', 'fatal'];
+export const RUNTIMES = ['auto', 'node', 'bun'];
+export const PRERENDER_MODES = ['full', 'ppr', false];
+export const TRAILING_SLASH_MODES = ['always', 'never', 'ignore'];
+export const RUNTIME_MANIFEST = 'runtime-manifest.json';
+const CONFIG_KEYS = new Set([
+    'runtime',
+    'logger',
+    'metadata',
+    'precompress',
+    'prerender',
+    'sitemap',
+    'trustedOrigins',
+    'trailingSlash',
+    'url',
+]);
+const LOGGER_KEYS = new Set(['level']);
+/**
+ * Validate the plugin configuration object, throwing an error if invalid
+ * @param input - the unvalidated configuration object
+ * @return the typed and validated configuration object
+ */
+export function validate(input) {
+    if (input === undefined)
+        return {};
+    const errors = [];
+    if (!isRecord(input)) {
+        throw new Error(`[${NAME}] Invalid config:\n- Expected plugin config to be an object`);
+    }
+    for (const key of Object.keys(input)) {
+        if (!CONFIG_KEYS.has(key)) {
+            errors.push(`Unknown config key: ${key}`);
+        }
+    }
+    if ('runtime' in input && input.runtime !== undefined && !isRuntime(input.runtime)) {
+        errors.push("runtime must be 'auto', 'node', or 'bun'");
+    }
+    if ('url' in input && input.url !== undefined) {
+        if (typeof input.url !== 'string') {
+            errors.push('url must be a string');
+        }
+        else {
+            try {
+                const url = new URL(input.url);
+                if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+                    errors.push('url must use http:// or https://');
+                }
+            }
+            catch {
+                errors.push('url must be a valid URL');
+            }
+        }
+    }
+    if ('precompress' in input && input.precompress !== undefined) {
+        if (typeof input.precompress !== 'boolean') {
+            errors.push('precompress must be a boolean');
+        }
+    }
+    if ('trustedOrigins' in input && input.trustedOrigins !== undefined) {
+        if (!Array.isArray(input.trustedOrigins)) {
+            errors.push('trustedOrigins must be an array of origins');
+        }
+        else {
+            for (const [index, value] of input.trustedOrigins.entries()) {
+                if (typeof value !== 'string') {
+                    errors.push(`trustedOrigins[${index}] must be a string`);
+                    continue;
+                }
+                try {
+                    const url = new URL(value);
+                    const canonical = value.replace(/\/$/, '');
+                    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+                        errors.push(`trustedOrigins[${index}] must use http:// or https://`);
+                        continue;
+                    }
+                    if (canonical !== url.origin) {
+                        errors.push(`trustedOrigins[${index}] must be an origin without a path, query, or hash`);
+                    }
+                }
+                catch {
+                    errors.push(`trustedOrigins[${index}] must be a valid URL origin`);
+                }
+            }
+        }
+    }
+    if ('sitemap' in input && input.sitemap !== undefined && input.sitemap !== false) {
+        if (typeof input.sitemap !== 'boolean' && typeof input.sitemap !== 'object') {
+            errors.push('sitemap must be a boolean or an object with a routes function');
+        }
+        if (typeof input.sitemap === 'object' &&
+            input.sitemap !== null &&
+            typeof input.sitemap.routes !== 'function') {
+            errors.push('sitemap.routes must be a function');
+        }
+    }
+    if ('prerender' in input && input.prerender !== undefined) {
+        if (!new Set(PRERENDER_MODES).has(input.prerender)) {
+            errors.push("prerender must be 'full', 'ppr', or false");
+        }
+    }
+    if ('trailingSlash' in input && input.trailingSlash !== undefined) {
+        if (typeof input.trailingSlash !== 'string' ||
+            !new Set(TRAILING_SLASH_MODES).has(input.trailingSlash)) {
+            errors.push("trailingSlash must be 'always', 'never', or 'ignore'");
+        }
+    }
+    if ('metadata' in input && input.metadata !== undefined && !isRecord(input.metadata)) {
+        errors.push('metadata must be an object when provided');
+    }
+    if ('logger' in input && input.logger !== undefined) {
+        if (!isRecord(input.logger)) {
+            errors.push('logger must be an object when provided');
+        }
+        else {
+            for (const key of Object.keys(input.logger)) {
+                if (!LOGGER_KEYS.has(key)) {
+                    errors.push(`Unknown logger key: ${key}`);
+                }
+            }
+            if ('level' in input.logger && input.logger.level !== undefined) {
+                if (typeof input.logger.level !== 'string' ||
+                    !new Set(LOG_LEVELS).has(input.logger.level)) {
+                    errors.push('logger.level must be one of: debug, info, warn, error, fatal');
+                }
+            }
+        }
+    }
+    if (errors.length > 0) {
+        throw new Error(`[${NAME}] Invalid config:\n- ${errors.join('\n- ')}`);
+    }
+    return input;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isRuntime(value) {
+    return typeof value === 'string' && new Set(Config.RUNTIMES).has(value);
+}

package/dist/events.d.ts

@@ -0,0 +1,4 @@
+export declare const names: {
+    readonly NAVIGATION: `${string}navigation`;
+    readonly NAVIGATION_ERROR: `${string}navigationerror`;
+};

package/dist/events.js

@@ -0,0 +1,5 @@
+import * as Config from './config.js';
+export const names = {
+    NAVIGATION: `${Config.SLUG}navigation`,
+    NAVIGATION_ERROR: `${Config.SLUG}navigationerror`,
+};

package/dist/index.d.ts

@@ -2,6 +2,5 @@ import { type PluginOption } from 'vite';
 import type { PluginConfig } from './types.js';
 declare function solas(c?: PluginConfig): PluginOption[];
 export default solas;
-export type * from './solas.d.ts';
-export { Solas } from './solas.js';
+export * as Solas from './solas.js';
 export type * from './types.js';