@belte/belte 0.19.0

package/src/serverEntry.ts

@@ -0,0 +1,94 @@
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import * as appMod from './_virtual/app.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { appInfo } from './_virtual/app-info.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { assets } from './_virtual/assets.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import cliProgramName from './_virtual/cli-name.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { errors } from './_virtual/errors.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { layouts } from './_virtual/layouts.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import mcp from './_virtual/mcp.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { mcpResources } from './_virtual/mcp-resources.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { pages } from './_virtual/pages.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { prompts } from './_virtual/prompts.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { publicAssets } from './_virtual/public-assets.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { rpc } from './_virtual/rpc.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { shell } from './_virtual/shell.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { sockets } from './_virtual/sockets.ts'
+import { exitWithParent } from './lib/bundle/exitWithParent.ts'
+import { loadEnvFromBinaryDir } from './lib/cli/loadEnvFromBinaryDir.ts'
+import { createServer } from './lib/server/runtime/createServer.ts'
+import { requestContext } from './lib/server/runtime/requestContext.ts'
+import { createCacheStore } from './lib/shared/createCacheStore.ts'
+import { loadEnvFromDataDir } from './lib/shared/loadEnvFromDataDir.ts'
+import { runningAsStandaloneBinary } from './lib/shared/runningAsStandaloneBinary.ts'
+import { setCacheStoreResolver } from './lib/shared/setCacheStoreResolver.ts'
+import { setGlobalCacheStoreResolver } from './lib/shared/setGlobalCacheStoreResolver.ts'
+
+/*
+Resolve config into process.env before anything reads it (createServer reads
+PORT, app code reads Bun.env.*). Standalone-only: data-dir first so the user's
+saved config wins over the binary-dir shipped default; both back-fill only what
+the shell didn't already set. A bundle launched via `open` has cwd `/`, so the
+data-dir `.env` is how it gets its config at all. Under `bun dev`/`bun start`
+these bundle layers don't apply — the project's own CWD `.env` (Bun-autoloaded)
+is the config — so loading them would let a stray data-dir `PORT` defeat dev's
+port scan.
+*/
+if (runningAsStandaloneBinary()) {
+    await loadEnvFromDataDir(cliProgramName)
+    await loadEnvFromBinaryDir()
+}
+
+/*
+Eager-import src/server/config.ts (via belte:config) now that every .env layer
+is merged into process.env — its top-level `env(schema)` validates the
+environment and fails the boot loudly here, before the server starts, rather
+than lazily on the first handler that imports `$server/config`. A dynamic
+import (not a static top-level one) so it runs after the merge above, not at
+module-eval time. No-op when the file is absent.
+*/
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+await import('./_virtual/config.ts')
+
+// In a bundle, tie this server's life to the launcher's (no-op standalone).
+exitWithParent()
+
+setCacheStoreResolver(() => requestContext.getStore()?.cache)
+
+/*
+Process-level store for cache(fn, { global: true }) — one per server process,
+outlives every request so memoised external calls are shared across them.
+*/
+const globalCacheStore = createCacheStore()
+setGlobalCacheStoreResolver(() => globalCacheStore)
+
+await createServer({
+    pages,
+    rpc,
+    sockets,
+    prompts,
+    layouts,
+    errors,
+    shell,
+    app: appMod,
+    assets,
+    publicAssets,
+    mcpResources,
+    mcp,
+    cliProgramName,
+    appInfo,
+    // Set by the dev orchestrator (devEntry); mounts the live-reload channel.
+    dev: Bun.env.BELTE_DEV === '1',
+})

package/src/sveltePlugin.ts

@@ -0,0 +1,58 @@
+import type { BunPlugin } from 'bun'
+import { compile, compileModule, preprocess } from 'svelte/compiler'
+import { log } from './lib/shared/log.ts'
+import type { SvelteConfig } from './lib/shared/types/SvelteConfig.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.debug('belte: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.debug('belte: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/bunfig.toml

@@ -0,0 +1,4 @@
+[test]
+# Register belte's preload so `.svelte`/`.svelte.ts` rune modules compile
+# under `bun test` — same runtime as the server.
+preload = ["@briancray/belte/preload"]

package/template/package.json

@@ -0,0 +1,19 @@
+{
+    "name": "belte-app",
+    "version": "0.0.1",
+    "private": true,
+    "type": "module",
+    "scripts": {
+        "dev": "belte dev",
+        "build": "belte build",
+        "start": "belte start",
+        "compile": "belte compile",
+        "cli": "belte cli",
+        "bundle": "belte bundle",
+        "test": "bun test"
+    },
+    "dependencies": {
+        "@belte/belte": "^0.2.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/belte/server/AppModule'
+
+export const init: AppModule['init'] = () => {
+    // one-time setup; optionally return a cleanup to run on SIGINT/SIGTERM
+}
+
+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/belte/shared/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/config.ts

@@ -0,0 +1,17 @@
+/*
+Typed environment. `env(schema)` validates Bun.env against a Standard Schema at
+boot — a missing or malformed variable fails the boot with every issue listed,
+instead of surfacing as `undefined` inside a handler. Import `config` from
+`$server/config` anywhere server-side; it's typed from the schema.
+
+Belte eager-imports this file at boot (the belte:config virtual) — no import is
+needed from your own code. The floor below re-exports Bun.env untyped; swap it
+for a schema once you have required variables:
+
+  import { env } from '@belte/belte/server/env'
+  import { z } from 'zod'
+  export const config = env(z.object({ DATABASE_URL: z.string() }))
+
+Optional — delete this file to read Bun.env directly instead.
+*/
+export const config = Bun.env

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

@@ -0,0 +1,35 @@
+/*
+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 as `inputSchema` in the
+second argument: `GET(fn, { inputSchema })`. Args then infers from the
+schema's output type and the server replies with 422 on validation
+failure. An optional `outputSchema` describes the success body for the
+OpenAPI 200 response and the MCP tool output.
+
+`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/belte/server/GET'
+import { json } from '@belte/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('@briancray/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/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"]
+    }
+}