@briancray/belte 0.1.0

package/src/sveltePlugin.ts

@@ -0,0 +1,58 @@
+import type { BunPlugin } from 'bun'
+import { compile, compileModule, preprocess } from 'svelte/compiler'
+import type { SvelteConfig } from './lib/server/runtime/types/SvelteConfig.ts'
+import { log } from './lib/shared/log.ts'
+import { tailwindStylePreprocessor } from './tailwindStylePreprocessor.ts'
+
+/*
+Bun plugin that compiles `.svelte` components (with CSS injected at runtime)
+and `.svelte.{js,ts}` rune modules via the svelte compiler. `.svelte.ts`
+modules are first transpiled by Bun.Transpiler so the svelte compiler only
+sees stripped JS. `generate` chooses 'server' (SSR) or 'client' (hydration);
+the build pipeline constructs a separate plugin instance per target.
+*/
+export function sveltePlugin(options: {
+    generate: 'server' | 'client'
+    svelteConfig?: SvelteConfig
+}): BunPlugin {
+    return {
+        name: 'svelte-loader',
+        async setup(build) {
+            const compileOptions = options.svelteConfig?.compilerOptions ?? {}
+            const tsTranspiler = new Bun.Transpiler({ loader: 'ts' })
+            const tailwindPreprocessor = await tailwindStylePreprocessor()
+            build.onLoad({ filter: /\.svelte\.(js|ts)$/ }, async (args) => {
+                const raw = await Bun.file(args.path).text()
+                const source = args.path.endsWith('.ts') ? tsTranspiler.transformSync(raw) : raw
+                const { js, warnings } = compileModule(source, {
+                    ...compileOptions,
+                    filename: args.path,
+                    generate: options.generate,
+                    dev: false,
+                })
+                for (const warning of warnings) {
+                    log.warn(`svelte ${args.path}: ${warning.message}`)
+                }
+                return { contents: js.code, loader: 'js' }
+            })
+
+            build.onLoad({ filter: /\.svelte$/ }, async (args) => {
+                const raw = await Bun.file(args.path).text()
+                const source = tailwindPreprocessor
+                    ? (await preprocess(raw, tailwindPreprocessor, { filename: args.path })).code
+                    : raw
+                const { js, warnings } = compile(source, {
+                    ...compileOptions,
+                    filename: args.path,
+                    generate: options.generate,
+                    css: 'injected',
+                    dev: false,
+                })
+                for (const warning of warnings) {
+                    log.warn(`svelte ${args.path}: ${warning.message}`)
+                }
+                return { contents: js.code, loader: 'js' }
+            })
+        },
+    }
+}

package/src/tailwindStylePreprocessor.ts

