Skip to content

feat(cli): add Foldkit as a web frontend option - #1176

Open
artile wants to merge 1 commit into
AmanVarshney01:mainfrom
artile:feat/foldkit-frontend
Open

artile wants to merge 1 commit into
AmanVarshney01:mainfrom
artile:feat/foldkit-frontend

Conversation

@artile

@artile artile commented Aug 15, 2026 •

Copy link
Copy Markdown

Closes #1175.

Adds Foldkit as a ninth web frontend (--frontend foldkit). Foldkit is a TypeScript frontend framework built on Effect and architected like Elm: Model, Message, update, view, and side effects confined to Commands. It ships its own router, virtual DOM, and Vite plugin, and uses Effect Schema for every type.

The one design difference worth reviewing first

Every current web frontend gets a TanStack Query binding through api-deps.ts. Foldkit gets none, on purpose: server state lives in the Model as AsyncData and is fetched by Commands. So the Foldkit branch adds the vanilla @orpc/client only, and better-auth uses its vanilla client. Both calls are wrapped in an Effect inside a Command. A query cache next to the Model would fight the architecture rather than help it.

What the templates generate

packages/template-generator/templates/frontend/foldkit is a Vite SPA on port 3001 with @foldkit/vite-plugin and Tailwind v4. The cross-cutting templates follow the existing layout:

Path Contents
frontend/foldkit app shell, routes, Messages, header, home, 404
api/orpc/web/foldkit oRPC client and the health-check Command
auth/better-auth/web/foldkit auth client, session state, sign-in/sign-up page, dashboard
examples/todo/web/foldkit the todo example as a Submodel
deploy/docker/web/foldkit multi-stage build serving dist through nginx

What it rejects, and where

Everything without a Foldkit template fails during configuration rather than after generation, which is the rule openspec/config.yaml asks for:

  • tRPC. Foldkit joins TRPC_UNSUPPORTED_FRONTENDS, which also replaces the four-way includesNuxt ? ... : includesSvelte ? ... chains in validateApiFrontendCompatibility and allowedApisForFrontends.
  • Convex, Clerk, Polar, the AI example, --backend self, Tauri and Electrobun.
  • --web-deploy cloudflare and --web-deploy prisma. There is no Alchemy recipe, so DeployedWebFramework excludes Foldkit and a new validateCloudflareWebDeploy reports it. The prompt hides the option instead of offering a dead end.

Docker and Vercel web deployment both work. Vercel gets the SPA index.html rewrite; Docker maps 3001:80 and health-checks nginx, matching what TanStack Router already does.

Verification

  • bun run check, packages/template-generator typecheck, and apps/cli typecheck are clean. The one remaining apps/cli error, in prompts/database-setup.ts, and the apps/web Next.js prerender failure both reproduce on main untouched.
  • cd apps/cli && bun test: 685 pass, 30 skip, 0 fail.
  • cd apps/web && bun test: 46 pass, 0 fail. Includes a new Foldkit suite in stack-builder-compatibility.test.ts.
  • BTS_MATRIX_MODE=smoke: 307 pass, 0 fail.
  • Full matrix: I sampled 14,479 Foldkit configurations and compared the oracle against production validation. Zero mismatches. Shard 1/6000 has 11 failures, 7 of which reproduce on main; the rest share the same pre-existing next + planetscale + cloudflare signature and none involve Foldkit.
  • New Foldkit Frontend suite in apps/cli/test/frontend.test.ts covers the generated layout, the absence of a query cache, the Docker output, and each rejected combination.

I also ran a generated project end to end (Hono + oRPC + better-auth + SQLite/Drizzle + todo). tsc --noEmit and vite build pass, and in a headless browser:

  • the home page renders and the API status card reaches Connected,
  • sign-up redirects to /dashboard, which shows the session and the privateData response,
  • creating, toggling, and deleting a todo all round-trip through oRPC,
  • /dashboard while signed out redirects to /login, /login while signed in redirects to /dashboard, sign-out returns to /,
  • no console or page errors.

Typecheck also passes for the minimal config (--api none --auth none), for oRPC with the todo example and no auth, for Prisma/Postgres with better-auth, and for Mongoose, whose string todo ids the template handles.

