@jk2908/solas 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jerome Kenway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

package/README.md

@@ -0,0 +1,333 @@
+# Solas
+
+Solas is a minimal React meta-framework powered by Vite, created for experimenting with routing, streaming, and prerendering with React Server Components.
+
+It has not been rigorously tested yet (there are currently no automated tests) ... and broken behaviour should be expected.
+
+## Install
+
+```sh
+npm install @jk2908/solas react react-dom react-server-dom-webpack vite
+npm install -D @vitejs/plugin-react typescript vite-tsconfig-paths
+```
+
+## Use
+
+Create a Vite config that registers Solas.
+
+```ts
+import { defineConfig } from 'vite'
+
+import solas from '@jk2908/solas'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+	plugins: [solas(), react()],
+})
+```
+
+## Structure
+
+Put your routes in `app/`.
+
+```text
+app/
+	+layout.tsx
+	+page.tsx
+	+middleware.ts
+	+loading.tsx
+	+401.tsx
+	+403.tsx
+	+404.tsx
+	+500.tsx
+	about/
+		+layout.tsx
+		+page.tsx
+	api/
+		+endpoint.ts
+	posts/
+		[id]/
+			+page.tsx
+```
+
+Use these filename conventions:
+
+- `+layout.tsx`: shared layout for a route branch.
+- `+page.tsx`: page component for a route.
+- `+endpoint.ts`: request handler for non-page routes.
+- `+middleware.ts`: middleware that runs for the current route branch and is inherited by child routes. Parent and child middleware stack together.
+- `+loading.tsx`: loading fallback inherited by child routes.
+- `+401.tsx`: boundary for unauthorised responses in the current route branch and its children.
+- `+403.tsx`: boundary for forbidden responses in the current route branch and its children.
+- `+404.tsx`: boundary for not found responses in the current route branch and its children.
+- `+500.tsx`: boundary for server errors in the current route branch and its children.
+
+Nested folders create nested routes. Dynamic segments use `[param]`, and catch-all segments use `[...param]`.
+
+Status boundaries follow the same override pattern as layouts: a child route uses the nearest matching boundary file above it, and a more specific boundary replaces a parent one.
+
+## Config
+
+All Solas options are passed to `solas()` inside `defineConfig`.
+
+### `url`
+
+Use `url` to tell Solas what the public application origin is.
+
+`url` is optional.
+
+This happens inside `solas()` when the plugin builds its validated config object. Solas assigns `config.url` with this lookup order:
+
+- `config.url`
+- `VITE_APP_URL`
+- `APP_URL`
+
+Current behaviour:
+
+- Solas reads that value during plugin configuration.
+- Solas injects `APP_URL` and `VITE_APP_URL` into `import.meta.env`.
+- The current Solas runtime does not otherwise require `config.url` for routing, build, or prerender to work.
+
+In practice, that means you do not have to pass `url` unless your application code wants a canonical origin value, or you want to standardise that value in config rather than relying on environment variables.
+
+If you do want to set it explicitly, this is the shape:
+
+```ts
+export default defineConfig(({ mode }) => ({
+	plugins: [
+		solas({
+			url: mode === 'production' ? 'https://example.com' : 'http://localhost:8787',
+		}),
+	],
+}))
+```
+
+If you prefer environment variables, set one of these instead:
+
+```sh
+APP_URL=https://example.com
+```
+
+```sh
+VITE_APP_URL=https://example.com
+```
+
+### `port`
+
+Use `port` to change the development server port.
+
+Default: `8787`
+
+```ts
+export default defineConfig({
+	plugins: [
+		solas({
+			port: 4000,
+		}),
+	],
+})
+```
+
+### `precompress`
+
+Use `precompress` to control whether Solas writes compressed build assets.
+
+Default: `true`
+
+```ts
+export default defineConfig({
+	plugins: [
+		solas({
+			precompress: false,
+		}),
+	],
+})
+```
+
+### `prerender`
+
+Use `prerender` to set the default prerender mode for the app. Valid values are `full`, `ppr`, and `false`.
+
+Default: `false`
+
+- `false`: do not prerender the route.
+- `full`: render the full route to HTML at build time.
+- `ppr`: prerender a static shell and defer dynamic regions to request time.
+
+```ts
+export default defineConfig({
+	plugins: [
+		solas({
+			prerender: 'ppr',
+		}),
+	],
+})
+```
+
+This value is only the default. Route files can override it with `export const prerender = ...`, and the nearest explicit export wins.
+
+```ts
+// vite.config.ts
+export default defineConfig({
+	plugins: [solas({ prerender: 'full' })],
+})
+```
+
+```tsx
+// app/about/+layout.tsx
+export const prerender = 'ppr'
+```
+
+```tsx
+// app/about/team/+page.tsx
+export const prerender = false
+```
+
+In that example, the app default is `full`, the `about` layout overrides it to `ppr`, and the page overrides it again to `false`.
+
+For dynamic routes, prerendering uses the params you export from the page:
+
+```tsx
+export const params = () => [{ id: 'post-1' }, { id: 'post-2' }]
+export const prerender = 'full'
+```
+
+In `ppr` mode, Solas prerenders the shell and lets you defer parts of the tree to request time.
+
+Use `dynamic()` inside a Suspense boundary to mark a subtree as request-time only:
+
+```tsx
+import { Suspense } from 'react'
+
+import { dynamic } from '@jk2908/solas/server'
+
+export const prerender = 'ppr'
+
+export default function Page() {
+	return (
+		<Suspense fallback={<div>Loading...</div>}>
+			<Ts />
+		</Suspense>
+	)
+}
+
+async function Ts() {
+	dynamic()
+	return <div>{Date.now()}</div>
+}
+```
+
+During prerender, `dynamic()` suspends so the nearest Suspense fallback is written into the static shell. At request time, the deferred content resolves normally.
+
+If you call `dynamic()` outside `ppr` mode, Solas does not defer that subtree. In `full` mode it logs a warning and the component still renders at build time.
+
+`headers()`, `cookies()`, and `url()` also mark the current render path as dynamic, so they should be treated the same way when you are building a `ppr` shell.
+
+### `metadata`
+
+Use `metadata` to set default document metadata.
+
+```ts
+export default defineConfig({
+	plugins: [
+		solas({
+			metadata: {
+				title: '%s - Solas',
+				meta: [
+					{
+						name: 'description',
+						content: 'My Solas app',
+					},
+				],
+			},
+		}),
+	],
+})
+```
+
+This is also only the default. Route metadata is merged in order, so config metadata can be extended or overridden by the shell, layouts, page, and status boundaries. The later, more specific route metadata wins for titles and duplicate tags.
+
+```tsx
+// vite.config.ts
+solas({
+	metadata: {
+		title: '%s - Solas',
+	},
+})
+
+// app/+layout.tsx
+export const metadata = {
+	title: 'Docs',
+}
+
+// app/guides/+page.tsx
+export const metadata = {
+	title: 'Routing',
+}
+```
+
+In that example, the final page title becomes `Routing - Solas`.
+
+### `trailingSlash`
+
+Use `trailingSlash` when you want generated routes to end with `/`.
+
+Default: `false`
+
+```ts
+export default defineConfig({
+	plugins: [
+		solas({
+			trailingSlash: true,
+		}),
+	],
+})
+```
+
+### `logger.level`
+
+Use `logger.level` to control internal Solas logging.
+
+Default: `info`
+
+Valid values are `debug`, `info`, `warn`, `error`, and `fatal`.
+
+- `debug`: show everything
+- `info`: the default
+- `warn`: only warnings and errors
+- `error`: only errors
+- `fatal`: only fatal errors
+
+This is mainly useful when debugging framework behaviour such as routing and prerendering. It is for Solas internals, not your app's general-purpose logging, and it does not control top-level CLI status output such as build and preview progress messages.
+
+```ts
+export default defineConfig({
+	plugins: [
+		solas({
+			logger: {
+				level: process.env.NODE_ENV === 'production' ? 'fatal' : 'info',
+			},
+		}),
+	],
+})
+```
+
+## Scripts
+
+Add scripts to your app:
+
+```json
+{
+	"scripts": {
+		"dev": "solas dev",
+		"build": "solas build",
+		"preview": "solas preview"
+	}
+}
+```
+
+## Commands
+
+- `solas dev` starts the development server.
+- `solas build` creates a production build, prerenders configured routes, and writes compressed assets when enabled.
+- `solas preview` serves the built app for local verification.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/cli.js

