Repository navigation
Conversation
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
|
@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. |
WalkthroughChangesFoldkit 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
Possibly related PRs
Merge Risk: 🔵 Low · up to 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)
✅ Passed checks (3 passed)
✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
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
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. Comment |
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (4)
apps/web/src/app/(home)/new/_components/utils.ts (1)
62-84: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueUse SCREAMING_SNAKE_CASE for module-level constants.
Rename the compatibility arrays to names such as
CLERK_INCOMPATIBLE_WEB_FRONTENDSandCLOUDFLARE_INCOMPATIBLE_WEB_FRONTENDS. Update their references in this module.Based on learnings, TypeScript files under
apps/web/srcuse 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 winRename the template to kebab-case.
The filename
notFound.ts.hbsdoes not use kebab-case. Rename it tonot-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 winSet
no-cacheon the SPA shell.
/index.htmlis returned for every route and carries noCache-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 valueRemove the unused
AsyncDataimport.For
api = "orpc"withauth != "better-auth",main.tsimports but does not useAsyncData. The Foldkittsconfigdoes not enablenoUnusedLocals, 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
⛔ Files ignored due to path filters (1)
packages/template-generator/src/templates.generated.tsis excluded by!**/*.generated.*
📒 Files selected for processing (55)
apps/cli/src/prompts/backend.tsapps/cli/src/prompts/frontend.tsapps/cli/src/prompts/payments.tsapps/cli/src/prompts/web-deploy.tsapps/cli/src/utils/compatibility-rules.tsapps/cli/src/utils/compatibility.tsapps/cli/src/utils/config-validation.tsapps/cli/src/utils/requirements.tsapps/cli/test/frontend.test.tsapps/cli/test/matrix/cases.tsapps/cli/test/matrix/oracle.tsapps/web/content/docs/cli/compatibility.mdxapps/web/content/docs/cli/options.mdxapps/web/src/app/(home)/new/_components/utils.tsapps/web/src/lib/constant.tsapps/web/test/stack-builder-compatibility.test.tspackages/template-generator/src/generators/alchemy/plan.tspackages/template-generator/src/post-process/vercel-config.tspackages/template-generator/src/processors/api-deps.tspackages/template-generator/src/processors/auth-deps.tspackages/template-generator/src/processors/env-vars.tspackages/template-generator/src/processors/readme-generator.tspackages/template-generator/src/template-handlers/api.tspackages/template-generator/src/template-handlers/auth.tspackages/template-generator/src/template-handlers/deploy.tspackages/template-generator/src/template-handlers/examples.tspackages/template-generator/src/template-handlers/frontend.tspackages/template-generator/src/template-handlers/packages.tspackages/template-generator/src/utils/generated-ignore-patterns.tspackages/template-generator/templates/api/orpc/web/foldkit/src/api/health.ts.hbspackages/template-generator/templates/api/orpc/web/foldkit/src/api/orpc.ts.hbspackages/template-generator/templates/auth/better-auth/web/foldkit/src/auth/client.ts.hbspackages/template-generator/templates/auth/better-auth/web/foldkit/src/auth/session.ts.hbspackages/template-generator/templates/auth/better-auth/web/foldkit/src/page/login.ts.hbspackages/template-generator/templates/auth/better-auth/web/foldkit/src/view/dashboard.ts.hbspackages/template-generator/templates/deploy/docker/compose/docker-compose.yml.hbspackages/template-generator/templates/deploy/docker/web/foldkit/Dockerfile.hbspackages/template-generator/templates/deploy/docker/web/foldkit/nginx.confpackages/template-generator/templates/examples/todo/web/foldkit/src/page/todos.ts.hbspackages/template-generator/templates/frontend/foldkit/_gitignorepackages/template-generator/templates/frontend/foldkit/index.html.hbspackages/template-generator/templates/frontend/foldkit/package.json.hbspackages/template-generator/templates/frontend/foldkit/src/entry.ts.hbspackages/template-generator/templates/frontend/foldkit/src/main.ts.hbspackages/template-generator/templates/frontend/foldkit/src/message.ts.hbspackages/template-generator/templates/frontend/foldkit/src/route.ts.hbspackages/template-generator/templates/frontend/foldkit/src/styles.csspackages/template-generator/templates/frontend/foldkit/src/view/header.ts.hbspackages/template-generator/templates/frontend/foldkit/src/view/home.ts.hbspackages/template-generator/templates/frontend/foldkit/src/view/notFound.ts.hbspackages/template-generator/templates/frontend/foldkit/tsconfig.json.hbspackages/template-generator/templates/frontend/foldkit/vite.config.ts.hbspackages/types/src/constants.tspackages/types/src/schemas.tspackages/types/src/types.ts
| init, | ||
| update, | ||
| view, | ||
| container: document.getElementById("root"), |
There was a problem hiding this comment.
🩺 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:
- 1: https://foldkit.dev/core/runtime
- 2: https://foldkit.dev/core/counter-example
- 3: https://github.com/foldkit/foldkit
- 4: https://foldkit.dev/api-reference/runtime
🏁 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 -200Repository: 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
doneRepository: 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:
- 1: https://foldkit.dev/core/runtime
- 2: https://foldkit.dev/core/counter-example
- 3: https://foldkit.dev/api-reference/runtime
- 4: https://foldkit.dev/core/embedding
🌐 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.
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 asAsyncDataand is fetched by Commands. So the Foldkit branch adds the vanilla@orpc/clientonly, 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/foldkitis a Vite SPA on port 3001 with@foldkit/vite-pluginand Tailwind v4. The cross-cutting templates follow the existing layout:frontend/foldkitapi/orpc/web/foldkitauth/better-auth/web/foldkitexamples/todo/web/foldkitdeploy/docker/web/foldkitdistthrough nginxWhat it rejects, and where
Everything without a Foldkit template fails during configuration rather than after generation, which is the rule
openspec/config.yamlasks for:TRPC_UNSUPPORTED_FRONTENDS, which also replaces the four-wayincludesNuxt ? ... : includesSvelte ? ...chains invalidateApiFrontendCompatibilityandallowedApisForFrontends.--backend self, Tauri and Electrobun.--web-deploy cloudflareand--web-deploy prisma. There is no Alchemy recipe, soDeployedWebFrameworkexcludes Foldkit and a newvalidateCloudflareWebDeployreports it. The prompt hides the option instead of offering a dead end.Docker and Vercel web deployment both work. Vercel gets the SPA
index.htmlrewrite; Docker maps3001:80and health-checks nginx, matching what TanStack Router already does.Verification
bun run check,packages/template-generatortypecheck, andapps/clitypecheck are clean. The one remainingapps/clierror, inprompts/database-setup.ts, and theapps/webNext.js prerender failure both reproduce onmainuntouched.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 instack-builder-compatibility.test.ts.BTS_MATRIX_MODE=smoke: 307 pass, 0 fail.main; the rest share the same pre-existingnext+planetscale+cloudflaresignature and none involve Foldkit.Foldkit Frontendsuite inapps/cli/test/frontend.test.tscovers 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 --noEmitandvite buildpass, and in a headless browser:/dashboard, which shows the session and theprivateDataresponse,/dashboardwhile signed out redirects to/login,/loginwhile signed in redirects to/dashboard, sign-out returns to/,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
foldkit@^0.145.0,@foldkit/ui@^0.145.0,@foldkit/vite-plugin@^0.13.1, andeffect@4.0.0-rc.108, which is the version Foldkit 0.145 requires.Summary by CodeRabbit
New Features
Bug Fixes
Documentation