Notes

  • App source follows this repo's template style, double quotes and semicolons, not Foldkit's own scaffolder style. Say the word if you would rather the generated app match Foldkit's formatting.
  • Versions are pinned to foldkit@^0.145.0, @foldkit/ui@^0.145.0, @foldkit/vite-plugin@^0.13.1, and effect@4.0.0-rc.108, which is the version Foldkit 0.145 requires.
  • I maintain Foldkit, so I can keep this branch current with the framework.

Summary by CodeRabbit

  • New Features

    • Added Foldkit as a supported web frontend option.
    • Added project generation for Foldkit apps, including routing, authentication, oRPC, todo examples, and Docker deployment.
    • Added generated Vercel static SPA support and required Node.js version guidance.
  • Bug Fixes

    • Improved compatibility checks for unsupported authentication, backend, payment, AI, and deployment combinations.
    • Cloudflare deployment is now offered only for compatible frontends.
  • Documentation

    • Updated frontend options and compatibility guidance to include Foldkit and its supported configurations.

Foldkit is a TypeScript frontend framework built on Effect and architected
like Elm: Model, Message, update, view, and side effects confined to Commands.
`--frontend foldkit` scaffolds a Vite SPA with the Foldkit Vite plugin,
Tailwind v4, and Foldkit's own router.

Unlike every other web frontend, Foldkit pulls in no TanStack Query binding.
Server state lives in the Model as AsyncData and is fetched by Commands, so
the oRPC wiring uses the vanilla `@orpc/client` and better-auth's vanilla
client, both wrapped in Effect.

Templates cover the app shell, the oRPC client and health check, better-auth
sign-in/sign-up with route guards and a dashboard, the todo example as a
Submodel, and a Docker image that serves the built SPA through nginx.

Compatibility rules reject the combinations that have no Foldkit template
yet, at configuration time rather than after generation: tRPC, Convex, Clerk,
Polar, the AI example, backend self, desktop addons, and Cloudflare or Prisma
web deployment. Docker and Vercel web deployment both work.

Closes AmanVarshney01#1175
@vercel

vercel Bot commented Aug 15, 2026

Copy link
Copy Markdown

@MYREMOTELY is attempting to deploy a commit to the Better T Stack Team on Vercel.

A member of the Team first needs to authorize it.

@coderabbitai

coderabbitai Bot commented Aug 15, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

Walkthrough

Changes

Foldkit is added as a supported web frontend. The change includes CLI selection, compatibility validation, generated application templates, Docker deployment, documentation, and integration and matrix tests.

Foldkit frontend integration