@@ -0,0 +1,219 @@
+#!/usr/bin/env bun
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { Solas } from './solas';
+import { Compress } from './utils/compress';
+import { Logger } from './utils/logger';
+import { Prerender } from './internal/prerender';
+const logger = new Logger();
+const DEFAULT_PREVIEW_PORT = 4173;
+async function build() {
+    process.env.NODE_ENV = 'production';
+    const cwd = process.cwd();
+    const manifestPath = path.join(cwd, Solas.Config.GENERATED_DIR, 'build.json');
+    // run vite build
+    logger.info('[build]', 'running vite build...');
+    const vite = Bun.spawnSync(['bunx', '--bun', 'vite', 'build', '--mode', 'production'], {
+        cwd,
+        stdout: 'inherit',
+        stderr: 'inherit',
+        env: { ...process.env, NODE_ENV: 'production' },
+    });
+    if (vite.exitCode !== 0) {
+        logger.error('[build] vite build failed');
+        process.exit(1);
+    }
+    // read build manifest
+    let manifest;
+    try {
+        const raw = await fs.readFile(manifestPath, 'utf-8');
+        manifest = JSON.parse(raw);
+    }
+    catch {
+        logger.error('[build] failed to read build manifest');
+        process.exit(1);
+    }
+    const outDir = path.resolve(cwd, Solas.Config.OUT_DIR);
+    const rscDir = path.join(outDir, 'rsc');
+    const artifactRoot = Prerender.Artifact.getRootPath(outDir);
+    // clear old prerender artifacts so routes that have switched modes
+    // do not keep stale metadata from a previous build
+    await fs.rm(artifactRoot, { recursive: true, force: true });
+    // prerender routes
+    if (manifest.prerenderedRoutes.length > 0) {
+        const timeout = Prerender.Build.getTimeout();
+        const concurrency = Prerender.Build.getConcurrency();
+        const artifactManifestRoutes = {};
+        logger.info('[prerender]', `prerendering ${manifest.prerenderedRoutes.length} routes (timeout: ${timeout}ms, concurrency: ${concurrency})...`);
+        // ensure production mode for React
+        process.env.NODE_ENV = 'production';
+        const rscEntry = path.join(rscDir, 'index.js');
+        const { default: app } = await import(/* @vite-ignore */ rscEntry);
+        for await (const result of Prerender.Build.run(app, manifest.prerenderedRoutes, {
+            timeout,
+            concurrency,
+        })) {
+            const route = result.route;
+            try {
+                const routeDir = route === '/' ? '' : route.replace(/^\//, '');
+                // folder for this route's build notes/files
+                const artifactDir = Prerender.Artifact.getPath(outDir, route);
+                if ('error' in result)
+                    throw result.error;
+                if ('status' in result) {
+                    logger.warn('[prerender]', `skipped ${route}: ${result.status}`);
+                    continue;
+                }
+                const artifact = result.artifact;
+                if (artifact.mode === 'ppr') {
+                    // for ppr we save the shell now, and the delayed part for later
+                    await fs.mkdir(artifactDir, { recursive: true });
+                    const writes = [
+                        Bun.write(path.join(artifactDir, 'prelude.html'), artifact.html),
+                        Bun.write(path.join(artifactDir, 'metadata.json'), JSON.stringify({
+                            schema: artifact.schema,
+                            route: artifact.route,
+                            createdAt: artifact.createdAt,
+                            mode: artifact.mode,
+                        })),
+                    ];
+                    if (artifact.postponed !== undefined) {
+                        writes.push(Bun.write(path.join(artifactDir, 'postponed.json'), JSON.stringify(artifact.postponed)));
+                    }
+                    await Promise.all(writes);
+                    artifactManifestRoutes[route] = {
+                        mode: artifact.mode,
+                        createdAt: artifact.createdAt,
+                        files: artifact.postponed !== undefined
+                            ? ['metadata', 'prelude', 'postponed']
+                            : ['metadata', 'prelude'],
+                    };
+                    logger.info('[prerender:artifacts]', JSON.stringify({
+                        route,
+                        prelude: artifact.html,
+                        postponed: artifact.postponed ?? null,
+                        metadata: {
+                            schema: artifact.schema,
+                            route: artifact.route,
+                            createdAt: artifact.createdAt,
+                            mode: artifact.mode,
+                        },
+                    }));
+                    logger.info('[prerender]', `${route} (ppr)`);
+                    continue;
+                }
+                // @todo: hash files
+                // even for full pages, write metadata so preview/runtime knows to serve built html
+                await fs.mkdir(artifactDir, { recursive: true });
+                await Bun.write(path.join(artifactDir, 'metadata.json'), JSON.stringify({
+                    schema: artifact.schema,
+                    route: artifact.route,
+                    createdAt: artifact.createdAt,
+                    mode: artifact.mode,
+                }));
+                const outPath = route === '/'
+                    ? path.join(outDir, 'index.html')
+                    : path.join(outDir, routeDir, 'index.html');
+                await fs.mkdir(path.dirname(outPath), { recursive: true });
+                await Bun.write(outPath, artifact.html);
+                artifactManifestRoutes[route] = {
+                    mode: artifact.mode,
+                    createdAt: artifact.createdAt,
+                    files: ['metadata', 'html'],
+                };
+                logger.info('[prerender]', `${route} (full)`);
+            }
+            catch (err) {
+                logger.error('[prerender]', `failed ${route}: ${err}. This often means unresolved async work (for example external fetches or dynamic rendering in full mode).`);
+            }
+        }
+        await fs.mkdir(artifactRoot, { recursive: true });
+        await Bun.write(Prerender.Artifact.getManifestPath(outDir), JSON.stringify({
+            generatedAt: Date.now(),
+            routes: artifactManifestRoutes,
+        }));
+    }
+    // precompress
+    if (manifest.precompress) {
+        logger.info('[precompress]', 'compressing assets...');
+        for await (const { input, compressed } of Compress.run(outDir, {
+            filter: f => /\.(js|css|html|svg|json|txt)$/.test(f),
+        })) {
+            await Bun.write(`${input}.br`, compressed);
+            logger.info('[precompress]', `${path.basename(input)}.br`);
+        }
+    }
+    // cleanup
+    await fs.unlink(manifestPath).catch(() => { });
+    logger.info('[build]', 'done');
+}
+async function dev() {
+    const proc = Bun.spawn(['bunx', '--bun', 'vite', 'dev'], {
+        cwd: process.cwd(),
+        stdout: 'inherit',
+        stderr: 'inherit',
+        stdin: 'inherit',
+        env: { ...process.env, NODE_ENV: 'development' },
+    });
+    await proc.exited;
+}
+async function preview() {
+    process.env.NODE_ENV = 'production';
+    const cwd = process.cwd();
+    const outDir = path.resolve(cwd, Solas.Config.OUT_DIR);
+    const rscDir = path.join(outDir, 'rsc');
+    const rscEntry = path.join(rscDir, 'index.js');
+    const portFlagIndex = args.findIndex(arg => arg === '--port' || arg === '-p');
+    const parsedPort = portFlagIndex >= 0 && args[portFlagIndex + 1]
+        ? Number(args[portFlagIndex + 1])
+        : DEFAULT_PREVIEW_PORT;
+    if (!Number.isInteger(parsedPort) || parsedPort <= 0 || parsedPort > 65535) {
+        logger.error(`[preview] invalid port: ${args[portFlagIndex + 1] ?? 'undefined'}`);
+        process.exit(1);
+    }
+    // import RSC server (handles prerendered HTML, static assets, and ssr)
+    try {
+        await fs.access(rscEntry);
+    }
+    catch {
+        logger.error(`[preview] missing ${path.relative(cwd, rscEntry)} - run \`${Solas.Config.SLUG} build\` first`);
+        process.exit(1);
+    }
+    const { default: app } = await import(/* @vite-ignore */ rscEntry);
+    try {
+        Bun.serve({
+            port: parsedPort,
+            fetch: app.fetch,
+        });
+    }
+    catch (err) {
+        logger.error(`[preview] failed to start on port ${parsedPort}: ${err}`);
+        process.exit(1);
+    }
+    logger.info('[preview]', `server running at http://localhost:${parsedPort}`);
+    // keep alive
+    await new Promise(() => { });
+}
+// cli entry point
+const [, , command, ...args] = process.argv;
+switch (command) {
+    case 'build':
+        await build();
+        break;
+    case 'dev':
+        await dev();
+        break;
+    case 'preview':
+        await preview();
+        break;
+    default:
+        console.log(`
+			${Solas.Config.NAME} - cli
+
+			Commands:
+				build    Build for production (vite build + prerender + compress)
+				dev      Start development server
+				preview  Preview production build (serves prerendered HTML with SSR fallback)
+		`);
+        process.exit(command ? 1 : 0);
+}

package/dist/error-boundary.d.ts

@@ -0,0 +1 @@
+export { ErrorBoundary } from './internal/ui/error-boundary';

package/dist/error-boundary.js

@@ -0,0 +1 @@
+export { ErrorBoundary } from './internal/ui/error-boundary';

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import type { PluginOption } from 'vite';
+import type { PluginConfig } from './types';
+declare function solas(c: PluginConfig): PluginOption[];
+export default solas;
+export { Solas } from './solas';
+export type * from './solas.d.ts';
+export type * from './types';