alchemy 0.37.2 → 0.38.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (262) hide show
  1. package/bin/alchemy.mjs +44306 -48055
  2. package/bin/alchemy.ts +80 -85
  3. package/bin/commands/create.ts +263 -0
  4. package/bin/constants.ts +13 -0
  5. package/bin/errors.ts +11 -0
  6. package/bin/services/dependencies.ts +47 -0
  7. package/bin/services/get-package-version.ts +11 -0
  8. package/bin/services/package-manager.ts +113 -0
  9. package/bin/services/template-manager.ts +137 -0
  10. package/bin/types.ts +83 -0
  11. package/lib/alchemy.d.ts.map +1 -1
  12. package/lib/alchemy.js +12 -3
  13. package/lib/alchemy.js.map +1 -1
  14. package/lib/apply.d.ts +2 -0
  15. package/lib/apply.d.ts.map +1 -1
  16. package/lib/apply.js +47 -12
  17. package/lib/apply.js.map +1 -1
  18. package/lib/build-date.d.ts +6 -0
  19. package/lib/build-date.d.ts.map +1 -0
  20. package/lib/build-date.js +8 -0
  21. package/lib/build-date.js.map +1 -0
  22. package/lib/cloudflare/api.d.ts.map +1 -1
  23. package/lib/cloudflare/api.js +2 -1
  24. package/lib/cloudflare/api.js.map +1 -1
  25. package/lib/cloudflare/do-state-store/internal.js +5 -3
  26. package/lib/cloudflare/do-state-store/internal.js.map +1 -1
  27. package/lib/cloudflare/do-state-store/worker.d.ts.map +1 -1
  28. package/lib/cloudflare/do-state-store/worker.js +6 -1
  29. package/lib/cloudflare/do-state-store/worker.js.map +1 -1
  30. package/lib/cloudflare/pipeline.d.ts +1 -1
  31. package/lib/cloudflare/pipeline.d.ts.map +1 -1
  32. package/lib/cloudflare/pipeline.js +6 -1
  33. package/lib/cloudflare/pipeline.js.map +1 -1
  34. package/lib/cloudflare/worker-stub.d.ts +23 -2
  35. package/lib/cloudflare/worker-stub.d.ts.map +1 -1
  36. package/lib/cloudflare/worker-stub.js +16 -2
  37. package/lib/cloudflare/worker-stub.js.map +1 -1
  38. package/lib/cloudflare/worker.d.ts +5 -4
  39. package/lib/cloudflare/worker.d.ts.map +1 -1
  40. package/lib/cloudflare/worker.js +4 -7
  41. package/lib/cloudflare/worker.js.map +1 -1
  42. package/lib/context.d.ts +2 -2
  43. package/lib/context.d.ts.map +1 -1
  44. package/lib/destroy.d.ts +8 -2
  45. package/lib/destroy.d.ts.map +1 -1
  46. package/lib/destroy.js +19 -5
  47. package/lib/destroy.js.map +1 -1
  48. package/lib/scope.d.ts +26 -4
  49. package/lib/scope.d.ts.map +1 -1
  50. package/lib/scope.js +104 -9
  51. package/lib/scope.js.map +1 -1
  52. package/lib/sentry/project.js +1 -1
  53. package/lib/sentry/project.js.map +1 -1
  54. package/lib/util/logger.js +1 -1
  55. package/lib/util/logger.js.map +1 -1
  56. package/lib/util/mutex.d.ts +9 -0
  57. package/lib/util/mutex.d.ts.map +1 -0
  58. package/lib/util/mutex.js +35 -0
  59. package/lib/util/mutex.js.map +1 -0
  60. package/package.json +16 -6
  61. package/src/alchemy.ts +17 -5
  62. package/src/apply.ts +67 -17
  63. package/src/build-date.ts +8 -0
  64. package/src/cloudflare/api.ts +2 -1
  65. package/src/cloudflare/do-state-store/internal.ts +5 -3
  66. package/src/cloudflare/do-state-store/worker.ts +13 -3
  67. package/src/cloudflare/pipeline.ts +6 -0
  68. package/src/cloudflare/worker-stub.ts +31 -2
  69. package/src/cloudflare/worker.ts +6 -15
  70. package/src/context.ts +2 -2
  71. package/src/destroy.ts +30 -7
  72. package/src/scope.ts +145 -10
  73. package/src/sentry/project.ts +1 -1
  74. package/src/util/logger.ts +1 -1
  75. package/src/util/mutex.ts +33 -0
  76. package/templates/astro/.vscode/extensions.json +4 -0
  77. package/templates/astro/.vscode/launch.json +11 -0
  78. package/templates/astro/README.md +48 -0
  79. package/templates/astro/_env.example +1 -0
  80. package/templates/astro/_gitignore +27 -0
  81. package/templates/astro/alchemy.run.ts +16 -0
  82. package/templates/astro/astro.config.mjs +8 -0
  83. package/templates/astro/package.json +23 -0
  84. package/templates/astro/public/favicon.svg +9 -0
  85. package/templates/astro/src/assets/astro.svg +1 -0
  86. package/templates/astro/src/assets/background.svg +1 -0
  87. package/templates/astro/src/components/Welcome.astro +210 -0
  88. package/templates/astro/src/layouts/Layout.astro +22 -0
  89. package/templates/astro/src/pages/api/hello.ts +19 -0
  90. package/templates/astro/src/pages/index.astro +11 -0
  91. package/templates/astro/tsconfig.json +18 -0
  92. package/templates/astro/types/env.d.ts +16 -0
  93. package/templates/astro/wrangler.jsonc +6 -0
  94. package/templates/nuxt/README.md +75 -0
  95. package/templates/nuxt/_env +1 -0
  96. package/templates/nuxt/_env.example +1 -0
  97. package/templates/nuxt/_gitignore +27 -0
  98. package/templates/nuxt/alchemy.run.ts +16 -0
  99. package/templates/nuxt/app.vue +6 -0
  100. package/templates/nuxt/nuxt.config.ts +13 -0
  101. package/templates/nuxt/package.json +26 -0
  102. package/templates/nuxt/public/favicon.ico +0 -0
  103. package/templates/nuxt/public/robots.txt +2 -0
  104. package/templates/nuxt/server/api/hello.ts +7 -0
  105. package/templates/nuxt/server/middleware/auth.ts +5 -0
  106. package/templates/nuxt/server/middleware/hello.ts +5 -0
  107. package/templates/nuxt/server/tsconfig.json +3 -0
  108. package/templates/nuxt/tsconfig.json +15 -0
  109. package/templates/nuxt/types/env.d.ts +16 -0
  110. package/templates/react-router/.vscode/settings.json +5 -0
  111. package/templates/react-router/README.md +79 -0
  112. package/templates/react-router/_env +1 -0
  113. package/templates/react-router/_env.example +1 -0
  114. package/templates/react-router/_gitignore +15 -0
  115. package/templates/react-router/alchemy.run.ts +17 -0
  116. package/templates/react-router/app/app.css +15 -0
  117. package/templates/react-router/app/entry.server.tsx +43 -0
  118. package/templates/react-router/app/root.tsx +75 -0
  119. package/templates/react-router/app/routes/home.tsx +17 -0
  120. package/templates/react-router/app/routes.ts +3 -0
  121. package/templates/react-router/app/welcome/logo-dark.svg +23 -0
  122. package/templates/react-router/app/welcome/logo-light.svg +23 -0
  123. package/templates/react-router/app/welcome/welcome.tsx +90 -0
  124. package/templates/react-router/package.json +34 -0
  125. package/templates/react-router/public/favicon.ico +0 -0
  126. package/templates/react-router/react-router.config.ts +8 -0
  127. package/templates/react-router/tsconfig.cloudflare.json +27 -0
  128. package/templates/react-router/tsconfig.json +17 -0
  129. package/templates/react-router/tsconfig.node.json +20 -0
  130. package/templates/react-router/types/env.d.ts +16 -0
  131. package/templates/react-router/vite.config.ts +14 -0
  132. package/templates/react-router/workers/app.ts +23 -0
  133. package/templates/react-router/wrangler.jsonc +6 -0
  134. package/templates/rwsdk/.cursor/rules/rwsdk_rwsdk-interruptors.mdc +247 -0
  135. package/templates/rwsdk/.cursor/rules/rwsdk_rwsdk-middleware.mdc +75 -0
  136. package/templates/rwsdk/.cursor/rules/rwsdk_rwsdk-react.mdc +110 -0
  137. package/templates/rwsdk/.cursor/rules/rwsdk_rwsdk-request-response.mdc +213 -0
  138. package/templates/rwsdk/.devcontainer/Dockerfile +8 -0
  139. package/templates/rwsdk/.devcontainer/devcontainer.json +21 -0
  140. package/templates/rwsdk/README.md +62 -0
  141. package/templates/rwsdk/_env +5 -0
  142. package/templates/rwsdk/_env.example +5 -0
  143. package/templates/rwsdk/_gitignore +71 -0
  144. package/templates/rwsdk/alchemy.run.ts +29 -0
  145. package/templates/rwsdk/package.json +61 -0
  146. package/templates/rwsdk/prisma/schema.prisma +43 -0
  147. package/templates/rwsdk/src/app/Document.tsx +16 -0
  148. package/templates/rwsdk/src/app/headers.ts +32 -0
  149. package/templates/rwsdk/src/app/pages/Home.tsx +13 -0
  150. package/templates/rwsdk/src/app/pages/user/Login.tsx +79 -0
  151. package/templates/rwsdk/src/app/pages/user/functions.ts +171 -0
  152. package/templates/rwsdk/src/app/pages/user/routes.ts +17 -0
  153. package/templates/rwsdk/src/app/shared/links.ts +3 -0
  154. package/templates/rwsdk/src/client.tsx +3 -0
  155. package/templates/rwsdk/src/db.ts +26 -0
  156. package/templates/rwsdk/src/scripts/seed.ts +21 -0
  157. package/templates/rwsdk/src/session/durableObject.ts +63 -0
  158. package/templates/rwsdk/src/session/store.ts +13 -0
  159. package/templates/rwsdk/src/worker.tsx +63 -0
  160. package/templates/rwsdk/tsconfig.json +47 -0
  161. package/templates/rwsdk/types/env.d.ts +16 -0
  162. package/templates/rwsdk/types/rw.d.ts +5 -0
  163. package/templates/rwsdk/types/vite.d.ts +4 -0
  164. package/templates/rwsdk/vite.config.mts +6 -0
  165. package/templates/rwsdk/wrangler.jsonc +28 -0
  166. package/templates/sveltekit/README.md +38 -0
  167. package/templates/sveltekit/_env +1 -0
  168. package/templates/sveltekit/_env.example +1 -0
  169. package/templates/sveltekit/_gitignore +26 -0
  170. package/templates/sveltekit/_npmrc +1 -0
  171. package/templates/sveltekit/_prettierrc +3 -0
  172. package/templates/sveltekit/alchemy.run.ts +16 -0
  173. package/templates/sveltekit/bun.lock +1099 -0
  174. package/templates/sveltekit/package.json +33 -0
  175. package/templates/sveltekit/src/app.css +1 -0
  176. package/templates/sveltekit/src/app.d.ts +13 -0
  177. package/templates/sveltekit/src/app.html +12 -0
  178. package/templates/sveltekit/src/routes/+layout.svelte +7 -0
  179. package/templates/sveltekit/src/routes/+page.svelte +2 -0
  180. package/templates/sveltekit/static/favicon.png +0 -0
  181. package/templates/sveltekit/svelte.config.js +12 -0
  182. package/templates/sveltekit/tsconfig.json +27 -0
  183. package/templates/sveltekit/types/env.d.ts +16 -0
  184. package/templates/sveltekit/vite.config.ts +6 -0
  185. package/templates/sveltekit/wrangler.jsonc +7 -0
  186. package/templates/tanstack-start/.vscode/settings.json +11 -0
  187. package/templates/tanstack-start/README.md +72 -0
  188. package/templates/tanstack-start/_env +1 -0
  189. package/templates/tanstack-start/_env.example +1 -0
  190. package/templates/tanstack-start/_gitignore +22 -0
  191. package/templates/tanstack-start/_prettierignore +4 -0
  192. package/templates/tanstack-start/alchemy.run.ts +16 -0
  193. package/templates/tanstack-start/package.json +37 -0
  194. package/templates/tanstack-start/public/android-chrome-192x192.png +0 -0
  195. package/templates/tanstack-start/public/android-chrome-512x512.png +0 -0
  196. package/templates/tanstack-start/public/apple-touch-icon.png +0 -0
  197. package/templates/tanstack-start/public/favicon-16x16.png +0 -0
  198. package/templates/tanstack-start/public/favicon-32x32.png +0 -0
  199. package/templates/tanstack-start/public/favicon.ico +0 -0
  200. package/templates/tanstack-start/public/favicon.png +0 -0
  201. package/templates/tanstack-start/public/site.webmanifest +19 -0
  202. package/templates/tanstack-start/src/components/DefaultCatchBoundary.tsx +53 -0
  203. package/templates/tanstack-start/src/components/NotFound.tsx +25 -0
  204. package/templates/tanstack-start/src/components/PostError.tsx +5 -0
  205. package/templates/tanstack-start/src/components/UserError.tsx +5 -0
  206. package/templates/tanstack-start/src/router.tsx +22 -0
  207. package/templates/tanstack-start/src/routes/__root.tsx +146 -0
  208. package/templates/tanstack-start/src/routes/_pathlessLayout/_nested-layout/route-a.tsx +10 -0
  209. package/templates/tanstack-start/src/routes/_pathlessLayout/_nested-layout/route-b.tsx +10 -0
  210. package/templates/tanstack-start/src/routes/_pathlessLayout/_nested-layout.tsx +34 -0
  211. package/templates/tanstack-start/src/routes/_pathlessLayout.tsx +16 -0
  212. package/templates/tanstack-start/src/routes/api/users.$userId.ts +28 -0
  213. package/templates/tanstack-start/src/routes/api/users.ts +59 -0
  214. package/templates/tanstack-start/src/routes/customScript[.]js.ts +10 -0
  215. package/templates/tanstack-start/src/routes/deferred.tsx +62 -0
  216. package/templates/tanstack-start/src/routes/index.tsx +12 -0
  217. package/templates/tanstack-start/src/routes/posts.$postId.tsx +34 -0
  218. package/templates/tanstack-start/src/routes/posts.index.tsx +8 -0
  219. package/templates/tanstack-start/src/routes/posts.tsx +38 -0
  220. package/templates/tanstack-start/src/routes/posts_.$postId.deep.tsx +29 -0
  221. package/templates/tanstack-start/src/routes/redirect.tsx +9 -0
  222. package/templates/tanstack-start/src/routes/users.$userId.tsx +44 -0
  223. package/templates/tanstack-start/src/routes/users.index.tsx +18 -0
  224. package/templates/tanstack-start/src/routes/users.tsx +49 -0
  225. package/templates/tanstack-start/src/styles/app.css +12 -0
  226. package/templates/tanstack-start/src/utils/loggingMiddleware.tsx +41 -0
  227. package/templates/tanstack-start/src/utils/posts.tsx +40 -0
  228. package/templates/tanstack-start/src/utils/seo.ts +33 -0
  229. package/templates/tanstack-start/src/utils/users.tsx +5 -0
  230. package/templates/tanstack-start/tsconfig.json +31 -0
  231. package/templates/tanstack-start/types/env.d.ts +16 -0
  232. package/templates/tanstack-start/vite.config.ts +33 -0
  233. package/templates/tanstack-start/wrangler.jsonc +7 -0
  234. package/templates/typescript/README.md +15 -0
  235. package/templates/typescript/_gitignore +37 -0
  236. package/templates/typescript/alchemy.run.ts +15 -0
  237. package/templates/typescript/index.ts +1 -0
  238. package/templates/typescript/package.json +18 -0
  239. package/templates/typescript/src/worker.js +5 -0
  240. package/templates/typescript/src/worker.ts +7 -0
  241. package/templates/typescript/tsconfig.json +21 -0
  242. package/templates/typescript/types/env.d.ts +16 -0
  243. package/templates/vite/README.md +54 -0
  244. package/templates/vite/_env.example +1 -0
  245. package/templates/vite/_gitignore +27 -0
  246. package/templates/vite/alchemy.run.ts +17 -0
  247. package/templates/vite/eslint.config.js +28 -0
  248. package/templates/vite/index.html +13 -0
  249. package/templates/vite/package.json +35 -0
  250. package/templates/vite/public/vite.svg +1 -0
  251. package/templates/vite/src/App.css +42 -0
  252. package/templates/vite/src/App.tsx +35 -0
  253. package/templates/vite/src/assets/react.svg +1 -0
  254. package/templates/vite/src/index.css +68 -0
  255. package/templates/vite/src/main.tsx +10 -0
  256. package/templates/vite/src/vite-env.d.ts +1 -0
  257. package/templates/vite/tsconfig.json +34 -0
  258. package/templates/vite/types/env.d.ts +16 -0
  259. package/templates/vite/vite.config.ts +9 -0
  260. package/templates/vite/worker/index.ts +12 -0
  261. package/templates/vite/wrangler.jsonc +6 -0
  262. package/bin/create-alchemy.ts +0 -1220