Layer / File(s) Summary
Frontend contracts and selection
packages/types/*, apps/cli/src/prompts/*, apps/cli/src/utils/compatibility.ts, apps/cli/src/utils/requirements.ts
Foldkit is added to frontend types, constants, prompts, framework detection, payment checks, and Node.js requirements.
Compatibility and deployment validation
apps/cli/src/utils/compatibility-rules.ts, apps/cli/src/utils/config-validation.ts, apps/web/src/app/(home)/new/_components/utils.ts, apps/web/src/lib/constant.ts, packages/template-generator/src/generators/alchemy/plan.ts
Foldkit is rejected for unsupported Convex, tRPC, Clerk, Polar, AI, self-backend, and Cloudflare configurations. Docker and Vercel remain supported.
Template-generator wiring
packages/template-generator/src/processors/*, packages/template-generator/src/template-handlers/*, packages/template-generator/src/post-process/*
The generator recognizes Foldkit as a web frontend and processes its API, authentication, example, deployment, environment, README, and frontend templates.
Generated Foldkit application templates
packages/template-generator/templates/frontend/foldkit/*, packages/template-generator/templates/api/orpc/web/foldkit/*, packages/template-generator/templates/auth/better-auth/web/foldkit/*, packages/template-generator/templates/examples/todo/web/foldkit/*, packages/template-generator/templates/deploy/docker/*
New templates provide routing, messages, views, oRPC, Better Auth, todos, Vite configuration, and Docker/Nginx deployment output.
Matrix, integration, and documentation coverage
apps/cli/test/*, apps/web/test/*, apps/web/content/docs/cli/*
Tests cover generated files, dependencies, supported deployments, incompatible configurations, matrix cases, and documented Foldkit compatibility rules.

Possibly related PRs

Merge Risk: 🔵 Low · up to dcd63

The PR is mergeable with explicit owner awareness: the generated Docker deployment should revalidate index.html to avoid stale shells referencing removed hashed assets after a deploy, and the application entrypoint should fail clearly if its root element is missing.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
Linked Issues check ❓ Inconclusive The changes cover the linked issue objectives, but templates.generated.ts is excluded, so generated template registration cannot be verified. Review packages/template-generator/src/templates.generated.ts to verify Foldkit template registration.
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly identifies adding Foldkit as a web frontend, which is the pull request's primary change.
Out of Scope Changes check ✅ Passed The reviewed changes directly support Foldkit frontend integration, templates, compatibility rules, documentation, and tests.
✨ Finishing Touches 💡 1
🛠️ Fix failing CI checks 💡
  • Create stacked PR
  • Commit on current branch

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install failed. For unrecoverable errors, disable the tool in CodeRabbit configuration.


Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (4)
apps/web/src/app/(home)/new/_components/utils.ts (1)

62-84: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Use SCREAMING_SNAKE_CASE for module-level constants.

Rename the compatibility arrays to names such as CLERK_INCOMPATIBLE_WEB_FRONTENDS and CLOUDFLARE_INCOMPATIBLE_WEB_FRONTENDS. Update their references in this module.

Based on learnings, TypeScript files under apps/web/src use SCREAMING_SNAKE_CASE for module-level constants.

Source: Learnings

packages/template-generator/templates/frontend/foldkit/src/view/notFound.ts.hbs (1)

1-15: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Rename the template to kebab-case.

The filename notFound.ts.hbs does not use kebab-case. Rename it to not-found.ts.hbs. Update generated-source imports that reference this template.

As per coding guidelines, "**/*: Prefer kebab-case file names."

Source: Coding guidelines

packages/template-generator/templates/deploy/docker/web/foldkit/nginx.conf (1)

14-17: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

Set no-cache on the SPA shell.

/index.html is returned for every route and carries no Cache-Control. A browser may then reuse a cached shell that references hashed assets removed by a later deploy. The assets remain immutable, so only the shell needs revalidation.

♻️ Proposed refactor
     # SPA fallback
     location / {
         try_files $uri $uri/ /index.html;
     }
+
+    location = /index.html {
+        add_header Cache-Control "no-cache";
+    }
packages/template-generator/templates/frontend/foldkit/src/main.ts.hbs (1)

2-2: 🎯 Functional Correctness | 🔵 Trivial | 💤 Low value

Remove the unused AsyncData import.

For api = "orpc" with auth != "better-auth", main.ts imports but does not use AsyncData. The Foldkit tsconfig does not enable noUnusedLocals, so this does not fail type checking. Treat this as cleanup.


ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: f7e13121-f6e3-4020-a8cf-c33710882295

📥 Commits

Reviewing files that changed from the base of the PR and between 0668cf6 and dcd639d.