@@ -0,0 +1,62 @@
+import type { PreprocessorGroup } from 'svelte/compiler'
+
+/*
+Svelte preprocessor that runs Tailwind v4 over each component `<style>` block.
+Without this, directives like `@apply` and `@import "tailwindcss/theme" reference;`
+pass straight through the Svelte compiler into the bundle — the `@import` becomes
+a runtime fetch and `@apply` is dropped silently. `bun-plugin-tailwind` only
+processes `.css` files, so scoped styles need this hook instead.
+
+Returns undefined when `tailwindcss` isn't installed, so consumers without
+Tailwind get the same behaviour as before.
+*/
+
+function dirname(filepath: string): string {
+    const lastSlash = filepath.lastIndexOf('/')
+    return lastSlash === -1 ? '' : filepath.slice(0, lastSlash)
+}
+
+function fileUrlToPath(href: string): string {
+    return new URL(href).pathname
+}
+
+function pathToFileUrl(path: string): string {
+    return new URL(path, 'file://').href
+}
+
+export async function tailwindStylePreprocessor(): Promise<PreprocessorGroup | undefined> {
+    let tailwind: typeof import('tailwindcss')
+    try {
+        tailwind = await import('tailwindcss')
+    } catch {
+        return undefined
+    }
+    const TAILWIND_DIRECTIVE = /@(?:apply|reference|tailwind|import\s+["']tailwindcss)/
+    return {
+        name: 'belte-tailwind-style',
+        async style({ content, filename }) {
+            if (!TAILWIND_DIRECTIVE.test(content)) {
+                return undefined
+            }
+            const base = filename ? dirname(filename) : process.cwd()
+            const result = await tailwind.compile(content, {
+                base,
+                loadStylesheet: async (uri, fromBase) => {
+                    const fromUrl = pathToFileUrl(`${fromBase}/`)
+                    const resolved = fileUrlToPath(import.meta.resolve(uri, fromUrl))
+                    return {
+                        path: resolved,
+                        base: dirname(resolved),
+                        content: await Bun.file(resolved).text(),
+                    }
+                },
+                loadModule: async () => {
+                    throw new Error(
+                        'Tailwind plugins/configs in component <style> blocks are not supported',
+                    )
+                },
+            })
+            return { code: result.build([]) }
+        },
+    }
+}

package/template/package.json

@@ -0,0 +1,16 @@
+{
+    "name": "belte-app",
+    "version": "0.0.1",
+    "private": true,
+    "type": "module",
+    "scripts": {
+        "dev": "belte dev",
+        "build": "belte build",
+        "start": "belte start",
+        "compile": "belte compile"
+    },
+    "dependencies": {
+        "@briancray/belte": "^0.1.0",
+        "svelte": "^5.0.0"
+    }
+}

package/template/src/app.ts

@@ -0,0 +1,23 @@
+/*
+Optional application hooks. Every export is optional; delete the ones you
+don't need. Belte resolves this file at build time via the belte:app virtual
+module — no import is needed from your own code.
+
+  init        runs once after Bun.serve is up; return a cleanup for SIGINT/SIGTERM
+  handle      middleware wrapping the default request pipeline
+  handleError custom 500 fallback
+*/
+import type { AppModule } from 'belte/server/AppModule'
+
+export const init: AppModule['init'] = ({ server }) => {
+    console.log(`server listening on http://localhost:${server.port}`)
+}
+
+export const handle: AppModule['handle'] = async (request, next) => {
+    return next(request)
+}
+
+export const handleError: AppModule['handleError'] = (error) => {
+    console.error(error)
+    return new Response('something went wrong', { status: 500 })
+}

package/template/src/browser/app.css

@@ -0,0 +1,21 @@
+/*
+Global stylesheet. Imported once from src/browser/pages/layout.svelte so it ships
+with every page. To enable Tailwind v4, add `bun-plugin-tailwind` and
+`tailwindcss` as devDependencies and replace this file with:
+
+    @import "tailwindcss";
+*/
+
+:root {
+    font-family: system-ui, sans-serif;
+    color: #1f2937;
+    background: #f8fafc;
+}
+
+body {
+    margin: 0;
+}
+
+a {
+    color: inherit;
+}

package/template/src/browser/app.html

@@ -0,0 +1,24 @@
+<!--
+Optional HTML shell. If present at src/browser/app.html, belte uses this as the SSR
+template; otherwise a default shell is used. The three comment markers below
+are replaced at render time:
+  ssr:head     rendered <head> from Svelte (title, meta, link tags)
+  ssr:body     rendered page body
+  ssr:state    cache snapshot + route info for hydration
+See their usage further down (wrapped as HTML comments).
+Delete this file to use the default shell.
+-->
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<link rel="stylesheet" href="/_app/client.css" />
+<!--ssr:head-->
+</head>
+<body>
+<div id="app"><!--ssr:body--></div>
+<!--ssr:state-->
+<script type="module" src="/_app/client.js"></script>
+</body>
+</html>

package/template/src/browser/pages/about/page.svelte

@@ -0,0 +1,5 @@
+<!--
+A second page — served at GET /about. Folder name becomes the URL segment.
+-->
+<h1>About</h1>
+<p>This is a barebones belte app.</p>

package/template/src/browser/pages/layout.svelte

@@ -0,0 +1,26 @@
+<!--
+Root layout. Wraps every page below src/browser/pages/. Layouts are nearest-only:
+the deepest matching layout.svelte runs and replaces ancestors — they don't
+stack. To inherit chrome in a nested layout, extract a snippet and
+{@render} it from each layout. Layouts run on both the server (during SSR)
+and the client (after hydration).
+-->
+<script lang="ts">
+import '../app.css'
+
+let { children }: { children: import('svelte').Snippet } = $props()
+</script>
+
+<svelte:head>
+    <title>belte app</title>
+</svelte:head>
+
+<header>
+    <nav>
+        <a href="/">Home</a>
+        <a href="/about">About</a>
+    </nav>
+</header>
+<main>
+    {@render children()}
+</main>

package/template/src/browser/pages/page.svelte

@@ -0,0 +1,20 @@
+<!--
+Root page — served at GET /. Every folder under src/browser/pages/ that
+contains a page.svelte mounts at that folder's URL.
+-->
+<script lang="ts">
+import { cache } from 'belte/browser/cache'
+import { getHello } from '$server/rpc/getHello.ts'
+
+/*
+Top-level await runs on the server during SSR. The decoded body is captured
+into the per-request cache, serialized into the HTML, and replayed on the
+client during hydration — no second fetch. `cache(fn)()` returns the
+Content-Type-decoded value (JSON object, string, or Blob); reach for
+`.raw(args)` if you need the underlying Response.
+*/
+const hello = await cache(getHello)()
+</script>
+
+<h1>{hello.message}</h1>
+<p>Edit <code>src/browser/pages/page.svelte</code> and the page hot-reloads.</p>

package/template/src/cli/banner.txt

@@ -0,0 +1,3 @@
+┌───────────────┐
+│   belte app   │
+└───────────────┘

package/template/src/cli/footer.txt

@@ -0,0 +1 @@
+Run `<command> --help` for command-specific flags.

package/template/src/server/rpc/getHello.ts

@@ -0,0 +1,33 @@
+/*
+RPC module — every file under src/server/rpc/ exposes exactly one verb-bound remote
+function. The filename is the export name and the URL path (under `/rpc/`),
+and the imported verb (GET / POST / PUT / PATCH / DELETE / HEAD) picks the
+HTTP method. The bundler swaps the runtime per build target: direct call on
+the server, fetch over the network on the client.
+
+Args (what the caller passes in) come from the handler's parameter type —
+either an inline annotation or an explicit `GET<{ id: string }>(...)`
+generic. Return (what the caller receives after Content-Type-driven
+decoding) is inferred from the handler's return type via the
+`TypedResponse<T>` brand on `json`/`error`/`redirect`/`jsonl`/`sse`, so
+plain `GET(() => json({...}))` already types end-to-end.
+
+For inbound validation pass a Standard Schema-compatible schema as the
+second argument: `GET(fn, { schema })`. Args then infers from the schema's
+output type and the server replies with 422 on validation failure.
+
+`json(...)` from `belte/server/json` is a thin wrapper over `Response.json`
+that defaults `Cache-Control: no-store`, since intermediary caches shouldn't
+memoise rpc replies (the framework's per-request cache handles in-process
+dedupe). Other helpers are siblings, one per file: `belte/server/error`,
+`belte/server/redirect`, `belte/server/sse`, `belte/server/jsonl`.
+
+Every rpc value also exposes `.raw(args?)` (returns the underlying
+`Response`) and `.stream(args?)` (returns a `Subscribable` view of the body)
+for callers that need headers/status or want to iterate SSE/JSONL frames.
+*/
+
+import { GET } from 'belte/server/GET'
+import { json } from 'belte/server/json'
+
+export const getHello = GET(() => json({ message: 'Hello from belte' }))

package/template/svelte.config.js

@@ -0,0 +1,12 @@
+/*
+Optional Svelte compiler configuration. Same shape as upstream Svelte.
+Delete this file to use defaults.
+*/
+
+/** @type {import('belte').SvelteConfig} */
+export default {
+    compilerOptions: {
+        // Opt in to top-level await inside Svelte components.
+        experimental: { async: true },
+    },
+}

package/template/tsconfig.json

@@ -0,0 +1,18 @@
+{
+    "extends": "belte/tsconfig",
+    "include": ["src/**/*.ts", "src/**/*.svelte"],
+    "compilerOptions": {
+        "paths": {
+            "$server": ["./src/server"],
+            "$server/*": ["./src/server/*"],
+            "$browser": ["./src/browser"],
+            "$browser/*": ["./src/browser/*"],
+            "$shared": ["./src/shared"],
+            "$shared/*": ["./src/shared/*"],
+            "$mcp": ["./src/mcp"],
+            "$mcp/*": ["./src/mcp/*"],
+            "$cli": ["./src/cli"],
+            "$cli/*": ["./src/cli/*"]
+        }
+    }
+}

package/tsconfig.app.json

@@ -0,0 +1,16 @@
+{
+    "compilerOptions": {
+        "target": "ESNext",
+        "module": "ESNext",
+        "moduleResolution": "bundler",
+        "lib": ["ESNext", "DOM", "DOM.Iterable"],
+        "strict": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "allowImportingTsExtensions": true,
+        "verbatimModuleSyntax": true,
+        "noEmit": true,
+        "isolatedModules": true,
+        "types": ["bun"]
+    }
+}