package/templates/sveltekit/package.json ADDED
@@ -0,0 +1,33 @@
1
+ {
2
+ "type": "module",
3
+ "name": "sveltekit",
4
+ "private": true,
5
+ "version": "0.0.1",
6
+ "scripts": {
7
+ "build": "vite build",
8
+ "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
9
+ "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
10
+ "deploy": "bun --env-file=./.env ./alchemy.run.ts",
11
+ "destroy": "bun --env-file=./.env ./alchemy.run.ts --destroy",
12
+ "dev": "vite dev",
13
+ "prepare": "svelte-kit sync || echo ''",
14
+ "preview": "vite preview"
15
+ },
16
+ "devDependencies": {
17
+ "alchemy": "workspace:*",
18
+ "@cloudflare/workers-types": "^4.20250620.0",
19
+ "miniflare": "^4.20250617.3",
20
+ "@sveltejs/adapter-auto": "^6.0.0",
21
+ "@sveltejs/adapter-cloudflare": "^7.0.4",
22
+ "@sveltejs/kit": "^2.16.0",
23
+ "@sveltejs/vite-plugin-svelte": "^5.1.0",
24
+ "@tailwindcss/vite": "^4.0.0",
25
+ "prettier-plugin-tailwindcss": "^0.6.11",
26
+ "svelte": "^5.0.0",
27
+ "svelte-check": "^4.0.0",
28
+ "tailwindcss": "^4.0.0",
29
+ "typescript": "^5.8.3",
30
+ "vite": "^6.2.6",
31
+ "vite-plugin-devtools-json": "^0.2.0"
32
+ }
33
+ }
package/templates/sveltekit/src/app.css ADDED
@@ -0,0 +1 @@
1
+ @import "tailwindcss";
package/templates/sveltekit/src/app.d.ts ADDED
@@ -0,0 +1,13 @@
1
+ // See https://svelte.dev/docs/kit/types#app.d.ts
2
+ // for information about these interfaces
3
+ declare global {
4
+ namespace App {
5
+ // interface Error {}
6
+ // interface Locals {}
7
+ // interface PageData {}
8
+ // interface PageState {}
9
+ // interface Platform {}
10
+ }
11
+ }
12
+
13
+ export {};
package/templates/sveltekit/src/app.html ADDED
@@ -0,0 +1,12 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8" />
5
+ <link rel="icon" href="%sveltekit.assets%/favicon.png" />
6
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
7
+ %sveltekit.head%
8
+ </head>
9
+ <body data-sveltekit-preload-data="hover">
10
+ <div style="display: contents">%sveltekit.body%</div>
11
+ </body>
12
+ </html>
package/templates/sveltekit/src/routes/+layout.svelte ADDED
@@ -0,0 +1,7 @@
1
+ <script lang="ts">
2
+ import '../app.css';
3
+
4
+ let { children } = $props();
5
+ </script>
6
+
7
+ {@render children()}
package/templates/sveltekit/src/routes/+page.svelte ADDED
@@ -0,0 +1,2 @@
1
+ <h1>Welcome to SvelteKit</h1>
2
+ <p>Visit <a href="https://svelte.dev/docs/kit">svelte.dev/docs/kit</a> to read the documentation</p>
package/templates/sveltekit/svelte.config.js ADDED
@@ -0,0 +1,12 @@
1
+ import adapter from '@sveltejs/adapter-cloudflare';
2
+ import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
3
+
4
+ /** @type {import('@sveltejs/kit').Config} */
5
+ const config = {
6
+ preprocess: vitePreprocess(),
7
+ kit: {
8
+ adapter: adapter()
9
+ }
10
+ };
11
+
12
+ export default config;
package/templates/sveltekit/tsconfig.json ADDED
@@ -0,0 +1,27 @@
1
+ {
2
+ "extends": "./.svelte-kit/tsconfig.json",
3
+ "compilerOptions": {
4
+ "allowJs": true,
5
+ "checkJs": true,
6
+ "esModuleInterop": true,
7
+ "forceConsistentCasingInFileNames": true,
8
+ "resolveJsonModule": true,
9
+ "skipLibCheck": true,
10
+ "sourceMap": true,
11
+ "strict": true,
12
+ "moduleResolution": "bundler",
13
+ "types": [
14
+ "@cloudflare/workers-types",
15
+ "./types/env.d.ts"
16
+ ]
17
+ },
18
+ "include": [
19
+ "alchemy.run.ts",
20
+ "types/**/*.ts"
21
+ ]
22
+ // Path aliases are handled by https://svelte.dev/docs/kit/configuration#alias
23
+ // except $lib which is handled by https://svelte.dev/docs/kit/configuration#files
24
+ //
25
+ // If you want to overwrite includes/excludes, make sure to copy over the relevant includes/excludes
26
+ // from the referenced tsconfig.json - TypeScript does not merge them in
27
+ }
package/templates/sveltekit/types/env.d.ts ADDED
@@ -0,0 +1,16 @@
1
+ // This file infers types for the cloudflare:workers environment from your Alchemy Worker.
2
+ // @see https://alchemy.run/docs/concepts/bindings.html#type-safe-bindings
3
+
4
+ import type { worker } from "../alchemy.run.ts";
5
+
6
+ export type CloudflareEnv = typeof worker.Env;
7
+
8
+ declare global {
9
+ type Env = CloudflareEnv;
10
+ }
11
+
12
+ declare module "cloudflare:workers" {
13
+ namespace Cloudflare {
14
+ export interface Env extends CloudflareEnv {}
15
+ }
16
+ }
package/templates/sveltekit/vite.config.ts ADDED
@@ -0,0 +1,6 @@
1
+ import { sveltekit } from '@sveltejs/kit/vite';
2
+ import { defineConfig } from 'vite';
3
+
4
+ export default defineConfig({
5
+ plugins: [sveltekit()],
6
+ });
package/templates/sveltekit/wrangler.jsonc ADDED
@@ -0,0 +1,7 @@
1
+ {
2
+ "name": "website",
3
+ "main": ".svelte-kit/cloudflare/_worker.js",
4
+ "compatibility_date": "2025-04-20",
5
+ "compatibility_flags": ["nodejs_compat"],
6
+ "assets": { "binding": "ASSETS", "directory": ".svelte-kit/cloudflare" }
7
+ }
package/templates/tanstack-start/.vscode/settings.json ADDED
@@ -0,0 +1,11 @@
1
+ {
2
+ "files.watcherExclude": {
3
+ "**/routeTree.gen.ts": true
4
+ },
5
+ "search.exclude": {
6
+ "**/routeTree.gen.ts": true
7
+ },
8
+ "files.readonlyInclude": {
9
+ "**/routeTree.gen.ts": true
10
+ }
11
+ }
package/templates/tanstack-start/README.md ADDED
@@ -0,0 +1,72 @@
1
+ # Welcome to TanStack.com!
2
+
3
+ This site is built with TanStack Router!
4
+
5
+ - [TanStack Router Docs](https://tanstack.com/router)
6
+
7
+ It's deployed automagically with Netlify!
8
+
9
+ - [Netlify](https://netlify.com/)
10
+
11
+ ## Development
12
+
13
+ From your terminal:
14
+
15
+ ```sh
16
+ pnpm install
17
+ pnpm dev
18
+ ```
19
+
20
+ This starts your app in development mode, rebuilding assets on file changes.
21
+
22
+ ## Editing and previewing the docs of TanStack projects locally
23
+
24
+ The documentations for all TanStack projects except for `React Charts` are hosted on [https://tanstack.com](https://tanstack.com), powered by this TanStack Router app.
25
+ In production, the markdown doc pages are fetched from the GitHub repos of the projects, but in development they are read from the local file system.
26
+
27
+ Follow these steps if you want to edit the doc pages of a project (in these steps we'll assume it's [`TanStack/form`](https://github.com/tanstack/form)) and preview them locally :
28
+
29
+ 1. Create a new directory called `tanstack`.
30
+
31
+ ```sh
32
+ mkdir tanstack
33
+ ```
34
+
35
+ 2. Enter the directory and clone this repo and the repo of the project there.
36
+
37
+ ```sh
38
+ cd tanstack
39
+ git clone git@github.com:TanStack/tanstack.com.git
40
+ git clone git@github.com:TanStack/form.git
41
+ ```
42
+
43
+ > [!NOTE]
44
+ > Your `tanstack` directory should look like this:
45
+ >
46
+ > ```
47
+ > tanstack/
48
+ > |
49
+ > +-- form/
50
+ > |
51
+ > +-- tanstack.com/
52
+ > ```
53
+
54
+ > [!WARNING]
55
+ > Make sure the name of the directory in your local file system matches the name of the project's repo. For example, `tanstack/form` must be cloned into `form` (this is the default) instead of `some-other-name`, because that way, the doc pages won't be found.
56
+
57
+ 3. Enter the `tanstack/tanstack.com` directory, install the dependencies and run the app in dev mode:
58
+
59
+ ```sh
60
+ cd tanstack.com
61
+ pnpm i
62
+ # The app will run on https://localhost:3000 by default
63
+ pnpm dev
64
+ ```
65
+
66
+ 4. Now you can visit http://localhost:3000/form/latest/docs/overview in the browser and see the changes you make in `tanstack/form/docs`.
67
+
68
+ > [!NOTE]
69
+ > The updated pages need to be manually reloaded in the browser.
70
+
71
+ > [!WARNING]
72
+ > You will need to update the `docs/config.json` file (in the project's repo) if you add a new doc page!
package/templates/tanstack-start/_env ADDED
@@ -0,0 +1 @@
1
+ ALCHEMY_PASSWORD=change-me
package/templates/tanstack-start/_env.example ADDED
@@ -0,0 +1 @@
1
+ ALCHEMY_PASSWORD=change-me
package/templates/tanstack-start/_gitignore ADDED
@@ -0,0 +1,22 @@
1
+ node_modules
2
+ package-lock.json
3
+ yarn.lock
4
+
5
+ .DS_Store
6
+ .cache
7
+ .env
8
+ .vercel
9
+ .output
10
+ .nitro
11
+ /build/
12
+ /api/
13
+ /server/build
14
+ /public/build# Sentry Config File
15
+ .env.sentry-build-plugin
16
+ /test-results/
17
+ /playwright-report/
18
+ /blob-report/
19
+ /playwright/.cache/
20
+ .tanstack
21
+ .alchemy/
22
+ .env
package/templates/tanstack-start/_prettierignore ADDED
@@ -0,0 +1,4 @@
1
+ **/build
2
+ **/public
3
+ pnpm-lock.yaml
4
+ routeTree.gen.ts
package/templates/tanstack-start/alchemy.run.ts ADDED
@@ -0,0 +1,16 @@
1
+ /// <reference types="@types/node" />
2
+
3
+ import alchemy from "alchemy";
4
+ import { TanStackStart } from "alchemy/cloudflare";
5
+
6
+ const app = await alchemy("my-alchemy-app");
7
+
8
+ export const worker = await TanStackStart("website", {
9
+ command: "bun run build",
10
+ });
11
+
12
+ console.log({
13
+ url: worker.url,
14
+ });
15
+
16
+ await app.finalize();
package/templates/tanstack-start/package.json ADDED
@@ -0,0 +1,37 @@
1
+ {
2
+ "type": "module",
3
+ "name": "tanstack-start",
4
+ "private": true,
5
+ "sideEffects": false,
6
+ "scripts": {
7
+ "build": "vite build",
8
+ "deploy": "bun --env-file=./.env ./alchemy.run.ts",
9
+ "destroy": "bun --env-file=./.env ./alchemy.run.ts --destroy",
10
+ "dev": "vite dev",
11
+ "start": "node .output/server/index.mjs"
12
+ },
13
+ "dependencies": {
14
+ "@tanstack/react-router": "^1.121.27",
15
+ "@tanstack/react-router-devtools": "^1.121.27",
16
+ "@tanstack/react-start": "^1.121.32",
17
+ "react": "^19.0.0",
18
+ "react-dom": "^19.0.0",
19
+ "tailwind-merge": "3",
20
+ "zod": "^3.24.2"
21
+ },
22
+ "devDependencies": {
23
+ "alchemy": "workspace:*",
24
+ "@cloudflare/workers-types": "^4.20250620.0",
25
+ "@tailwindcss/vite": "^4.1.10",
26
+ "@types/node": "^22.5.4",
27
+ "@types/react": "^19.0.8",
28
+ "@types/react-dom": "^19.0.3",
29
+ "autoprefixer": "^10.4.20",
30
+ "miniflare": "^4.20250617.3",
31
+ "postcss": "^8.5.6",
32
+ "tailwindcss": "4",
33
+ "typescript": "^5.8.3",
34
+ "vite": "^6.3.5",
35
+ "vite-tsconfig-paths": "^5.1.4"
36
+ }
37
+ }
package/templates/tanstack-start/public/site.webmanifest ADDED
@@ -0,0 +1,19 @@
1
+ {
2
+ "name": "",
3
+ "short_name": "",
4
+ "icons": [
5
+ {
6
+ "src": "/android-chrome-192x192.png",
7
+ "sizes": "192x192",
8
+ "type": "image/png"
9
+ },
10
+ {
11
+ "src": "/android-chrome-512x512.png",
12
+ "sizes": "512x512",
13
+ "type": "image/png"
14
+ }
15
+ ],
16
+ "theme_color": "#ffffff",
17
+ "background_color": "#ffffff",
18
+ "display": "standalone"
19
+ }
package/templates/tanstack-start/src/components/DefaultCatchBoundary.tsx ADDED
@@ -0,0 +1,53 @@
1
+ import {
2
+ ErrorComponent,
3
+ Link,
4
+ rootRouteId,
5
+ useMatch,
6
+ useRouter,
7
+ } from '@tanstack/react-router'
8
+ import type { ErrorComponentProps } from '@tanstack/react-router'
9
+
10
+ export function DefaultCatchBoundary({ error }: ErrorComponentProps) {
11
+ const router = useRouter()
12
+ const isRoot = useMatch({
13
+ strict: false,
14
+ select: (state) => state.id === rootRouteId,
15
+ })
16
+
17
+ console.error('DefaultCatchBoundary Error:', error)
18
+
19
+ return (
20
+ <div className="min-w-0 flex-1 p-4 flex flex-col items-center justify-center gap-6">
21
+ <ErrorComponent error={error} />
22
+ <div className="flex gap-2 items-center flex-wrap">
23
+ <button
24
+ onClick={() => {
25
+ router.invalidate()
26
+ }}
27
+ className={`px-2 py-1 bg-gray-600 dark:bg-gray-700 rounded text-white uppercase font-extrabold`}
28
+ >
29
+ Try Again
30
+ </button>
31
+ {isRoot ? (
32
+ <Link
33
+ to="/"
34
+ className={`px-2 py-1 bg-gray-600 dark:bg-gray-700 rounded text-white uppercase font-extrabold`}
35
+ >
36
+ Home
37
+ </Link>
38
+ ) : (
39
+ <Link
40
+ to="/"
41
+ className={`px-2 py-1 bg-gray-600 dark:bg-gray-700 rounded text-white uppercase font-extrabold`}
42
+ onClick={(e) => {
43
+ e.preventDefault()
44
+ window.history.back()
45
+ }}
46
+ >
47
+ Go Back
48
+ </Link>
49
+ )}
50
+ </div>
51
+ </div>
52
+ )
53
+ }
package/templates/tanstack-start/src/components/NotFound.tsx ADDED
@@ -0,0 +1,25 @@
1
+ import { Link } from '@tanstack/react-router'
2
+
3
+ export function NotFound({ children }: { children?: any }) {
4
+ return (
5
+ <div className="space-y-2 p-2">
6
+ <div className="text-gray-600 dark:text-gray-400">
7
+ {children || <p>The page you are looking for does not exist.</p>}
8
+ </div>
9
+ <p className="flex items-center gap-2 flex-wrap">
10
+ <button
11
+ onClick={() => window.history.back()}
12
+ className="bg-emerald-500 text-white px-2 py-1 rounded uppercase font-black text-sm"
13
+ >
14
+ Go back
15
+ </button>
16
+ <Link
17
+ to="/"
18
+ className="bg-cyan-600 text-white px-2 py-1 rounded uppercase font-black text-sm"
19
+ >
20
+ Start Over
21
+ </Link>
22
+ </p>
23
+ </div>
24
+ )
25
+ }
package/templates/tanstack-start/src/components/PostError.tsx ADDED
@@ -0,0 +1,5 @@
1
+ import { ErrorComponent, ErrorComponentProps } from '@tanstack/react-router'
2
+
3
+ export function PostErrorComponent({ error }: ErrorComponentProps) {
4
+ return <ErrorComponent error={error} />
5
+ }
package/templates/tanstack-start/src/components/UserError.tsx ADDED
@@ -0,0 +1,5 @@
1
+ import { ErrorComponent, ErrorComponentProps } from '@tanstack/react-router'
2
+
3
+ export function UserErrorComponent({ error }: ErrorComponentProps) {
4
+ return <ErrorComponent error={error} />
5
+ }
package/templates/tanstack-start/src/router.tsx ADDED
@@ -0,0 +1,22 @@
1
+ import { createRouter as createTanStackRouter } from '@tanstack/react-router'
2
+ import { routeTree } from './routeTree.gen'
3
+ import { DefaultCatchBoundary } from './components/DefaultCatchBoundary'
4
+ import { NotFound } from './components/NotFound'
5
+
6
+ export function createRouter() {
7
+ const router = createTanStackRouter({
8
+ routeTree,
9
+ defaultPreload: 'intent',
10
+ defaultErrorComponent: DefaultCatchBoundary,
11
+ defaultNotFoundComponent: () => <NotFound />,
12
+ scrollRestoration: true,
13
+ })
14
+
15
+ return router
16
+ }
17
+
18
+ declare module '@tanstack/react-router' {
19
+ interface Register {
20
+ router: ReturnType<typeof createRouter>
21
+ }
22
+ }
package/templates/tanstack-start/src/routes/__root.tsx ADDED
@@ -0,0 +1,146 @@
1
+ /// <reference types="vite/client" />
2
+ import {
3
+ HeadContent,
4
+ Link,
5
+ Outlet,
6
+ Scripts,
7
+ createRootRoute,
8
+ } from '@tanstack/react-router'
9
+ import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'
10
+ import * as React from 'react'
11
+ import { DefaultCatchBoundary } from '~/components/DefaultCatchBoundary'
12
+ import { NotFound } from '~/components/NotFound'
13
+ import appCss from '~/styles/app.css?url'
14
+ import { seo } from '~/utils/seo'
15
+
16
+ export const Route = createRootRoute({
17
+ head: () => ({
18
+ meta: [
19
+ {
20
+ charSet: 'utf-8',
21
+ },
22
+ {
23
+ name: 'viewport',
24
+ content: 'width=device-width, initial-scale=1',
25
+ },
26
+ ...seo({
27
+ title:
28
+ 'TanStack Start | Type-Safe, Client-First, Full-Stack React Framework',
29
+ description: `TanStack Start is a type-safe, client-first, full-stack React framework. `,
30
+ }),
31
+ ],
32
+ links: [
33
+ { rel: 'stylesheet', href: appCss },
34
+ {
35
+ rel: 'apple-touch-icon',
36
+ sizes: '180x180',
37
+ href: '/apple-touch-icon.png',
38
+ },
39
+ {
40
+ rel: 'icon',
41
+ type: 'image/png',
42
+ sizes: '32x32',
43
+ href: '/favicon-32x32.png',
44
+ },
45
+ {
46
+ rel: 'icon',
47
+ type: 'image/png',
48
+ sizes: '16x16',
49
+ href: '/favicon-16x16.png',
50
+ },
51
+ { rel: 'manifest', href: '/site.webmanifest', color: '#fffff' },
52
+ { rel: 'icon', href: '/favicon.ico' },
53
+ ],
54
+ scripts: [
55
+ {
56
+ src: '/customScript.js',
57
+ type: 'text/javascript',
58
+ },
59
+ ],
60
+ }),
61
+ errorComponent: (props) => {
62
+ return (
63
+ <RootDocument>
64
+ <DefaultCatchBoundary {...props} />
65
+ </RootDocument>
66
+ )
67
+ },
68
+ notFoundComponent: () => <NotFound />,
69
+ component: RootComponent,
70
+ })
71
+
72
+ function RootComponent() {
73
+ return (
74
+ <RootDocument>
75
+ <Outlet />
76
+ </RootDocument>
77
+ )
78
+ }
79
+
80
+ function RootDocument({ children }: { children: React.ReactNode }) {
81
+ return (
82
+ <html>
83
+ <head>
84
+ <HeadContent />
85
+ </head>
86
+ <body>
87
+ <div className="p-2 flex gap-2 text-lg">
88
+ <Link
89
+ to="/"
90
+ activeProps={{
91
+ className: 'font-bold',
92
+ }}
93
+ activeOptions={{ exact: true }}
94
+ >
95
+ Home
96
+ </Link>{' '}
97
+ <Link
98
+ to="/posts"
99
+ activeProps={{
100
+ className: 'font-bold',
101
+ }}
102
+ >
103
+ Posts
104
+ </Link>{' '}
105
+ <Link
106
+ to="/users"
107
+ activeProps={{
108
+ className: 'font-bold',
109
+ }}
110
+ >
111
+ Users
112
+ </Link>{' '}
113
+ <Link
114
+ to="/route-a"
115
+ activeProps={{
116
+ className: 'font-bold',
117
+ }}
118
+ >
119
+ Pathless Layout
120
+ </Link>{' '}
121
+ <Link
122
+ to="/deferred"
123
+ activeProps={{
124
+ className: 'font-bold',
125
+ }}
126
+ >
127
+ Deferred
128
+ </Link>{' '}
129
+ <Link
130
+ // @ts-expect-error
131
+ to="/this-route-does-not-exist"
132
+ activeProps={{
133
+ className: 'font-bold',
134
+ }}
135
+ >
136
+ This Route Does Not Exist
137
+ </Link>
138
+ </div>
139
+ <hr />
140
+ {children}
141
+ <TanStackRouterDevtools position="bottom-right" />
142
+ <Scripts />
143
+ </body>
144
+ </html>
145
+ )
146
+ }
package/templates/tanstack-start/src/routes/_pathlessLayout/_nested-layout/route-a.tsx ADDED
@@ -0,0 +1,10 @@
1
+ import { createFileRoute } from '@tanstack/react-router'
2
+ export const Route = createFileRoute('/_pathlessLayout/_nested-layout/route-a')(
3
+ {
4
+ component: LayoutAComponent,
5
+ },
6
+ )
7
+
8
+ function LayoutAComponent() {
9
+ return <div>I'm A!</div>
10
+ }
package/templates/tanstack-start/src/routes/_pathlessLayout/_nested-layout/route-b.tsx ADDED
@@ -0,0 +1,10 @@
1
+ import { createFileRoute } from '@tanstack/react-router'
2
+ export const Route = createFileRoute('/_pathlessLayout/_nested-layout/route-b')(
3
+ {
4
+ component: LayoutBComponent,
5
+ },
6
+ )
7
+
8
+ function LayoutBComponent() {
9
+ return <div>I'm B!</div>
10
+ }