⛔ Files ignored due to path filters (1)
  • packages/template-generator/src/templates.generated.ts is excluded by !**/*.generated.*
📒 Files selected for processing (55)
  • apps/cli/src/prompts/backend.ts
  • apps/cli/src/prompts/frontend.ts
  • apps/cli/src/prompts/payments.ts
  • apps/cli/src/prompts/web-deploy.ts
  • apps/cli/src/utils/compatibility-rules.ts
  • apps/cli/src/utils/compatibility.ts
  • apps/cli/src/utils/config-validation.ts
  • apps/cli/src/utils/requirements.ts
  • apps/cli/test/frontend.test.ts
  • apps/cli/test/matrix/cases.ts
  • apps/cli/test/matrix/oracle.ts
  • apps/web/content/docs/cli/compatibility.mdx
  • apps/web/content/docs/cli/options.mdx
  • apps/web/src/app/(home)/new/_components/utils.ts
  • apps/web/src/lib/constant.ts
  • apps/web/test/stack-builder-compatibility.test.ts
  • packages/template-generator/src/generators/alchemy/plan.ts
  • packages/template-generator/src/post-process/vercel-config.ts
  • packages/template-generator/src/processors/api-deps.ts
  • packages/template-generator/src/processors/auth-deps.ts
  • packages/template-generator/src/processors/env-vars.ts
  • packages/template-generator/src/processors/readme-generator.ts
  • packages/template-generator/src/template-handlers/api.ts
  • packages/template-generator/src/template-handlers/auth.ts
  • packages/template-generator/src/template-handlers/deploy.ts
  • packages/template-generator/src/template-handlers/examples.ts
  • packages/template-generator/src/template-handlers/frontend.ts
  • packages/template-generator/src/template-handlers/packages.ts
  • packages/template-generator/src/utils/generated-ignore-patterns.ts
  • packages/template-generator/templates/api/orpc/web/foldkit/src/api/health.ts.hbs
  • packages/template-generator/templates/api/orpc/web/foldkit/src/api/orpc.ts.hbs
  • packages/template-generator/templates/auth/better-auth/web/foldkit/src/auth/client.ts.hbs
  • packages/template-generator/templates/auth/better-auth/web/foldkit/src/auth/session.ts.hbs
  • packages/template-generator/templates/auth/better-auth/web/foldkit/src/page/login.ts.hbs
  • packages/template-generator/templates/auth/better-auth/web/foldkit/src/view/dashboard.ts.hbs
  • packages/template-generator/templates/deploy/docker/compose/docker-compose.yml.hbs
  • packages/template-generator/templates/deploy/docker/web/foldkit/Dockerfile.hbs
  • packages/template-generator/templates/deploy/docker/web/foldkit/nginx.conf
  • packages/template-generator/templates/examples/todo/web/foldkit/src/page/todos.ts.hbs
  • packages/template-generator/templates/frontend/foldkit/_gitignore
  • packages/template-generator/templates/frontend/foldkit/index.html.hbs
  • packages/template-generator/templates/frontend/foldkit/package.json.hbs
  • packages/template-generator/templates/frontend/foldkit/src/entry.ts.hbs
  • packages/template-generator/templates/frontend/foldkit/src/main.ts.hbs
  • packages/template-generator/templates/frontend/foldkit/src/message.ts.hbs
  • packages/template-generator/templates/frontend/foldkit/src/route.ts.hbs
  • packages/template-generator/templates/frontend/foldkit/src/styles.css
  • packages/template-generator/templates/frontend/foldkit/src/view/header.ts.hbs
  • packages/template-generator/templates/frontend/foldkit/src/view/home.ts.hbs
  • packages/template-generator/templates/frontend/foldkit/src/view/notFound.ts.hbs
  • packages/template-generator/templates/frontend/foldkit/tsconfig.json.hbs
  • packages/template-generator/templates/frontend/foldkit/vite.config.ts.hbs
  • packages/types/src/constants.ts
  • packages/types/src/schemas.ts
  • packages/types/src/types.ts

init,
update,
view,
container: document.getElementById("root"),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🌐 Web query:

foldkit Runtime.makeApplication container option type

💡 Result:

In Foldkit, the container option used in Runtime.makeApplication expects an HTMLElement (such as the result of document.getElementById) as its value [1][2]. This container serves as the DOM node where the Foldkit application will be mounted [1]. While the exact TypeScript type for the container option is typically inferred from the DOM API, it corresponds to the standard HTMLElement interface provided by the browser environment. In practical implementation, this is often passed as a reference to a div or similar element within your HTML entry point, as shown in official examples: const application = Runtime.makeApplication({ Model, init, update, view, container: document.getElementById('root'), // container: HTMLElement | null }) [1][2][3] If the provided container element is null, the runtime will typically fail to mount. Use Runtime.makeApplication when your application owns the entire page, or consider Runtime.makeElement if you need to mount the app into a specific node without it taking ownership of the document head or URL routing [1][4].

Citations:


🏁 Script executed:

#!/bin/bash
set -e

printf '%s\n' '--- template ---'
cat -n packages/template-generator/templates/frontend/foldkit/src/entry.ts.hbs

printf '%s\n' '--- Foldkit references ---'
rg -n --hidden -S 'makeApplication|container:' packages package.json pnpm-lock.yaml yarn.lock package-lock.json 2>/dev/null | head -200

printf '%s\n' '--- relevant files ---'
git ls-files | rg 'foldkit|template-processor|package.json$' | head -200

Repository: AmanVarshney01/create-better-t-stack

Length of output: 7381


🏁 Script executed:

#!/bin/bash
set -e

printf '%s\n' '--- Foldkit template inputs ---'
cat -n packages/template-generator/templates/frontend/foldkit/index.html.hbs
cat -n packages/template-generator/templates/frontend/foldkit/package.json.hbs
cat -n packages/template-generator/templates/frontend/foldkit/tsconfig.json.hbs

printf '%s\n' '--- lockfile/package references ---'
rg -n -i 'foldkit|makeApplication' --glob '!*templates.generated.ts' --glob '!*.map' . | head -200

printf '%s\n' '--- public package/source metadata ---'
curl -L --fail --silent --show-error https://registry.npmjs.org/foldkit/latest | jq '{name,version,types,main,repository,dist}'

Repository: AmanVarshney01/create-better-t-stack

Length of output: 22939


🏁 Script executed:

#!/bin/bash
set -e

repo='foldkit/foldkit'
tag='v0.145.0'

printf '%s\n' '--- release tree ---'
curl -L --fail --silent --show-error \
  "https://api.github.com/repos/$repo/git/trees/$tag?recursive=1" |
  jq -r '.tree[] | select(.path | test("runtime|Runtime|application|package.json"; "i")) | .path' |
  head -100

printf '%s\n' '--- source matches ---'
tree_json="$(curl -L --fail --silent --show-error "https://api.github.com/repos/$repo/git/trees/$tag?recursive=1")"
printf '%s\n' "$tree_json" |
  jq -r '.tree[] | select(.type == "blob" and (.path | test("\\.(ts|tsx|d\\.ts)$"))) | .path' |
  while IFS= read -r path; do
    content="$(curl -L --fail --silent --show-error "https://raw.githubusercontent.com/$repo/$tag/$path" || true)"
    if printf '%s' "$content" | rg -q 'makeApplication|container'; then
      printf '%s\n' "--- $path ---"
      printf '%s' "$content" | rg -n -C 5 'makeApplication|container'
    fi
  done

Repository: AmanVarshney01/create-better-t-stack

Length of output: 318


🌐 Web query:

foldkit v0.145.0 Runtime.makeApplication container HTMLElement TypeScript

💡 Result:

In Foldkit, Runtime.makeApplication is a function used to initialize a Foldkit application that owns the entire page [1]. It takes a configuration object, including the Model, init, update, and view functions, as well as a container property [1][2]. The container property is of type HTMLElement, representing the DOM element in your page where the Foldkit application will be mounted [1]. You typically retrieve this element using standard DOM methods, such as document.getElementById('root') [1][2]. Example usage in TypeScript: import { Runtime } from 'foldkit'; import { Model, init, update, view } from './main'; const application = Runtime.makeApplication({ Model, init, update, view, container: document.getElementById('root') as HTMLElement, }); Runtime.run(application); When using makeApplication, the application assumes ownership of page-level concerns like the document title, meta tags, and URL routing (if a routing config is provided) [1][3][4]. For embedding a Foldkit app as a component within a larger, host-controlled page, the library provides makeElement, which scope-limits the runtime to a container without interacting with document-level metadata [1][3][4].

Citations:


🌐 Web query:

site:github.com/foldkit/foldkit "makeApplication" "container"

💡 Result:

In the Foldkit framework, makeApplication is a function used to initialize a top-level application that owns the entire page [1]. When configuring makeApplication, the container property is used to specify the DOM element where the application should be mounted [2]. Key details regarding the container and makeApplication include: Usage: It is typically passed as a property within the configuration object provided to Runtime.makeApplication, pointing to a target element in the DOM (e.g., document.getElementById('root')) [2]. Scope: makeApplication is designed for applications that own the page and manage document-level metadata, such as document.title and URL routing [1]. Comparison: This contrasts with makeElement, which is used for embedded widgets that do not control the entire page [1]. Unlike makeApplication, makeElement mounts scoped to a specific DOM node and does not interact with document-level properties [1].

Citations:


Guard the #root lookup before calling Runtime.makeApplication.

container requires HTMLElement, but document.getElementById("root") returns HTMLElement | null. Throw a clear error when the element is missing.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature Request: add Foldkit as a web frontend option

2 participants