create-foldkit-app 0.25.0 → 0.27.0

package/README.md

@@ -1,6 +1,6 @@
 # create-foldkit-app
 
-Scaffolding CLI for new Foldkit applications. Creates a ready-to-run project with Vite, Tailwind CSS, TypeScript, [`@foldkit/vite-plugin`](https://www.npmjs.com/package/@foldkit/vite-plugin) for hot reloading with Model preservation, and your choice of starter example.
+Scaffolding CLI for new Foldkit applications. Creates a ready-to-run project with Vite, Tailwind CSS, TypeScript, [`@foldkit/vite-plugin`](https://www.npmjs.com/package/@foldkit/vite-plugin) for hot reloading with Model preservation, your choice of rendering mode, and a starter example for SPA scaffolds.
 
 ## Usage
 
@@ -14,7 +14,17 @@ yarn create foldkit-app
 bun create foldkit-app
 ```
 
-The CLI prompts you for a project name, starter example, and package manager. Pass `--name`, `--example`, and/or `--package-manager` to skip the matching prompts.
+The CLI prompts you for a project name, rendering mode, starter example, and package manager. Pass `--name`, `--rendering`, `--example`, and/or `--package-manager` to skip the matching prompts.
+
+## Rendering
+
+| Mode  | Description                                                                                                                                                                    |
+| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `spa` | Render entirely in the browser. Starts from your choice of starter example below.                                                                                              |
+| `ssg` | Prerender routes to static HTML at build time, then hydrate in the browser. Scaffolds a small routed app with a server entry and a prerender script.                           |
+| `ssr` | Render each request on a Node server, then hydrate in the browser. Scaffolds a counter whose Flags come from the request, plus an Effect HttpServer host and a `start` script. |
+
+The starter examples apply to `spa` rendering. The `ssg` and `ssr` modes scaffold their own starter apps.
 
 ## Examples
 

package/dist/commands/create.js

@@ -1,8 +1,9 @@
 import chalk from 'chalk';
-import { Console, Effect, FileSystem, Option, Path } from 'effect';
+import { Console, Effect, FileSystem, Match, Option, Path, pipe } from 'effect';
 import { Prompt } from 'effect/unstable/cli';
 import { spawnSync } from 'node:child_process';
 import { examples } from '../examples.js';
+import { Scaffold, renderings } from '../rendering.js';
 import { createProject } from '../utils/files.js';
 import { devCommand, installDependencies, } from '../utils/packages.js';
 import { validateProjectName } from '../validateName.js';
@@ -14,6 +15,14 @@ const promptForName = Prompt.text({
         onSome: message => Effect.fail(message),
     }),
 });
+const promptForRendering = Prompt.select({
+    message: 'Pick a rendering mode',
+    choices: renderings.map(({ value, title, description }) => ({
+        value,
+        title,
+        description,
+    })),
+});
 const promptForExample = Prompt.autoComplete({
     message: 'Pick a starting example',
     choices: examples.map(({ value, title, description }) => ({
@@ -31,20 +40,28 @@ const promptForPackageManager = Prompt.select({
         { value: 'bun', title: 'bun' },
     ],
 });
+const resolveScaffold = (rendering, maybeExample) => Match.value(rendering).pipe(Match.when('spa', () => pipe(maybeExample, Option.match({
+    onNone: () => promptForExample,
+    onSome: Effect.succeed,
+}), Effect.map(example => Scaffold.Spa({ example })))), Match.when('ssg', () => Effect.succeed(Scaffold.Ssg())), Match.when('ssr', () => Effect.succeed(Scaffold.Ssr())), Match.exhaustive);
 const resolveInput = (input) => Effect.gen(function* () {
     const name = yield* Option.match(input.name, {
         onNone: () => promptForName,
         onSome: Effect.succeed,
     });
-    const example = yield* Option.match(input.example, {
-        onNone: () => promptForExample,
+    const rendering = yield* Option.match(input.rendering, {
+        onNone: () => promptForRendering,
         onSome: Effect.succeed,
     });
+    if (rendering !== 'spa' && Option.isSome(input.example)) {
+        yield* Effect.fail('The --example flag only applies to spa rendering.');
+    }
+    const scaffold = yield* resolveScaffold(rendering, input.example);
     const packageManager = yield* Option.match(input.packageManager, {
         onNone: () => promptForPackageManager,
         onSome: Effect.succeed,
     });
-    return { name, example, packageManager };
+    return { name, scaffold, packageManager };
 });
 const validateProject = (name, projectPath, packageManager) => Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
@@ -60,16 +77,16 @@ const validateProject = (name, projectPath, packageManager) => Effect.gen(functi
         return yield* Effect.fail(`Package manager '${packageManager}' is not available. Please install it first.`);
     }
 });
-const setupProject = (name, projectPath, example, packageManager) => Effect.gen(function* () {
+const setupProject = (name, projectPath, scaffold, packageManager) => Effect.gen(function* () {
     yield* Console.log(chalk.blue('🚀 Creating your Foldkit app...'));
     yield* Console.log('');
-    yield* createProject(name, projectPath, example, packageManager);
+    yield* createProject(name, projectPath, scaffold, packageManager);
     yield* Console.log(chalk.green(`✅ Created project`));
     yield* Console.log('');
 });
-const installProjectDependencies = (projectPath, packageManager, example) => Effect.gen(function* () {
+const installProjectDependencies = (projectPath, packageManager, scaffold) => Effect.gen(function* () {
     yield* Console.log(chalk.blue(`📦 Installing dependencies with ${packageManager}...`));
-    yield* installDependencies(projectPath, packageManager, example);
+    yield* installDependencies(projectPath, packageManager, scaffold);
     yield* Console.log(chalk.green('✅ Dependencies installed'));
     yield* Console.log('');
 });
@@ -113,12 +130,12 @@ const displaySuccessMessage = (name, packageManager) => Effect.gen(function* ()
     yield* Console.log('');
 });
 export const create = (input) => Effect.gen(function* () {
-    const { name, example, packageManager } = yield* resolveInput(input);
+    const { name, scaffold, packageManager } = yield* resolveInput(input);
     const path = yield* Path.Path;
     const projectPath = path.resolve(name);
     yield* validateProject(name, projectPath, packageManager);
-    yield* setupProject(name, projectPath, example, packageManager);
-    yield* installProjectDependencies(projectPath, packageManager, example);
+    yield* setupProject(name, projectPath, scaffold, packageManager);
+    yield* installProjectDependencies(projectPath, packageManager, scaffold);
     yield* displaySuccessMessage(name, packageManager);
     return name;
 });

package/dist/index.js

@@ -6,6 +6,7 @@ import { createRequire } from 'node:module';
 import { NodeRuntime, NodeServices, NodeStdio } from '@effect/platform-node';
 import { create as create_ } from './commands/create.js';
 import { EXAMPLE_VALUES } from './examples.js';
+import { RENDERING_VALUES } from './rendering.js';
 import { validateProjectName } from './validateName.js';
 /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
 const packageJson = createRequire(import.meta.url)('../package.json');
@@ -14,7 +15,8 @@ const nameSchema = Schema.String.pipe(Schema.check(Schema.makeFilter(value => Op
     onSome: message => message,
 }))));
 const name = Flag.string('name').pipe(Flag.withAlias('n'), Flag.withDescription('The name of the project to create'), Flag.withSchema(nameSchema), Flag.optional);
-const example = Flag.choice('example', EXAMPLE_VALUES).pipe(Flag.withAlias('e'), Flag.withDescription("The example application to start from. Run with no flags for an interactive picker that shows each example's description."), Flag.optional);
+const rendering = Flag.choice('rendering', RENDERING_VALUES).pipe(Flag.withAlias('r'), Flag.withDescription('How the application renders: spa renders entirely in the browser, ssg prerenders routes to static HTML at build time, ssr renders each request on a Node server'), Flag.optional);
+const example = Flag.choice('example', EXAMPLE_VALUES).pipe(Flag.withAlias('e'), Flag.withDescription("The example application to start from with spa rendering. Run with no flags for an interactive picker that shows each example's description."), Flag.optional);
 const packageManager = Flag.choice('package-manager', [
     'pnpm',
     'npm',
@@ -23,6 +25,7 @@ const packageManager = Flag.choice('package-manager', [
 ]).pipe(Flag.withAlias('p'), Flag.withDescription('The package manager to use for installing dependencies'), Flag.optional);
 const create = Command.make('create', {
     name,
+    rendering,
     example,
     packageManager,
 }, create_).pipe(Command.withDescription('Create a new Foldkit application'));

package/dist/rendering.js

@@ -0,0 +1,20 @@
+import { Data } from 'effect';
+export const RENDERING_VALUES = ['spa', 'ssg', 'ssr'];
+export const renderings = [
+    {
+        value: 'spa',
+        title: 'SPA',
+        description: 'Render entirely in the browser',
+    },
+    {
+        value: 'ssg',
+        title: 'SSG',
+        description: 'Prerender routes to static HTML at build time, then hydrate in the browser',
+    },
+    {
+        value: 'ssr',
+        title: 'SSR',
+        description: 'Render each request on a Node server, then hydrate in the browser',
+    },
+];
+export const Scaffold = Data.taggedEnum();

package/dist/utils/files.js

@@ -72,11 +72,27 @@ const createPackageManagerFiles = (projectPath, packageManager) => Effect.gen(fu
     const packageManagerFiles = yield* getPackageManagerFiles(packageManager);
     yield* createFiles(projectPath, packageManagerFiles);
 });
-export const createProject = (name, projectPath, example, packageManager) => Effect.gen(function* () {
+const overlayRenderingFiles = (projectPath, directory) => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const templateRoot = yield* getTemplateRoot;
+    const renderingFiles = yield* getTemplateFiles(path.join(templateRoot, 'rendering', directory));
+    yield* createFiles(projectPath, renderingFiles);
+});
+const createRenderingFiles = (projectPath, scaffold) => Match.value(scaffold).pipe(Match.tagsExhaustive({
+    Spa: () => Effect.void,
+    Ssg: () => overlayRenderingFiles(projectPath, 'ssg'),
+    Ssr: () => overlayRenderingFiles(projectPath, 'ssr'),
+}));
+export const createProject = (name, projectPath, scaffold, packageManager) => Effect.gen(function* () {
     yield* createBaseFiles(projectPath);
+    yield* createRenderingFiles(projectPath, scaffold);
     yield* modifyBaseFiles(projectPath, name, packageManager);
     yield* createPackageManagerFiles(projectPath, packageManager);
-    yield* createExampleFiles(projectPath, example);
+    yield* Match.value(scaffold).pipe(Match.tagsExhaustive({
+        Spa: ({ example }) => createExampleFiles(projectPath, example),
+        Ssg: () => Effect.void,
+        Ssr: () => Effect.void,
+    }));
 });
 export const applyPackageManager = (readme, packageManager) => pipe(readme, String.replace('{{installCommand}}', installCommand(packageManager)), String.replace('{{devCommand}}', devCommand(packageManager)));
 const modifyBaseFiles = (projectPath, name, packageManager) => Effect.gen(function* () {

package/dist/utils/packages.js

@@ -1,4 +1,4 @@
-import { Array, Effect, FileSystem, Match, Order, Path, Record, Result, Schema, pipe, } from 'effect';
+import { Array, Data, Effect, FileSystem, Match, Order, Path, Record, Result, Schema, pipe, } from 'effect';
 import { HttpClient, HttpClientRequest } from 'effect/unstable/http';
 import { spawn } from 'node:child_process';
 export const installCommand = (packageManager) => `${packageManager} install`;
@@ -38,15 +38,16 @@ const TEMPLATE_DEV_DEPENDENCIES = [
     'prettier',
     'vitest',
 ];
+const SERVER_RENDERING_DEV_DEPENDENCIES = ['@types/node'];
 const isFoldkitPackage = (name) => name === 'foldkit' || name.startsWith(FOLDKIT_SCOPE_PREFIX);
-const Keep = (version) => ({ _tag: 'Keep', version });
-const Latest = { _tag: 'Latest' };
+const UnresolvedSpec = Data.taggedEnum();
+const { Keep, Latest } = UnresolvedSpec;
 const toUnresolvedSpec = (spec, name) => {
     if (spec.includes('workspace:')) {
-        return isFoldkitPackage(name) ? Result.succeed(Latest) : Result.failVoid;
+        return isFoldkitPackage(name) ? Result.succeed(Latest()) : Result.failVoid;
     }
     else {
-        return Result.succeed(Keep(spec));
+        return Result.succeed(Keep({ version: spec }));
     }
 };
 /**
@@ -58,14 +59,35 @@ const toUnresolvedSpec = (spec, name) => {
 export const buildUnresolvedDeps = (exampleDeps) => Record.filterMap(exampleDeps, toUnresolvedSpec);
 /**
  * Build the devDependency map for a scaffolded project by merging the always-on
- * template tooling with the example's own `devDependencies`. A concrete version
- * from the example wins over the template's latest marker for the same package.
+ * template tooling and any extra scaffold devDependencies with the example's
+ * own `devDependencies`. A concrete version from the example wins over a
+ * latest marker for the same package.
  */
-export const buildUnresolvedDevDeps = (exampleDevDeps) => {
-    const templateSpecs = Record.fromIterableWith(TEMPLATE_DEV_DEPENDENCIES, name => [name, Latest]);
+export const buildUnresolvedDevDeps = (exampleDevDeps, extraDevDependencies) => {
+    const templateSpecs = Record.fromIterableWith([...TEMPLATE_DEV_DEPENDENCIES, ...extraDevDependencies], name => [name, Latest()]);
     const exampleSpecs = Record.filterMap(exampleDevDeps, toUnresolvedSpec);
     return Record.union(templateSpecs, exampleSpecs, (_templateSpec, exampleSpec) => exampleSpec);
 };
+/**
+ * The repo example whose `package.json` supplies a scaffold's dependency
+ * versions. An SPA scaffold reads from its chosen starter example; the SSG and
+ * SSR scaffolds read from the reference apps their overlay files mirror.
+ */
+export const dependencyExample = (scaffold) => Match.value(scaffold).pipe(Match.tagsExhaustive({
+    Spa: ({ example }) => example,
+    Ssg: () => 'ssg',
+    Ssr: () => 'ssr',
+}));
+/**
+ * The devDependencies a scaffold needs beyond the template tooling and the
+ * example's own list. The server-rendered scaffolds ship Node build and host
+ * scripts, so they need `@types/node` to typecheck.
+ */
+export const scaffoldDevDependencies = (scaffold) => Match.value(scaffold).pipe(Match.tagsExhaustive({
+    Spa: () => [],
+    Ssg: () => SERVER_RENDERING_DEV_DEPENDENCIES,
+    Ssr: () => SERVER_RENDERING_DEV_DEPENDENCIES,
+}));
 const resolveLatestVersion = (name) => Effect.gen(function* () {
     const client = yield* HttpClient.HttpClient;
     const encodedName = name.replace('/', '%2F');
@@ -130,10 +152,10 @@ const runCommand = (command, args, cwd) => Effect.callback((resume) => {
         }
     });
 });
-export const installDependencies = (projectPath, packageManager, example) => Effect.gen(function* () {
-    const examplePackageJson = yield* fetchExamplePackageJson(example);
+export const installDependencies = (projectPath, packageManager, scaffold) => Effect.gen(function* () {
+    const examplePackageJson = yield* fetchExamplePackageJson(dependencyExample(scaffold));
     const dependencies = yield* resolveSpecs(buildUnresolvedDeps(examplePackageJson.dependencies));
-    const devDependencies = yield* resolveSpecs(buildUnresolvedDevDeps(examplePackageJson.devDependencies));
+    const devDependencies = yield* resolveSpecs(buildUnresolvedDevDeps(examplePackageJson.devDependencies, scaffoldDevDependencies(scaffold)));
     yield* writeManifest(projectPath, sortDependencies(dependencies), sortDependencies(devDependencies));
     yield* runCommand(packageManager, ['install'], projectPath);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-foldkit-app",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "Create Foldkit applications",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,15 +12,15 @@
     "templates"
   ],
   "dependencies": {
-    "@effect/platform-node": "4.0.0-rc.108",
-    "@effect/platform-node-shared": "4.0.0-rc.108",
+    "@effect/platform-node": "4.0.0-rc.109",
+    "@effect/platform-node-shared": "4.0.0-rc.109",
     "chalk": "^5.6.2",
-    "effect": "4.0.0-rc.108",
+    "effect": "4.0.0-rc.109",
     "rimraf": "^6.1.3",
     "typescript": "^6.0.3"
   },
   "devDependencies": {
-    "@effect/vitest": "4.0.0-rc.108",
+    "@effect/vitest": "4.0.0-rc.109",
     "@types/node": "^25.9.3",
     "vitest": "^4.1.9"
   },

package/templates/rendering/ssg/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build --outDir dist/client && vite build --ssr src/entry.server.ts --outDir dist/server && tsx scripts/prerender.ts",
+    "preview": "vite preview --outDir dist/client",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier -w .",
+    "test": "vitest run",
+    "lint": "oxlint src scripts"
+  }
+}

package/templates/rendering/ssg/scripts/prerender.ts

@@ -0,0 +1,71 @@
+import { Console, Effect, FileSystem } from 'effect'
+import { Server } from 'foldkit/experimental'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+import { NodeRuntime, NodeServices } from '@effect/platform-node'
+
+import type * as ServerEntry from '../src/entry.server'
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url))
+const PROJECT_DIR = resolve(SCRIPT_DIR, '..')
+const CLIENT_DIR = resolve(PROJECT_DIR, 'dist/client')
+const SERVER_ENTRY_PATH = resolve(PROJECT_DIR, 'dist/server/entry.server.js')
+const SITE_ORIGIN = 'https://example.com'
+
+const loadServerEntry: Effect.Effect<typeof ServerEntry> = Effect.promise(
+  () => import(pathToFileURL(SERVER_ENTRY_PATH).href),
+)
+
+const outputFileFor = (path: string): string => {
+  const url = new URL(path, SITE_ORIGIN)
+  if (url.origin !== SITE_ORIGIN || url.pathname !== path) {
+    throw new Error(
+      `Cannot generate the non-normalized same-origin path "${path}".`,
+    )
+  }
+  return path === '/'
+    ? resolve(CLIENT_DIR, 'index.html')
+    : resolve(CLIENT_DIR, path.slice(1), 'index.html')
+}
+
+const program = Effect.gen(function* () {
+  const fs = yield* FileSystem.FileSystem
+  const template = yield* fs.readFileString(resolve(CLIENT_DIR, 'index.html'))
+  const serverEntry = yield* loadServerEntry
+
+  for (const path of serverEntry.prerenderPaths) {
+    const result = yield* Effect.promise(() =>
+      serverEntry.renderPage(new Request(`${SITE_ORIGIN}${path}`)),
+    )
+    if (result._tag === 'Responded') {
+      return yield* Effect.die(
+        new Error(
+          `Cannot write the complete Response returned while generating "${path}" to a static HTML file.`,
+        ),
+      )
+    }
+    if (result.status !== undefined && result.status !== 200) {
+      return yield* Effect.die(
+        new Error(
+          `Cannot preserve status ${result.status} while generating "${path}" as a static HTML file.`,
+        ),
+      )
+    }
+    if (result.headers !== undefined) {
+      return yield* Effect.die(
+        new Error(
+          `Cannot preserve response headers while generating "${path}" as a static HTML file.`,
+        ),
+      )
+    }
+    const html = Server.injectIntoTemplate(template, result.application)
+    const outputFile = outputFileFor(path)
+
+    yield* fs.makeDirectory(dirname(outputFile), { recursive: true })
+    yield* fs.writeFileString(outputFile, html)
+    yield* Console.log(`Generated ${path}`)
+  }
+}).pipe(Effect.provide(NodeServices.layer))
+
+NodeRuntime.runMain(program)

package/templates/rendering/ssg/src/entry.server.ts

@@ -0,0 +1,18 @@
+import { Effect } from 'effect'
+import { Server } from 'foldkit/experimental'
+
+import { init, view } from './main'
+
+export const prerenderPaths: ReadonlyArray<string> = ['/', '/about']
+
+export const renderPage = (request: Request): Promise<Server.EntryResult> =>
+  Effect.runPromise(
+    Effect.gen(function* () {
+      const renderedApplication = yield* Server.renderToString(
+        { routing: {}, init, view },
+        { url: request.url },
+      )
+
+      return Server.Rendered(renderedApplication)
+    }),
+  )

package/templates/rendering/ssg/src/entry.ts

@@ -0,0 +1,28 @@
+import { Runtime } from 'foldkit'
+
+import {
+  ChangedUrl,
+  ClickedLink,
+  Message,
+  Model,
+  init,
+  update,
+  view,
+} from './main'
+
+const application = Runtime.makeApplication({
+  Model,
+  init,
+  update,
+  view,
+  container: document.getElementById('root'),
+  routing: {
+    onUrlRequest: request => ClickedLink({ request }),
+    onUrlChange: url => ChangedUrl({ url }),
+  },
+  devTools: {
+    Message,
+  },
+})
+
+Runtime.hydrate(application)

package/templates/rendering/ssg/src/main.ts

@@ -0,0 +1,176 @@
+import { Effect, Match as M, Schema as S, pipe } from 'effect'
+import { Command, Runtime } from 'foldkit'
+import { type Document, type Html, type HtmlBuilder } from 'foldkit/html'
+import { m } from 'foldkit/message'
+import { UrlRequest, load, pushUrl } from 'foldkit/navigation'
+import { evo } from 'foldkit/struct'
+import { Url, toString as urlToString } from 'foldkit/url'
+
+import { AppRoute, aboutRouter, homeRouter, urlToAppRoute } from './route'
+
+// MODEL
+
+export const Model = S.Struct({
+  route: AppRoute,
+  count: S.Number,
+})
+export type Model = typeof Model.Type
+
+// MESSAGE
+
+export const ClickedIncrement = m('ClickedIncrement')
+export const ClickedLink = m('ClickedLink', { request: UrlRequest })
+export const ChangedUrl = m('ChangedUrl', { url: Url })
+export const CompletedNavigateInternal = m('CompletedNavigateInternal')
+export const CompletedLoadExternal = m('CompletedLoadExternal')
+
+export const Message = S.Union([
+  ClickedIncrement,
+  ClickedLink,
+  ChangedUrl,
+  CompletedNavigateInternal,
+  CompletedLoadExternal,
+])
+export type Message = typeof Message.Type
+
+// INIT
+
+export const init: Runtime.RoutingApplicationInit<Model, Message> = url => [
+  { route: urlToAppRoute(url), count: 0 },
+  [],
+]
+
+// COMMAND
+
+const NavigateInternal = Command.define('NavigateInternal', {
+  args: { url: S.String },
+  messages: [CompletedNavigateInternal],
+  execute: ({ url }) =>
+    pushUrl(url).pipe(Effect.as(CompletedNavigateInternal())),
+})
+
+const LoadExternal = Command.define('LoadExternal', {
+  args: { href: S.String },
+  messages: [CompletedLoadExternal],
+  execute: ({ href }) => load(href).pipe(Effect.as(CompletedLoadExternal())),
+})
+
+// UPDATE
+
+type UpdateReturn = readonly [Model, ReadonlyArray<Command.Command<Message>>]
+const withUpdateReturn = M.withReturnType<UpdateReturn>()
+
+export const update = (model: Model, message: Message): UpdateReturn =>
+  M.value(message).pipe(
+    withUpdateReturn,
+    M.tagsExhaustive({
+      ClickedIncrement: () => [evo(model, { count: count => count + 1 }), []],
+      ClickedLink: ({ request }) =>
+        M.value(request).pipe(
+          withUpdateReturn,
+          M.tagsExhaustive({
+            Internal: ({ url }) => [
+              model,
+              [NavigateInternal({ url: urlToString(url) })],
+            ],
+            External: ({ href }) => [model, [LoadExternal({ href })]],
+          }),
+        ),
+      ChangedUrl: ({ url }) => [
+        evo(model, { route: () => urlToAppRoute(url) }),
+        [],
+      ],
+      CompletedNavigateInternal: () => [model, []],
+      CompletedLoadExternal: () => [model, []],
+    }),
+  )
+
+// VIEW
+
+const APP_NAME = 'Foldkit App'
+
+const appendAppName = (page: string): string => `${page} | ${APP_NAME}`
+
+const routeTitle = (route: AppRoute): string =>
+  pipe(
+    M.value(route),
+    M.tagsExhaustive({
+      Home: () => 'Home',
+      About: () => 'About',
+      NotFound: () => 'Not Found',
+    }),
+    appendAppName,
+  )
+
+const navigationView = (h: HtmlBuilder<Message>): Html =>
+  h.nav(
+    [h.Class('flex gap-4')],
+    [
+      h.a([h.Href(homeRouter()), h.Class('underline')], ['Home']),
+      h.a([h.Href(aboutRouter()), h.Class('underline')], ['About']),
+    ],
+  )
+
+const pageView = (model: Model, h: HtmlBuilder<Message>): Html =>
+  M.value(model.route).pipe(
+    M.tagsExhaustive({
+      Home: () =>
+        h.section(
+          [h.Class('grid gap-4')],
+          [
+            h.h1(
+              [h.Id('page-title'), h.Class('text-4xl font-bold')],
+              ['Statically generated home'],
+            ),
+            h.p(
+              [],
+              [
+                'This route was rendered during the build and hydrated in place.',
+              ],
+            ),
+            h.button(
+              [
+                h.OnClick(ClickedIncrement()),
+                h.Class('w-fit bg-black px-4 py-2 text-white'),
+              ],
+              [`Count: ${model.count}`],
+            ),
+          ],
+        ),
+      About: () =>
+        h.section(
+          [h.Class('grid gap-4')],
+          [
+            h.h1(
+              [h.Id('page-title'), h.Class('text-4xl font-bold')],
+              ['Statically generated about page'],
+            ),
+            h.p(
+              [],
+              [
+                'The same renderPage function produced this route in the same build.',
+              ],
+            ),
+          ],
+        ),
+      NotFound: ({ path }) =>
+        h.section(
+          [h.Class('grid gap-4')],
+          [
+            h.h1(
+              [h.Id('page-title'), h.Class('text-4xl font-bold')],
+              ['Not found'],
+            ),
+            h.p([], [`No statically generated page exists for ${path}.`]),
+          ],
+        ),
+    }),
+  )
+
+export const view = (model: Model, h: HtmlBuilder<Message>): Document => ({
+  title: routeTitle(model.route),
+  body: h.main(
+    [h.Class('mx-auto grid min-h-screen max-w-3xl content-center gap-10 p-8')],
+    [navigationView(h), pageView(model, h)],
+  ),
+})

package/templates/rendering/ssg/src/route.ts

@@ -0,0 +1,20 @@
+import { Schema as S, pipe } from 'effect'
+import { Route } from 'foldkit'
+import { literal, r } from 'foldkit/route'
+
+export const HomeRoute = r('Home')
+export const AboutRoute = r('About')
+export const NotFoundRoute = r('NotFound', { path: S.String })
+
+export const AppRoute = S.Union([HomeRoute, AboutRoute, NotFoundRoute])
+export type AppRoute = typeof AppRoute.Type
+
+export const homeRouter = pipe(Route.root, Route.mapTo(HomeRoute))
+export const aboutRouter = pipe(literal('about'), Route.mapTo(AboutRoute))
+
+const routeParser = Route.oneOf(aboutRouter, homeRouter)
+
+export const urlToAppRoute = Route.parseUrlWithFallback(
+  routeParser,
+  NotFoundRoute,
+)

package/templates/rendering/ssg/src/scene.test.ts

@@ -0,0 +1,27 @@
+import { click, expect, given, role, scene, text } from 'foldkit/scene'
+import { describe, test } from 'vitest'
+
+import { Model, update, view } from './main'
+import { HomeRoute } from './route'
+
+const initialModel = Model.make({ route: HomeRoute(), count: 0 })
+
+describe('view', () => {
+  test('renders the statically generated home page', () => {
+    scene(
+      { update, view },
+      given(initialModel),
+      expect(text('Statically generated home')).toExist(),
+      expect(role('button', { name: 'Count: 0' })).toExist(),
+    )
+  })
+
+  test('clicking the counter increments the count', () => {
+    scene(
+      { update, view },
+      given(initialModel),
+      click(role('button', { name: 'Count: 0' })),
+      expect(role('button', { name: 'Count: 1' })).toExist(),
+    )
+  })
+})

package/templates/rendering/ssg/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "lib": ["ES2022", "DOM"],
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "exactOptionalPropertyTypes": true,
+    "isolatedModules": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*", "scripts/**/*"]
+}

package/templates/rendering/ssg/vite.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from 'vite'
+
+import { foldkit } from '@foldkit/vite-plugin'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [
+    tailwindcss(),
+    foldkit({
+      devToolsMcpPort: 9988,
+      ssr: { serverEntry: '/src/entry.server.ts' },
+    }),
+  ],
+  optimizeDeps: {
+    entries: ['src/entry.ts'],
+  },
+})

package/templates/rendering/ssr/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build --outDir dist/client && vite build --ssr server/main.ts --outDir dist/server",
+    "start": "node dist/server/main.js",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier -w .",
+    "test": "vitest run",
+    "lint": "oxlint src server"
+  }
+}

package/templates/rendering/ssr/server/main.ts

@@ -0,0 +1,129 @@
+import { Config, Effect, FileSystem, Layer, Match as M, Option } from 'effect'
+import {
+  Headers as HttpHeaders,
+  HttpServer,
+  HttpServerError,
+  HttpServerRequest,
+  HttpServerResponse,
+  HttpStaticServer,
+} from 'effect/unstable/http'
+import { Server } from 'foldkit/experimental'
+import { createServer } from 'node:http'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import {
+  NodeHttpPlatform,
+  NodeHttpServer,
+  NodeRuntime,
+  NodeServices,
+} from '@effect/platform-node'
+
+import { renderPage } from '../src/entry.server'
+
+const PROJECT_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '../..')
+const CLIENT_DIR = resolve(PROJECT_DIR, 'dist/client')
+const DEFAULT_PORT = 3000
+
+const renderRequest = (
+  request: HttpServerRequest.HttpServerRequest,
+  template: string,
+) =>
+  Effect.gen(function* () {
+    const webRequest = yield* HttpServerRequest.toWeb(request)
+    const result = yield* Effect.promise(() => renderPage(webRequest))
+    return HttpServerResponse.fromWeb(Server.toResponse(template, result))
+  })
+
+// NOTE: Vary: Accept keeps a shared cache from serving one client's
+// representation to another when a static miss is answered by content
+// negotiation. It is merged with any Vary the render already set, parsing
+// Vary as field-name tokens so Accept-Language or Accept-Encoding is never
+// mistaken for the Accept field.
+const withVaryAccept = (
+  response: HttpServerResponse.HttpServerResponse,
+): HttpServerResponse.HttpServerResponse =>
+  HttpServerResponse.setHeader(
+    response,
+    'vary',
+    Server.varyWithAccept(
+      Option.getOrUndefined(HttpHeaders.get('vary')(response.headers)),
+    ),
+  )
+
+const isRouteNotFound = (error: HttpServerError.HttpServerError): boolean =>
+  error.reason._tag === 'RouteNotFound'
+
+type RequestKind = 'Render' | 'StaticOrRender' | 'MethodNotAllowed'
+
+// NOTE: `/` and `/index.html` (and the encoded paths that resolve to them)
+// are application requests even though a file exists for them: the file on
+// disk is the unfilled template, and serving it raw would hand the browser an
+// unstamped shell that Runtime.hydrate refuses. Only GET and HEAD render; every
+// other method (OPTIONS, POST, ...) is refused with 405 rather than rendered.
+const requestKind = ({
+  method,
+  url,
+}: HttpServerRequest.HttpServerRequest): RequestKind =>
+  M.value(method).pipe(
+    M.withReturnType<RequestKind>(),
+    M.whenOr('GET', 'HEAD', () =>
+      Server.resolvesToIndexHtml(url) ? 'Render' : 'StaticOrRender',
+    ),
+    M.orElse(() => 'MethodNotAllowed'),
+  )
+
+const makeHandler = Effect.gen(function* () {
+  const fs = yield* FileSystem.FileSystem
+  const template = yield* fs.readFileString(resolve(CLIENT_DIR, 'index.html'))
+  const staticFiles = yield* HttpStaticServer.make({
+    root: CLIENT_DIR,
+    index: undefined,
+  })
+
+  // NOTE: a static miss is Accept-negotiated because a deep link into a client
+  // route has no file on disk but an HTML client should still get the app
+  // shell. It renders, anything else 404s, and both carry Vary: Accept.
+  const serveStaticOrRender = (request: HttpServerRequest.HttpServerRequest) =>
+    staticFiles.pipe(
+      Effect.catchIf(isRouteNotFound, () =>
+        Server.acceptsHtml(request.headers['accept'])
+          ? renderRequest(request, template).pipe(Effect.map(withVaryAccept))
+          : Effect.succeed(
+              withVaryAccept(HttpServerResponse.empty({ status: 404 })),
+            ),
+      ),
+    )
+
+  return HttpServerRequest.HttpServerRequest.use(request =>
+    M.value(requestKind(request)).pipe(
+      M.when('Render', () => renderRequest(request, template)),
+      M.when('StaticOrRender', () => serveStaticOrRender(request)),
+      M.when('MethodNotAllowed', () =>
+        Effect.succeed(
+          HttpServerResponse.setHeader(
+            HttpServerResponse.empty({ status: 405 }),
+            'allow',
+            'GET, HEAD',
+          ),
+        ),
+      ),
+      M.exhaustive,
+    ),
+  )
+})
+
+const Main = Layer.unwrap(
+  Effect.map(makeHandler, handler => HttpServer.serve(handler)),
+).pipe(
+  HttpServer.withLogAddress,
+  Layer.provide(
+    NodeHttpServer.layerConfig(createServer, {
+      port: Config.withDefault(Config.port('PORT'), DEFAULT_PORT),
+    }),
+  ),
+  Layer.provide(NodeHttpPlatform.layer),
+  Layer.provide(NodeServices.layer),
+)
+
+NodeRuntime.runMain(Layer.launch(Main))

package/templates/rendering/ssr/src/cookie.ts

@@ -0,0 +1,13 @@
+import { Number as Number_, Option, Record, pipe } from 'effect'
+import { Cookies } from 'effect/unstable/http'
+
+export const COUNT_COOKIE = 'count'
+
+export const readCountCookie = (cookieHeader: string): number =>
+  pipe(
+    Cookies.parseHeader(cookieHeader),
+    Record.get(COUNT_COOKIE),
+    Option.flatMap(Number_.parse),
+    Option.filter(Number.isSafeInteger),
+    Option.getOrElse(() => 0),
+  )

package/templates/rendering/ssr/src/entry.server.ts

@@ -0,0 +1,33 @@
+import { Effect } from 'effect'
+import { Server } from 'foldkit/experimental'
+
+import { readCountCookie } from './cookie'
+import { Flags, init, view } from './main'
+
+const flagsForRequest = (cookieHeader: string): Flags => ({
+  initialCount: readCountCookie(cookieHeader),
+  renderedAt: new Date().toISOString(),
+  renderedOn: 'Server',
+})
+
+// NOTE: the Flags built from this request are serialized into the rendered
+// HTML and travel to the browser with it. The hydrating client reads them
+// back and calls init with the exact values this render used; the client
+// computes no Flags of its own.
+export const renderPage = (request: Request): Promise<Server.EntryResult> =>
+  Effect.runPromise(
+    Effect.gen(function* () {
+      const renderedApplication = yield* Server.renderToString(
+        { Flags, init, view },
+        { flags: flagsForRequest(request.headers.get('cookie') ?? '') },
+      )
+
+      return Server.Rendered(renderedApplication, {
+        headers: {
+          'cache-control': 'private, no-store',
+          vary: 'cookie',
+          'x-content-type-options': 'nosniff',
+        },
+      })
+    }),
+  )

package/templates/rendering/ssr/src/entry.ts

@@ -0,0 +1,17 @@
+import { Runtime } from 'foldkit'
+
+import { Flags, Message, Model, init, update, view } from './main'
+
+const application = Runtime.makeApplication({
+  Model,
+  Flags,
+  init,
+  update,
+  view,
+  container: document.getElementById('root'),
+  devTools: {
+    Message,
+  },
+})
+
+Runtime.hydrate(application)

package/templates/rendering/ssr/src/main.ts

@@ -0,0 +1,155 @@
+import { Effect, Match as M, Schema as S } from 'effect'
+import { Command, Runtime } from 'foldkit'
+import { type Document, type HtmlBuilder } from 'foldkit/html'
+import { m } from 'foldkit/message'
+import { evo } from 'foldkit/struct'
+
+import { Button } from '@foldkit/ui'
+
+import { COUNT_COOKIE } from './cookie'
+
+// MODEL
+
+export const Model = S.Struct({
+  count: S.Number,
+  renderedAt: S.String,
+  renderedOn: S.Literals(['Server', 'Client']),
+})
+export type Model = typeof Model.Type
+
+// FLAGS
+
+export const Flags = S.Struct({
+  initialCount: S.Number,
+  renderedAt: S.String,
+  renderedOn: S.Literals(['Server', 'Client']),
+})
+export type Flags = typeof Flags.Type
+
+// MESSAGE
+
+export const ClickedDecrement = m('ClickedDecrement')
+export const ClickedIncrement = m('ClickedIncrement')
+export const CompletedPersistCount = m('CompletedPersistCount')
+
+export const Message = S.Union([
+  ClickedDecrement,
+  ClickedIncrement,
+  CompletedPersistCount,
+])
+export type Message = typeof Message.Type
+
+// UPDATE
+
+export const update = (
+  model: Model,
+  message: Message,
+): readonly [Model, ReadonlyArray<Command.Command<Message>>] =>
+  M.value(message).pipe(
+    M.withReturnType<
+      readonly [Model, ReadonlyArray<Command.Command<Message>>]
+    >(),
+    M.tagsExhaustive({
+      ClickedDecrement: () => {
+        const nextCount = model.count - 1
+        return [
+          evo(model, { count: () => nextCount }),
+          [PersistCount({ count: nextCount })],
+        ]
+      },
+      ClickedIncrement: () => {
+        const nextCount = model.count + 1
+        return [
+          evo(model, { count: () => nextCount }),
+          [PersistCount({ count: nextCount })],
+        ]
+      },
+      CompletedPersistCount: () => [model, []],
+    }),
+  )
+
+// COMMAND
+
+const COUNT_COOKIE_MAX_AGE_SECONDS = 31536000
+
+export const PersistCount = Command.define('PersistCount', {
+  args: { count: S.Number },
+  messages: [CompletedPersistCount],
+  execute: ({ count }) =>
+    Effect.try(() => {
+      document.cookie = `${COUNT_COOKIE}=${count}; path=/; max-age=${COUNT_COOKIE_MAX_AGE_SECONDS}`
+    }).pipe(
+      Effect.map(() => CompletedPersistCount()),
+      Effect.catch(() => Effect.succeed(CompletedPersistCount())),
+    ),
+})
+
+// INIT
+
+export const init: Runtime.ApplicationInit<Model, Message, Flags> = flags => [
+  {
+    count: flags.initialCount,
+    renderedAt: flags.renderedAt,
+    renderedOn: flags.renderedOn,
+  },
+  [],
+]
+
+// VIEW
+
+export const view = (model: Model, h: HtmlBuilder<Message>): Document => ({
+  title: `Count ${model.count}`,
+  body: h.div(
+    [
+      h.Class(
+        'min-h-screen bg-white flex flex-col items-center justify-center gap-6 p-6',
+      ),
+    ],
+    [
+      h.h1(
+        [h.Class('text-2xl font-semibold text-gray-800')],
+        ['Server-rendered counter'],
+      ),
+      h.p(
+        [h.Id('count'), h.Class('text-6xl font-bold text-gray-800')],
+        [model.count.toString()],
+      ),
+      h.div(
+        [h.Class('flex flex-wrap justify-center gap-4')],
+        [
+          Button.view(
+            {
+              onClick: ClickedDecrement(),
+              toView: attributes =>
+                h.button([...attributes.button, h.Class(buttonStyle)], ['-']),
+            },
+            h,
+          ),
+          Button.view(
+            {
+              onClick: ClickedIncrement(),
+              toView: attributes =>
+                h.button([...attributes.button, h.Class(buttonStyle)], ['+']),
+            },
+            h,
+          ),
+        ],
+      ),
+      h.p(
+        [h.Id('provenance'), h.Class('text-sm text-gray-500')],
+        [`Rendered on the ${model.renderedOn} at ${model.renderedAt}`],
+      ),
+      h.p(
+        [h.Class('text-sm text-gray-500 max-w-md text-center')],
+        [
+          'The count persists in a cookie. Reload the page and the server ' +
+            'renders your latest count into the HTML before any JavaScript runs.',
+        ],
+      ),
+    ],
+  ),
+})
+
+// STYLE
+
+const buttonStyle = 'bg-black text-white hover:bg-gray-700 px-4 py-2 transition'

package/templates/rendering/ssr/src/scene.test.ts

@@ -0,0 +1,43 @@
+import { Command, click, expect, given, role, scene, text } from 'foldkit/scene'
+import { describe, test } from 'vitest'
+
+import {
+  CompletedPersistCount,
+  Model,
+  PersistCount,
+  update,
+  view,
+} from './main'
+
+const initialModel = Model.make({
+  count: 3,
+  renderedAt: '2026-07-26T00:00:00.000Z',
+  renderedOn: 'Server',
+})
+
+describe('view', () => {
+  test('renders the count and provenance line', () => {
+    scene(
+      { update, view },
+      given(initialModel),
+      expect(text('3')).toExist(),
+      expect(
+        text('Rendered on the Server at 2026-07-26T00:00:00.000Z'),
+      ).toExist(),
+      expect(role('button', { name: '+' })).toExist(),
+      expect(role('button', { name: '-' })).toExist(),
+    )
+  })
+
+  test('clicking + increments and persists the count', () => {
+    scene(
+      { update, view },
+      given(initialModel),
+      click(role('button', { name: '+' })),
+      expect(text('4')).toExist(),
+      Command.expectHas(PersistCount({ count: 4 })),
+      Command.resolve(PersistCount({ count: 4 }), CompletedPersistCount()),
+      Command.expectNone(),
+    )
+  })
+})

package/templates/rendering/ssr/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "lib": ["ES2022", "DOM"],
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "exactOptionalPropertyTypes": true,
+    "isolatedModules": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*", "server/**/*"]
+}

package/templates/rendering/ssr/vite.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from 'vite'
+
+import { foldkit } from '@foldkit/vite-plugin'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [
+    tailwindcss(),
+    foldkit({
+      devToolsMcpPort: 9988,
+      ssr: { serverEntry: '/src/entry.server.ts' },
+    }),
+  ],
+  optimizeDeps: {
+    entries: ['src/entry.ts'],
+  },
+})