spacefn-docs 0.0.0-stage → 0.11.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 (366) hide show
  1. package/LICENSE +200 -0
  2. package/README.md +15 -2
  3. package/assets/reader.css +1131 -0
  4. package/assets/reader.js +324 -0
  5. package/content/1-getting-started.md +107 -0
  6. package/content/2-conventions.md +138 -0
  7. package/content/3-best-practices.md +68 -0
  8. package/content/4-folders/1-app/1-entry.md +48 -0
  9. package/content/4-folders/1-app/2-routes.md +92 -0
  10. package/content/4-folders/1-app/3-db.md +81 -0
  11. package/content/4-folders/1-app/4-queues.md +46 -0
  12. package/content/4-folders/1-app/5-crons.md +30 -0
  13. package/content/4-folders/1-app/6-assets.md +53 -0
  14. package/content/4-folders/1-app/7-durable-objects.md +60 -0
  15. package/content/4-folders/1-app/8-workflows.md +46 -0
  16. package/content/4-folders/1-app/index.md +43 -0
  17. package/content/4-folders/2-modules.md +71 -0
  18. package/content/4-folders/3-lib.md +60 -0
  19. package/content/4-folders/4-public.md +24 -0
  20. package/content/4-folders/5-docs.md +23 -0
  21. package/content/4-folders/6-configs.md +57 -0
  22. package/content/4-folders/7-space.md +34 -0
  23. package/content/4-folders/8-env.md +35 -0
  24. package/content/4-folders/9-package-json.md +37 -0
  25. package/content/4-folders/index.md +50 -0
  26. package/content/5-deployment/1-cloudflare.md +70 -0
  27. package/content/5-deployment/2-bun.md +68 -0
  28. package/content/5-deployment/3-infrastructure.md +67 -0
  29. package/content/5-deployment/4-ci-cd.md +179 -0
  30. package/content/5-deployment/index.md +48 -0
  31. package/content/6-guides/1-entry.md +113 -0
  32. package/content/6-guides/2-routes.md +162 -0
  33. package/content/6-guides/3-pages.md +148 -0
  34. package/content/6-guides/4-frontend.md +232 -0
  35. package/content/6-guides/5-database.md +178 -0
  36. package/content/6-guides/6-services.md +125 -0
  37. package/content/6-guides/7-jobs.md +61 -0
  38. package/content/6-guides/8-auth.md +111 -0
  39. package/content/6-guides/9-testing.md +70 -0
  40. package/content/6-guides/index.md +21 -0
  41. package/content/7-reference/1-config.md +67 -0
  42. package/content/7-reference/2-cli.md +45 -0
  43. package/content/7-reference/3-writing-docs.md +206 -0
  44. package/content/7-reference/index.md +15 -0
  45. package/content/index.md +49 -0
  46. package/content/logo.svg +12 -0
  47. package/dist/index.d.mts +72 -0
  48. package/dist/index.mjs +713 -0
  49. package/examples/README.md +18 -0
  50. package/examples/datastar/.env.example +2 -0
  51. package/examples/datastar/README.md +17 -0
  52. package/examples/datastar/app/assets/main.ts +4 -0
  53. package/examples/datastar/app/assets/site.css +3 -0
  54. package/examples/datastar/app/db/main/config.json +5 -0
  55. package/examples/datastar/app/db/main/migrations/0001_votes.sql +8 -0
  56. package/examples/datastar/app/db/main/queries/add-vote.sql +3 -0
  57. package/examples/datastar/app/db/main/queries/tally.sql +1 -0
  58. package/examples/datastar/app/entry.ts +28 -0
  59. package/examples/datastar/app/routes/_middleware.ts +4 -0
  60. package/examples/datastar/app/routes/health.ts +7 -0
  61. package/examples/datastar/app/routes/index.ts +43 -0
  62. package/examples/datastar/configs/env.ts +6 -0
  63. package/examples/datastar/configs/infra.ts +88 -0
  64. package/examples/datastar/configs/tsconfig.json +15 -0
  65. package/examples/datastar/configs/vite.ts +4 -0
  66. package/examples/datastar/configs/vitest.ts +9 -0
  67. package/examples/datastar/lib/types/rocket.d.ts +30 -0
  68. package/examples/datastar/lib/ui/base.css +17 -0
  69. package/examples/datastar/lib/ui/layout.ts +27 -0
  70. package/examples/datastar/modules/poll/client/poll-meter.ts +39 -0
  71. package/examples/datastar/modules/poll/poll.css +13 -0
  72. package/examples/datastar/modules/poll/poll.test.ts +48 -0
  73. package/examples/datastar/modules/poll/poll.ts +62 -0
  74. package/examples/datastar/modules/poll/views.ts +52 -0
  75. package/examples/datastar/package.json +33 -0
  76. package/examples/datastar/tsconfig.json +4 -0
  77. package/examples/lightningcss/.env.example +1 -0
  78. package/examples/lightningcss/README.md +15 -0
  79. package/examples/lightningcss/app/assets/site.css +3 -0
  80. package/examples/lightningcss/app/entry.ts +28 -0
  81. package/examples/lightningcss/app/routes/_middleware.ts +4 -0
  82. package/examples/lightningcss/app/routes/health.ts +7 -0
  83. package/examples/lightningcss/app/routes/index.ts +12 -0
  84. package/examples/lightningcss/configs/Dockerfile +26 -0
  85. package/examples/lightningcss/configs/Dockerfile.dockerignore +9 -0
  86. package/examples/lightningcss/configs/env.ts +4 -0
  87. package/examples/lightningcss/configs/infra.ts +55 -0
  88. package/examples/lightningcss/configs/tsconfig.json +15 -0
  89. package/examples/lightningcss/configs/vite.ts +19 -0
  90. package/examples/lightningcss/configs/vitest.ts +9 -0
  91. package/examples/lightningcss/lib/ui/layout.ts +17 -0
  92. package/examples/lightningcss/lib/ui/tokens.css +23 -0
  93. package/examples/lightningcss/modules/releases/releases.css +20 -0
  94. package/examples/lightningcss/modules/releases/releases.test.ts +18 -0
  95. package/examples/lightningcss/modules/releases/releases.ts +21 -0
  96. package/examples/lightningcss/modules/releases/views.ts +25 -0
  97. package/examples/lightningcss/package.json +33 -0
  98. package/examples/lightningcss/tsconfig.json +4 -0
  99. package/examples/mini-shopify/.env.example +6 -0
  100. package/examples/mini-shopify/README.md +19 -0
  101. package/examples/mini-shopify/app/assets/site.css +2 -0
  102. package/examples/mini-shopify/app/db/platform/config.json +5 -0
  103. package/examples/mini-shopify/app/db/platform/migrations/0001_shops.sql +10 -0
  104. package/examples/mini-shopify/app/db/platform/queries/add-shop.sql +4 -0
  105. package/examples/mini-shopify/app/db/platform/queries/find-shop.sql +3 -0
  106. package/examples/mini-shopify/app/db/platform/queries/list-shops.sql +1 -0
  107. package/examples/mini-shopify/app/db/shop/config.json +6 -0
  108. package/examples/mini-shopify/app/db/shop/migrations/0001_products.sql +11 -0
  109. package/examples/mini-shopify/app/db/shop/queries/add-product.sql +4 -0
  110. package/examples/mini-shopify/app/db/shop/queries/list-products.sql +1 -0
  111. package/examples/mini-shopify/app/db/shop/queries/sell-product.sql +2 -0
  112. package/examples/mini-shopify/app/entry.ts +25 -0
  113. package/examples/mini-shopify/app/routes/_middleware.ts +4 -0
  114. package/examples/mini-shopify/app/routes/health.ts +7 -0
  115. package/examples/mini-shopify/app/routes/index.ts +26 -0
  116. package/examples/mini-shopify/app/routes/s/[shop]/_middleware.ts +6 -0
  117. package/examples/mini-shopify/app/routes/s/[shop]/index.ts +32 -0
  118. package/examples/mini-shopify/configs/Dockerfile +26 -0
  119. package/examples/mini-shopify/configs/Dockerfile.dockerignore +9 -0
  120. package/examples/mini-shopify/configs/env.ts +14 -0
  121. package/examples/mini-shopify/configs/infra.ts +55 -0
  122. package/examples/mini-shopify/configs/tsconfig.json +15 -0
  123. package/examples/mini-shopify/configs/vite.ts +4 -0
  124. package/examples/mini-shopify/configs/vitest.ts +9 -0
  125. package/examples/mini-shopify/lib/ui/base.css +19 -0
  126. package/examples/mini-shopify/lib/ui/layout.ts +17 -0
  127. package/examples/mini-shopify/modules/catalog/catalog.ts +31 -0
  128. package/examples/mini-shopify/modules/catalog/views.ts +39 -0
  129. package/examples/mini-shopify/modules/shops/host.test.ts +38 -0
  130. package/examples/mini-shopify/modules/shops/host.ts +73 -0
  131. package/examples/mini-shopify/modules/shops/shops.test.ts +63 -0
  132. package/examples/mini-shopify/modules/shops/shops.ts +64 -0
  133. package/examples/mini-shopify/modules/shops/views.ts +28 -0
  134. package/examples/mini-shopify/package.json +35 -0
  135. package/examples/mini-shopify/tsconfig.json +4 -0
  136. package/examples/react/.env.example +2 -0
  137. package/examples/react/README.md +18 -0
  138. package/examples/react/app/assets/site.css +3 -0
  139. package/examples/react/app/entry.ts +28 -0
  140. package/examples/react/app/routes/_middleware.ts +4 -0
  141. package/examples/react/app/routes/about.ts +10 -0
  142. package/examples/react/app/routes/health.ts +7 -0
  143. package/examples/react/app/routes/index.ts +12 -0
  144. package/examples/react/configs/Dockerfile +26 -0
  145. package/examples/react/configs/Dockerfile.dockerignore +9 -0
  146. package/examples/react/configs/env.ts +6 -0
  147. package/examples/react/configs/infra.ts +55 -0
  148. package/examples/react/configs/tsconfig.json +16 -0
  149. package/examples/react/configs/vite.ts +7 -0
  150. package/examples/react/configs/vitest.ts +9 -0
  151. package/examples/react/lib/ui/base.css +12 -0
  152. package/examples/react/lib/ui/layout.ts +18 -0
  153. package/examples/react/modules/about/views.ts +8 -0
  154. package/examples/react/modules/shop/products.ts +18 -0
  155. package/examples/react/modules/shop/shop.css +13 -0
  156. package/examples/react/modules/shop/shop.test.ts +28 -0
  157. package/examples/react/modules/shop/shop.ts +13 -0
  158. package/examples/react/modules/shop/ui/Cart.island.tsx +31 -0
  159. package/examples/react/modules/shop/views.ts +16 -0
  160. package/examples/react/package.json +38 -0
  161. package/examples/react/tsconfig.json +4 -0
  162. package/examples/services-bun/README.md +10 -0
  163. package/examples/services-bun/app/assets/main.ts +4 -0
  164. package/examples/services-bun/app/assets/style.css +1 -0
  165. package/examples/services-bun/app/crons/nightly.ts +5 -0
  166. package/examples/services-bun/app/entry.ts +9 -0
  167. package/examples/services-bun/app/queues/jobs.ts +5 -0
  168. package/examples/services-bun/app/routes/index.ts +10 -0
  169. package/examples/services-bun/app/routes/runtime.ts +5 -0
  170. package/examples/services-bun/app/routes/send.ts +8 -0
  171. package/examples/services-bun/app/routes/version.ts +5 -0
  172. package/examples/services-bun/configs/Dockerfile +10 -0
  173. package/examples/services-bun/configs/Dockerfile.dockerignore +4 -0
  174. package/examples/services-bun/configs/infra.ts +28 -0
  175. package/examples/services-bun/configs/tsconfig.json +15 -0
  176. package/examples/services-bun/configs/vite.ts +4 -0
  177. package/examples/services-bun/lib/ui/base.css +3 -0
  178. package/examples/services-bun/lib/ui/layout.ts +13 -0
  179. package/examples/services-bun/modules/status/client/ready.ts +4 -0
  180. package/examples/services-bun/modules/status/status.ts +20 -0
  181. package/examples/services-bun/modules/status/views.ts +4 -0
  182. package/examples/services-bun/package.json +30 -0
  183. package/examples/services-bun/public/robots.txt +1 -0
  184. package/examples/services-bun/tsconfig.json +4 -0
  185. package/examples/services-cloudflare/README.md +9 -0
  186. package/examples/services-cloudflare/app/assets/main.ts +4 -0
  187. package/examples/services-cloudflare/app/crons/nightly.ts +5 -0
  188. package/examples/services-cloudflare/app/db/main/config.json +4 -0
  189. package/examples/services-cloudflare/app/db/main/migrations/0001_notes.sql +2 -0
  190. package/examples/services-cloudflare/app/db/main/queries/add-note.sql +1 -0
  191. package/examples/services-cloudflare/app/db/main/queries/count-notes.sql +3 -0
  192. package/examples/services-cloudflare/app/entry.ts +10 -0
  193. package/examples/services-cloudflare/app/queues/jobs.ts +5 -0
  194. package/examples/services-cloudflare/app/routes/files.ts +5 -0
  195. package/examples/services-cloudflare/app/routes/index.ts +10 -0
  196. package/examples/services-cloudflare/app/routes/limited.ts +7 -0
  197. package/examples/services-cloudflare/app/routes/send.ts +8 -0
  198. package/examples/services-cloudflare/configs/env.ts +3 -0
  199. package/examples/services-cloudflare/configs/infra.ts +88 -0
  200. package/examples/services-cloudflare/configs/tsconfig.json +15 -0
  201. package/examples/services-cloudflare/configs/vite.ts +4 -0
  202. package/examples/services-cloudflare/lib/ui/layout.ts +12 -0
  203. package/examples/services-cloudflare/modules/files/files.ts +9 -0
  204. package/examples/services-cloudflare/modules/status/client/ready.ts +4 -0
  205. package/examples/services-cloudflare/modules/status/status.ts +27 -0
  206. package/examples/services-cloudflare/modules/status/views.ts +8 -0
  207. package/examples/services-cloudflare/package.json +30 -0
  208. package/examples/services-cloudflare/public/robots.txt +1 -0
  209. package/examples/services-cloudflare/tsconfig.json +4 -0
  210. package/examples/solid/.env.example +2 -0
  211. package/examples/solid/README.md +18 -0
  212. package/examples/solid/app/assets/site.css +3 -0
  213. package/examples/solid/app/entry.ts +28 -0
  214. package/examples/solid/app/routes/_middleware.ts +4 -0
  215. package/examples/solid/app/routes/about.ts +10 -0
  216. package/examples/solid/app/routes/health.ts +7 -0
  217. package/examples/solid/app/routes/index.ts +12 -0
  218. package/examples/solid/configs/Dockerfile +26 -0
  219. package/examples/solid/configs/Dockerfile.dockerignore +9 -0
  220. package/examples/solid/configs/env.ts +6 -0
  221. package/examples/solid/configs/infra.ts +55 -0
  222. package/examples/solid/configs/tsconfig.json +17 -0
  223. package/examples/solid/configs/vite.ts +7 -0
  224. package/examples/solid/configs/vitest.ts +12 -0
  225. package/examples/solid/lib/ui/base.css +12 -0
  226. package/examples/solid/lib/ui/layout.ts +18 -0
  227. package/examples/solid/modules/about/views.ts +8 -0
  228. package/examples/solid/modules/shop/products.ts +18 -0
  229. package/examples/solid/modules/shop/shop.css +13 -0
  230. package/examples/solid/modules/shop/shop.test.ts +28 -0
  231. package/examples/solid/modules/shop/shop.ts +13 -0
  232. package/examples/solid/modules/shop/ui/Cart.island.tsx +31 -0
  233. package/examples/solid/modules/shop/views.ts +16 -0
  234. package/examples/solid/package.json +35 -0
  235. package/examples/solid/tsconfig.json +4 -0
  236. package/examples/starter-bun/.env.example +2 -0
  237. package/examples/starter-bun/AGENTS.md +9 -0
  238. package/examples/starter-bun/README.md +47 -0
  239. package/examples/starter-bun/app/assets/site.css +3 -0
  240. package/examples/starter-bun/app/db/main/config.json +5 -0
  241. package/examples/starter-bun/app/db/main/migrations/0001_todos.sql +9 -0
  242. package/examples/starter-bun/app/db/main/queries/add-todo.sql +2 -0
  243. package/examples/starter-bun/app/db/main/queries/list-todos.sql +2 -0
  244. package/examples/starter-bun/app/db/main/queries/toggle-todo.sql +2 -0
  245. package/examples/starter-bun/app/entry.ts +28 -0
  246. package/examples/starter-bun/app/routes/_middleware.ts +4 -0
  247. package/examples/starter-bun/app/routes/health.ts +7 -0
  248. package/examples/starter-bun/app/routes/index.ts +44 -0
  249. package/examples/starter-bun/configs/Dockerfile +26 -0
  250. package/examples/starter-bun/configs/Dockerfile.dockerignore +9 -0
  251. package/examples/starter-bun/configs/env.ts +6 -0
  252. package/examples/starter-bun/configs/infra.ts +55 -0
  253. package/examples/starter-bun/configs/tsconfig.json +15 -0
  254. package/examples/starter-bun/configs/vite.ts +4 -0
  255. package/examples/starter-bun/configs/vitest.ts +9 -0
  256. package/examples/starter-bun/docs/index.md +5 -0
  257. package/examples/starter-bun/lib/ui/base.css +17 -0
  258. package/examples/starter-bun/lib/ui/layout.ts +22 -0
  259. package/examples/starter-bun/modules/todos/todos.css +16 -0
  260. package/examples/starter-bun/modules/todos/todos.test.ts +33 -0
  261. package/examples/starter-bun/modules/todos/todos.ts +31 -0
  262. package/examples/starter-bun/modules/todos/views.ts +38 -0
  263. package/examples/starter-bun/package.json +32 -0
  264. package/examples/starter-bun/public/favicon.svg +1 -0
  265. package/examples/starter-bun/tsconfig.json +4 -0
  266. package/examples/starter-cloudflare/.env.example +2 -0
  267. package/examples/starter-cloudflare/AGENTS.md +9 -0
  268. package/examples/starter-cloudflare/README.md +47 -0
  269. package/examples/starter-cloudflare/app/assets/site.css +3 -0
  270. package/examples/starter-cloudflare/app/db/main/config.json +5 -0
  271. package/examples/starter-cloudflare/app/db/main/migrations/0001_todos.sql +9 -0
  272. package/examples/starter-cloudflare/app/db/main/queries/add-todo.sql +2 -0
  273. package/examples/starter-cloudflare/app/db/main/queries/list-todos.sql +2 -0
  274. package/examples/starter-cloudflare/app/db/main/queries/toggle-todo.sql +2 -0
  275. package/examples/starter-cloudflare/app/entry.ts +28 -0
  276. package/examples/starter-cloudflare/app/routes/_middleware.ts +4 -0
  277. package/examples/starter-cloudflare/app/routes/health.ts +7 -0
  278. package/examples/starter-cloudflare/app/routes/index.ts +44 -0
  279. package/examples/starter-cloudflare/configs/env.ts +6 -0
  280. package/examples/starter-cloudflare/configs/infra.ts +88 -0
  281. package/examples/starter-cloudflare/configs/tsconfig.json +15 -0
  282. package/examples/starter-cloudflare/configs/vite.ts +4 -0
  283. package/examples/starter-cloudflare/configs/vitest.ts +9 -0
  284. package/examples/starter-cloudflare/docs/index.md +5 -0
  285. package/examples/starter-cloudflare/lib/ui/base.css +17 -0
  286. package/examples/starter-cloudflare/lib/ui/layout.ts +22 -0
  287. package/examples/starter-cloudflare/modules/todos/todos.css +16 -0
  288. package/examples/starter-cloudflare/modules/todos/todos.test.ts +33 -0
  289. package/examples/starter-cloudflare/modules/todos/todos.ts +31 -0
  290. package/examples/starter-cloudflare/modules/todos/views.ts +38 -0
  291. package/examples/starter-cloudflare/package.json +35 -0
  292. package/examples/starter-cloudflare/public/favicon.svg +1 -0
  293. package/examples/starter-cloudflare/tsconfig.json +4 -0
  294. package/examples/svelte/.env.example +2 -0
  295. package/examples/svelte/README.md +18 -0
  296. package/examples/svelte/app/assets/site.css +3 -0
  297. package/examples/svelte/app/entry.ts +28 -0
  298. package/examples/svelte/app/routes/_middleware.ts +4 -0
  299. package/examples/svelte/app/routes/about.ts +10 -0
  300. package/examples/svelte/app/routes/health.ts +7 -0
  301. package/examples/svelte/app/routes/index.ts +12 -0
  302. package/examples/svelte/configs/env.ts +6 -0
  303. package/examples/svelte/configs/infra.ts +88 -0
  304. package/examples/svelte/configs/tsconfig.json +15 -0
  305. package/examples/svelte/configs/vite.ts +9 -0
  306. package/examples/svelte/configs/vitest.ts +9 -0
  307. package/examples/svelte/lib/types/svelte.d.ts +8 -0
  308. package/examples/svelte/lib/ui/base.css +12 -0
  309. package/examples/svelte/lib/ui/layout.ts +18 -0
  310. package/examples/svelte/modules/about/views.ts +8 -0
  311. package/examples/svelte/modules/shop/products.ts +18 -0
  312. package/examples/svelte/modules/shop/shop.css +13 -0
  313. package/examples/svelte/modules/shop/shop.test.ts +28 -0
  314. package/examples/svelte/modules/shop/shop.ts +13 -0
  315. package/examples/svelte/modules/shop/ui/Cart.island.svelte +23 -0
  316. package/examples/svelte/modules/shop/views.ts +16 -0
  317. package/examples/svelte/package.json +35 -0
  318. package/examples/svelte/tsconfig.json +4 -0
  319. package/examples/tailwind/.env.example +2 -0
  320. package/examples/tailwind/README.md +16 -0
  321. package/examples/tailwind/app/assets/site.css +2 -0
  322. package/examples/tailwind/app/entry.ts +28 -0
  323. package/examples/tailwind/app/routes/_middleware.ts +4 -0
  324. package/examples/tailwind/app/routes/health.ts +7 -0
  325. package/examples/tailwind/app/routes/index.ts +30 -0
  326. package/examples/tailwind/configs/Dockerfile +26 -0
  327. package/examples/tailwind/configs/Dockerfile.dockerignore +9 -0
  328. package/examples/tailwind/configs/env.ts +6 -0
  329. package/examples/tailwind/configs/infra.ts +55 -0
  330. package/examples/tailwind/configs/tsconfig.json +15 -0
  331. package/examples/tailwind/configs/vite.ts +7 -0
  332. package/examples/tailwind/configs/vitest.ts +9 -0
  333. package/examples/tailwind/lib/ui/components.ts +21 -0
  334. package/examples/tailwind/lib/ui/layout.ts +21 -0
  335. package/examples/tailwind/lib/ui/theme.css +10 -0
  336. package/examples/tailwind/modules/team/team.test.ts +30 -0
  337. package/examples/tailwind/modules/team/team.ts +34 -0
  338. package/examples/tailwind/modules/team/views.ts +45 -0
  339. package/examples/tailwind/package.json +35 -0
  340. package/examples/tailwind/tsconfig.json +4 -0
  341. package/examples/vue/.env.example +2 -0
  342. package/examples/vue/README.md +18 -0
  343. package/examples/vue/app/assets/site.css +3 -0
  344. package/examples/vue/app/entry.ts +28 -0
  345. package/examples/vue/app/routes/_middleware.ts +4 -0
  346. package/examples/vue/app/routes/about.ts +10 -0
  347. package/examples/vue/app/routes/health.ts +7 -0
  348. package/examples/vue/app/routes/index.ts +12 -0
  349. package/examples/vue/configs/env.ts +6 -0
  350. package/examples/vue/configs/infra.ts +88 -0
  351. package/examples/vue/configs/tsconfig.json +15 -0
  352. package/examples/vue/configs/vite.ts +7 -0
  353. package/examples/vue/configs/vitest.ts +9 -0
  354. package/examples/vue/lib/types/vue.d.ts +8 -0
  355. package/examples/vue/lib/ui/base.css +12 -0
  356. package/examples/vue/lib/ui/layout.ts +18 -0
  357. package/examples/vue/modules/about/views.ts +8 -0
  358. package/examples/vue/modules/shop/products.ts +18 -0
  359. package/examples/vue/modules/shop/shop.css +13 -0
  360. package/examples/vue/modules/shop/shop.test.ts +28 -0
  361. package/examples/vue/modules/shop/shop.ts +13 -0
  362. package/examples/vue/modules/shop/ui/Cart.island.vue +27 -0
  363. package/examples/vue/modules/shop/views.ts +16 -0
  364. package/examples/vue/package.json +35 -0
  365. package/examples/vue/tsconfig.json +4 -0
  366. package/package.json +44 -3
@@ -0,0 +1,57 @@
1
+ ---
2
+ title: configs/
3
+ icon: settings
4
+ ---
5
+
6
+ # configs/
7
+
8
+ The tools' settings, kept out of the app root. Each file is the tool's own format, so what you know about Vite, Vitest and TypeScript applies as is.
9
+
10
+ ```txt
11
+ configs/
12
+ ├── env.ts the variables the app reads, checked at start
13
+ ├── vite.ts Vite, with spacefn's plugin and the target
14
+ ├── vitest.ts Vitest, merging vite.ts
15
+ ├── tsconfig.json TypeScript; the root tsconfig.json extends it
16
+ ├── infra.ts what a deploy creates: a plain Alchemy stack
17
+ ├── Dockerfile the image a Bun deploy builds (Bun only)
18
+ └── Dockerfile.dockerignore what stays out of that image
19
+ ```
20
+
21
+ ## `vite.ts`
22
+
23
+ spacefn is a plugin here, and `target` says where the app runs. Add other plugins beside it:
24
+
25
+ ```ts [configs/vite.ts]
26
+ import tailwindcss from "@tailwindcss/vite";
27
+ import { space } from "spacefn/vite";
28
+ import { defineConfig } from "vite";
29
+
30
+ export default defineConfig({ plugins: [tailwindcss(), space({ target: "cloudflare" })] });
31
+ ```
32
+
33
+ ## `env.ts`
34
+
35
+ The variables the app reads, each with its type. A missing or invalid one stops the app at start, naming it:
36
+
37
+ ```ts [configs/env.ts]
38
+ import { defineEnv, Env } from "spacefn";
39
+
40
+ export default defineEnv({
41
+ SITE_URL: Env.url(),
42
+ STRIPE_KEY: Env.secret(),
43
+ MAX_TODOS: Env.int({ default: 100 }),
44
+ });
45
+ ```
46
+
47
+ Read it in code with `const env = yield* Env` (imported from `#configs/env.ts`). Deploys import this file to know what to pass on, so import only `spacefn` and `effect` in it.
48
+
49
+ ## `infra.ts`
50
+
51
+ The app's infrastructure as a plain [Alchemy](https://alchemy.run) stack: what `space deploy` creates and, on Cloudflare, what `space dev` runs locally. It loops over what `app/` asks for, from `#space/infra.ts`, and is yours to change: add a domain, remove the R2 bucket you don't use.
52
+
53
+ ## `tsconfig.json` and `vitest.ts`
54
+
55
+ `include` lists `app/`, `lib/`, `modules/` and `configs/`; add a folder there if you make another. `vitest.ts` merges `vite.ts`, so tests run with the same plugins, and finds `*.test.ts` in `app/`, `modules/` and `lib/`.
56
+
57
+ Read more in [Configuration](../7-reference/1-config.md).
@@ -0,0 +1,34 @@
1
+ ---
2
+ title: .space/
3
+ icon: wand
4
+ ---
5
+
6
+ # .space/
7
+
8
+ What spacefn generates from `app/`: plain TypeScript you can read, but never edit. `space gen` writes it, `npm install` runs that, and `space dev` rewrites it on every change. It's in `.gitignore`.
9
+
10
+ ```txt
11
+ .space/
12
+ ├── manifest.ts the routes, middleware, queues, crons and databases, as data
13
+ ├── db/
14
+ │ └── main.ts MainDb: the typed queries of app/db/main/
15
+ ├── assets.d.ts the names assets(...) accepts, from app/assets/
16
+ ├── islands.ts island(name, props), from the *.island.* files
17
+ ├── islands/
18
+ │ └── Cart.ts an island's browser entry, starting its component
19
+ ├── entry.ts the target's entry, running app/entry.ts
20
+ ├── infra.ts what configs/infra.ts creates, as plain data
21
+ ├── vite.config.ts points Vite at configs/vite.ts
22
+ └── data/ local databases and blobs under space dev (Bun)
23
+ ```
24
+
25
+ You import four of them:
26
+
27
+ | Import | What it gives |
28
+ | --------------------- | --------------------------------------------- |
29
+ | `#space/manifest.ts` | `manifest`, for `app(...)` and `testApp(...)` |
30
+ | `#space/db/<name>.ts` | the database class, such as `MainDb` |
31
+ | `#space/islands.ts` | `island(name, props)`, for client components |
32
+ | `#space/infra.ts` | `app`, for `configs/infra.ts` |
33
+
34
+ If something in it looks wrong, the cause is in `app/` or `configs/`: fix it there and run `space gen`, which reports errors with the file and a hint. `space clean` deletes it, keeping the local data.
@@ -0,0 +1,35 @@
1
+ ---
2
+ title: .env
3
+ icon: key
4
+ ---
5
+
6
+ # .env
7
+
8
+ Values for the variables in [`configs/env.ts`](6-configs.md#envts), one file per place the app runs:
9
+
10
+ ```txt
11
+ my-app/
12
+ ├── .env.example committed: every variable, with safe example values
13
+ ├── .env your machine: space dev and space db
14
+ ├── .env.staging space deploy --stage staging
15
+ └── .env.prod space deploy (the default stage, prod)
16
+ ```
17
+
18
+ ```sh [.env]
19
+ SITE_URL=http://localhost:3000
20
+ STRIPE_KEY=sk_test_...
21
+ ```
22
+
23
+ A deploy reads only `.env.<stage>`, never `.env`, so local values can't reach production. Variables already set in the environment, as CI sets them, are passed on too, so CI needs no file.
24
+
25
+ Commit `.env.example` only: the scaffolded `.gitignore` keeps every other `.env` file out of git. A new teammate copies it to `.env`.
26
+
27
+ Besides your own, spacefn reads a few:
28
+
29
+ | Variable | What it's for |
30
+ | ---------------------------------------------- | ----------------------------------------------------------------------------------- |
31
+ | `DB_<NAME>_URL`, `DB_<NAME>_AUTH_TOKEN` | a libSQL database: Turso, `sqld`, or a `file:` |
32
+ | `SPACE_STATE_URL`, `SPACE_STATE_AUTH_TOKEN` | the state database on Bun |
33
+ | `OTEL_EXPORTER_OTLP_ENDPOINT`, `_HEADERS` | where traces, logs and metrics go |
34
+ | `PORT`, `HOST`, `SPACE_DATA_DIR`, `SPACE_ROLE` | the Bun server; see [Bun](../5-deployment/2-bun.md) |
35
+ | `SPACE_DEV_PORT` | `space dev --port` on Cloudflare; see [Cloudflare](../5-deployment/1-cloudflare.md) |
@@ -0,0 +1,37 @@
1
+ ---
2
+ title: package.json
3
+ icon: package
4
+ ---
5
+
6
+ # package.json
7
+
8
+ The app's name, scripts, dependencies, and the `#` imports that every tool reads.
9
+
10
+ ```json [package.json]
11
+ {
12
+ "name": "my-app",
13
+ "private": true,
14
+ "type": "module",
15
+ "imports": {
16
+ "#configs/*": "./configs/*",
17
+ "#lib/*": "./lib/*",
18
+ "#modules/*": "./modules/*",
19
+ "#space/*": "./.space/*"
20
+ },
21
+ "scripts": {
22
+ "postinstall": "space gen",
23
+ "dev": "space dev",
24
+ "build": "space build",
25
+ "deploy": "space deploy",
26
+ "docs": "space docs",
27
+ "test": "vitest run --config configs/vitest.ts",
28
+ "typecheck": "tsc --noEmit"
29
+ }
30
+ }
31
+ ```
32
+
33
+ - **`name`** names the Worker, the container and the deploy's resources.
34
+ - **`imports`** are Node's [subpath imports](https://nodejs.org/api/packages.html#subpath-imports): Node, TypeScript, Vite, Vitest and Bun all read them, so nothing else needs configuring. Add one for a folder of your own, such as `"#ui/*": "./src/ui/*"`.
35
+ - **`postinstall`** runs `space gen`, so `.space/` exists after `npm install`, in CI too.
36
+
37
+ The dependencies are `spacefn` and `effect`; the dev dependencies Vite, Vitest, TypeScript, Alchemy and its provider for the target, and `spacefn-docs`, which holds these docs and the examples, for you and your agents to read in `node_modules/spacefn-docs/`. [`space upgrade`](../7-reference/2-cli.md#upgrading) updates spacefn, the docs, Alchemy and what they need newer together.
@@ -0,0 +1,50 @@
1
+ ---
2
+ icon: folders
3
+ ---
4
+
5
+ # Folders
6
+
7
+ A spacefn app is a folder, and where a file sits says what it is. This section has a page for each folder and file of an app: what goes in it, how its files are named, and an example. Browse it like a map of the app.
8
+
9
+ ```txt
10
+ my-app/
11
+ ├── app/ what spacefn reads: wiring only
12
+ │ ├── entry.ts the services, what wraps every request, onError
13
+ │ ├── routes/ pages and HTTP endpoints, by URL
14
+ │ ├── db/ one folder per database: SQL migrations and queries
15
+ │ ├── queues/ one consumer per queue
16
+ │ ├── crons/ one scheduled job per file
17
+ │ ├── assets/ browser entries, bundled by Vite
18
+ │ ├── durable-objects/ Durable Object classes (Cloudflare)
19
+ │ └── workflows/ Workflow classes (Cloudflare)
20
+ ├── modules/ one folder per feature: logic, views, client code, tests
21
+ ├── lib/ what features share: UI kit, helpers, services
22
+ ├── public/ files served as they are at /
23
+ ├── docs/ notes on this app, in the docs reader
24
+ ├── configs/ Vite, Vitest, TypeScript, env and infra settings
25
+ ├── .space/ generated from app/; never edited
26
+ ├── .env local variables; .env.<stage> for deploys
27
+ └── package.json scripts, dependencies and #imports
28
+ ```
29
+
30
+ | Folder or file | What it is |
31
+ | ---------------------------------------------------- | ------------------------------------------------ |
32
+ | [`app/`](1-app/index.md) | What spacefn reads, and nothing else |
33
+ | [`app/entry.ts`](1-app/1-entry.md) | The app: services, `before`, `routes`, `onError` |
34
+ | [`app/routes/`](1-app/2-routes.md) | A file per URL: pages, routes, `_middleware.ts` |
35
+ | [`app/db/`](1-app/3-db.md) | Databases: config, migrations and typed queries |
36
+ | [`app/queues/`](1-app/4-queues.md) | Queue consumers |
37
+ | [`app/crons/`](1-app/5-crons.md) | Scheduled jobs |
38
+ | [`app/assets/`](1-app/6-assets.md) | Scripts and stylesheets for the browser |
39
+ | [`app/durable-objects/`](1-app/7-durable-objects.md) | Durable Objects, on Cloudflare |
40
+ | [`app/workflows/`](1-app/8-workflows.md) | Workflows, on Cloudflare |
41
+ | [`modules/`](2-modules.md) | The app's features |
42
+ | [`lib/`](3-lib.md) | Code the features share |
43
+ | [`public/`](4-public.md) | Static files at fixed URLs |
44
+ | [`docs/`](5-docs.md) | The app's own docs |
45
+ | [`configs/`](6-configs.md) | Tool settings, env and infra |
46
+ | [`.space/`](7-space.md) | Generated code |
47
+ | [`.env`](8-env.md) | Variables for dev and for each deploy stage |
48
+ | [`package.json`](9-package-json.md) | Scripts, dependencies, `#` imports |
49
+
50
+ Only `app/` has rules spacefn checks. `modules/` and `lib/` are the layout the docs, the new app and the examples use, so every kind of code has one place to look; see [Best practices](../3-best-practices.md).
@@ -0,0 +1,70 @@
1
+ ---
2
+ icon: brand-cloudflare
3
+ ---
4
+
5
+ # Cloudflare
6
+
7
+ On Cloudflare, one Worker serves the pages and routes, consumes the queues and runs the crons. The client build is served as static assets in front of it.
8
+
9
+ ```sh
10
+ space deploy
11
+ ```
12
+
13
+ The first deploy asks you to sign in to Cloudflare in the browser. In CI, set `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` instead; see [CI/CD](4-ci-cd.md). To deploy on push from the Cloudflare dashboard, see [Cloudflare dashboard](4-ci-cd.md#cloudflare-dashboard).
14
+
15
+ ## What it creates
16
+
17
+ The scaffolded `configs/infra.ts` creates, for each stage:
18
+
19
+ | From | Resource |
20
+ | ------------------------------ | -------------------------------------------------------------------- |
21
+ | the app | a Worker, with the client build as its assets |
22
+ | `app/db/<name>/` with `d1` | a D1 database, migrated when the Worker starts |
23
+ | `app/db/<name>/` with `libsql` | nothing: it reads `DB_<NAME>_URL` and `DB_<NAME>_AUTH_TOKEN` |
24
+ | `app/queues/<name>.ts` | a queue named `<app>-<stage>-<name>`, and the Worker as its consumer |
25
+ | `app/crons/` | a Cron Trigger per schedule |
26
+ | `app/durable-objects/` | a Durable Object binding per class |
27
+ | `app/workflows/` | a Workflow per class |
28
+ | `Kv`, `Blob` | a KV namespace and an R2 bucket |
29
+ | `Bus`, `RateLimiter` | the Durable Objects behind them |
30
+ | `configs/env.ts` | vars, and Worker secrets for `Env.secret()` fields |
31
+
32
+ Queue names are unique per account, so they carry the app and the stage. Remove what the app doesn't use, such as the R2 bucket, and add what it needs beside the rest.
33
+
34
+ ## A domain
35
+
36
+ Give the Worker a domain in `configs/infra.ts`; the zone must be in the same account:
37
+
38
+ ```ts [configs/infra.ts]
39
+ const worker =
40
+ yield *
41
+ Cloudflare.Website.Vite("Worker", {
42
+ // ...
43
+ domain: stage === "prod" ? "todo.example.com" : `${stage}.todo.example.com`,
44
+ });
45
+ ```
46
+
47
+ ## Locally
48
+
49
+ `space dev` runs the same stack with `alchemy dev`: the Worker in workerd, with local D1, KV, R2, queues, Durable Objects and workflows. No account is needed, and the local state stays on your machine.
50
+
51
+ It serves on port 1337, or the next free one. `space dev --port 3000` sets `SPACE_DEV_PORT`, which `configs/infra.ts` gives to the Worker; that port must be free:
52
+
53
+ ```ts [configs/infra.ts]
54
+ const devPort = process.env.SPACE_DEV_PORT;
55
+ const worker =
56
+ yield *
57
+ Cloudflare.Website.Vite("Worker", {
58
+ // ...
59
+ dev: devPort ? { port: Number(devPort), strictPort: true } : undefined,
60
+ });
61
+ ```
62
+
63
+ An app made with spacefn 0.11.0 or earlier doesn't have these lines yet. Add them to use `--port`; until then `space dev --port` says they're missing.
64
+
65
+ ## Things to know
66
+
67
+ - **D1 has no transactions.** spacefn runs a migration, or other atomic work, as one batch.
68
+ - **KV is eventually consistent**, and keeps a value for at least 60 seconds; shorter TTLs are raised to 60.
69
+ - **State.** Alchemy keeps what each stage deployed in your Cloudflare account (`Cloudflare.state()`), so a deploy from CI and one from your machine see the same thing.
70
+ - **Bindings spacefn doesn't wrap**, such as Workers AI, are added in `configs/infra.ts` and read with `CloudflareEnv` from `spacefn/cloudflare`. `space doctor` names a binding that `app/` needs and the stack doesn't give.
@@ -0,0 +1,68 @@
1
+ ---
2
+ icon: brand-docker
3
+ ---
4
+
5
+ # Bun
6
+
7
+ On Bun, the app is a Docker image built from its source, run as a container with a volume for its data. The scaffolded `configs/infra.ts` builds and runs it in your local Docker; point it at a server to deploy there.
8
+
9
+ ```sh
10
+ space deploy
11
+ ```
12
+
13
+ ## The processes
14
+
15
+ The app runs as three kinds of process: the **web** server, the **queue** consumers and the **crons**. By default the web process starts the other two as children and restarts one that crashes, so a slow or failing job never blocks or takes down a request. `SIGTERM` stops all three, and a queue process stopped mid-batch hands its messages back.
16
+
17
+ ```mermaid
18
+ flowchart LR
19
+ web["web: pages and routes"] --> queues["queues: app/queues/"]
20
+ web --> crons["crons: app/crons/"]
21
+ web --- state[("state database")]
22
+ queues --- state
23
+ crons --- state
24
+ ```
25
+
26
+ They share a libSQL **state database** behind `Kv`, `Queue`, `Bus` and `RateLimiter`: a file in the data folder by default.
27
+
28
+ ## The image
29
+
30
+ `configs/Dockerfile` installs the dependencies, runs `vite build` and keeps only `dist/`. Bun's downloads go in a [cache mount](https://docs.docker.com/build/cache/optimize/#use-cache-mounts), so a rebuild only downloads what changed, and the image doesn't carry them; that needs BuildKit, Docker's default builder since 23. `configs/Dockerfile.dockerignore` keeps local files, such as `.env` and `.space/data`, out of it. The container gets a volume on `/data`, for file databases, the state database and blobs, and restarts unless stopped.
31
+
32
+ ## Variables
33
+
34
+ | Variable | Default | What it does |
35
+ | ----------------- | ------------------------------------ | ----------------------------------------------------------------- |
36
+ | `PORT`, `HOST` | `3000`, all | Where the web server listens |
37
+ | `SPACE_DATA_DIR` | `.space/data` (`/data` in the image) | Local databases, the state database, blobs |
38
+ | `SPACE_STATE_URL` | a file in the data dir | The state database behind Kv, Queue, Bus and RateLimiter (libSQL) |
39
+ | `DB_<NAME>_URL` | a file in the data dir | A libSQL database: `libsql://`, `https://` or `file:` |
40
+ | `SPACE_ROLE` | unset: web, starting the others | `web`, `queues` or `crons`: run one part per process |
41
+
42
+ ## On a server
43
+
44
+ Give the image, the volume and the container a Docker context that reaches the server over SSH:
45
+
46
+ ```ts [configs/infra.ts]
47
+ const context = yield * Docker.Context("Host", { docker: "host=ssh://deploy@server.example.com" });
48
+ const image = yield * Docker.Image("Image", { context /* ... */ });
49
+ const data = yield * Docker.Volume("Data", { context });
50
+ yield * Docker.Container("App", { context /* ... */ });
51
+ ```
52
+
53
+ Put a reverse proxy, such as Caddy, in front of it for HTTPS.
54
+
55
+ The stack keeps its deploy state in `.alchemy/`, on the machine that deployed. To deploy from CI or from more than one machine, keep it in a shared store instead, such as `Cloudflare.state()` from `@alchemy.run/cloudflare`.
56
+
57
+ ## More than one machine
58
+
59
+ Point `SPACE_STATE_URL` and the databases at a shared libSQL server (Turso or `sqld`), then run several `SPACE_ROLE=web` and `SPACE_ROLE=queues` processes, and exactly one `SPACE_ROLE=crons`. `Blob` is a local folder for now, so it needs a shared volume.
60
+
61
+ ## Without Docker
62
+
63
+ ```sh
64
+ space build
65
+ bun dist/server/index.js
66
+ ```
67
+
68
+ runs the same thing, with the data in `.space/data` unless `SPACE_DATA_DIR` says otherwise.
@@ -0,0 +1,67 @@
1
+ ---
2
+ icon: building-factory-2
3
+ ---
4
+
5
+ # Infrastructure
6
+
7
+ `configs/infra.ts` is what a deploy creates: a plain [Alchemy](https://alchemy.run) stack, scaffolded with the app and yours to change. It's exactly what `alchemy deploy` would run, so Alchemy's docs cover everything in it. spacefn adds two things.
8
+
9
+ ## `#space/infra.ts`
10
+
11
+ Generated from `app/` like the manifest, it holds what the file conventions ask for, as plain data:
12
+
13
+ | Field | From |
14
+ | -------------------- | ------------------------------------------ |
15
+ | `app.name` | `package.json`'s `name` |
16
+ | `app.databases` | `app/db/*/`, with their driver and binding |
17
+ | `app.queues` | `app/queues/*.ts` |
18
+ | `app.crons` | the schedules in `app/crons/*.ts` |
19
+ | `app.durableObjects` | `app/durable-objects/*.ts` |
20
+ | `app.workflows` | `app/workflows/*.ts` |
21
+ | `app.folders` | the app's code folders, for rebuilds |
22
+
23
+ The stack loops over these lists, so a new database folder or queue file gets its resource on the next deploy. It imports no app code.
24
+
25
+ ## `variables(...)`
26
+
27
+ From `spacefn/infra`, it reads values from the environment for the deploy to pass on:
28
+
29
+ ```ts [configs/infra.ts]
30
+ import { variables } from "spacefn/infra";
31
+
32
+ import env from "#configs/env.ts";
33
+
34
+ const bindings = {
35
+ ...variables(env), // configs/env.ts's fields; Env.secret() ones as secrets
36
+ ...variables({ OTEL_EXPORTER_OTLP_ENDPOINT: "plain", OTEL_EXPORTER_OTLP_HEADERS: "secret" }),
37
+ };
38
+ ```
39
+
40
+ Secrets become Worker secrets on Cloudflare. A variable that isn't set is left out.
41
+
42
+ ## Changing it
43
+
44
+ Everything else is written out: the KV namespace, the R2 bucket, the Durable Objects behind `Bus` and `RateLimiter`, the Worker or the container. Remove what you don't use and add what you need beside it, such as a domain or Workers AI:
45
+
46
+ ```ts [configs/infra.ts]
47
+ const worker =
48
+ yield *
49
+ Cloudflare.Website.Vite("Worker", {
50
+ // ...
51
+ domain: "todo.example.com",
52
+ env: { ...bindings, AI: yield * Cloudflare.Ai("AI") },
53
+ });
54
+ ```
55
+
56
+ `space doctor` names any binding the conventions need that `configs/infra.ts` doesn't give, and a Worker missing one says which when it's used.
57
+
58
+ ## State
59
+
60
+ Alchemy records what each stage deployed, so the next deploy changes only what changed.
61
+
62
+ | Target | Where the state is |
63
+ | ---------- | ----------------------------------------------------------------------------------- |
64
+ | Cloudflare | in your account, with `Cloudflare.state()`; `space dev` uses `Alchemy.localState()` |
65
+ | Bun | `Alchemy.localState()`, in `.alchemy/` at the app root |
66
+
67
+ `.alchemy/` is in `.gitignore`. Deploy a Bun stage from one machine, or move its state to a shared store.
@@ -0,0 +1,179 @@
1
+ ---
2
+ title: CI/CD
3
+ icon: cloud-upload
4
+ ---
5
+
6
+ # CI/CD
7
+
8
+ A deploy from CI is the same command as from your machine, without the questions:
9
+
10
+ ```sh
11
+ npm ci # also runs space gen
12
+ npm test
13
+ npx space deploy --stage prod --yes
14
+ ```
15
+
16
+ `--yes` approves Alchemy's plan without asking. The app's variables come from the CI's environment, so no `.env.<stage>` file is needed: set each field of `configs/env.ts` as a CI variable, its secrets as CI secrets.
17
+
18
+ ## Cloudflare credentials
19
+
20
+ On your machine, the first deploy signs you in through the browser. CI can't, so give it an API token:
21
+
22
+ 1. In the Cloudflare dashboard, **My Profile → API Tokens → Create Token**, start from the **Edit Cloudflare Workers** template.
23
+ 2. Keep what the template has, and add:
24
+
25
+ | Permission | For |
26
+ | --------------------------------- | ------------------------------------------------------ |
27
+ | Account → **Secrets Store: Edit** | every app: the key to Alchemy's deploy state |
28
+ | Account → **D1: Edit** | D1 databases, as the scaffolded app has |
29
+ | Account → **Queues: Edit** | `app/queues/` |
30
+ | Zone → **Zone: Read** | a [domain](1-cloudflare.md#a-domain), to find its zone |
31
+
32
+ Secrets Store needs **Edit** even to read the key: Alchemy reads it through a temporary Worker bound to it.
33
+
34
+ 3. Under **Account Resources** pick the account, and under **Zone Resources** its zones.
35
+ 4. Store the token as `CLOUDFLARE_API_TOKEN` in the CI's secrets, and your account's ID (on the **Workers & Pages** overview) as `CLOUDFLARE_ACCOUNT_ID`.
36
+
37
+ Alchemy keeps the deploy state in the account too, so CI and your machine see the same deploys and either can deploy next.
38
+
39
+ ## Cloudflare dashboard
40
+
41
+ [Workers Builds](https://developers.cloudflare.com/workers/ci-cd/builds/) deploys on every push to a branch, from a repository you link in the dashboard. The app needs no Wrangler file: you replace the default `npx wrangler deploy` with `space deploy`.
42
+
43
+ 1. Deploy once from your machine, with the production values in `.env.prod`, so the Worker exists:
44
+
45
+ ```sh
46
+ npx space deploy --stage prod
47
+ ```
48
+
49
+ 2. In **Workers & Pages**, open that Worker, named like `<app>-worker-prod-<id>`, then **Settings → Builds → Connect**, and pick the repository. Don't use **Create application**: Alchemy names the Worker itself, so you'd get a second, unused one.
50
+
51
+ 3. Set the build:
52
+
53
+ | Setting | Value |
54
+ | ------------------ | -------------------------------------------------------------------------------------------------------------- |
55
+ | **Git branch** | `main` |
56
+ | **Build command** | `npm test`, or empty: the deploy builds the app |
57
+ | **Deploy command** | `npx space deploy --stage prod --yes` |
58
+ | **Preview builds** | off: their default, `wrangler preview`, needs a Wrangler file |
59
+ | **Root directory** | the app's folder, if it isn't the repository's root |
60
+ | **API token** | the token from [Cloudflare credentials](#cloudflare-credentials), not a generated one, which lacks permissions |
61
+
62
+ 4. Under **Build variables and secrets**, add:
63
+
64
+ - `CLOUDFLARE_ACCOUNT_ID`, and `CLOUDFLARE_API_TOKEN` as a secret, with the same token;
65
+ - what `.env.prod` has, as it isn't committed: the fields of `configs/env.ts`, and any `DB_<NAME>_*` and `OTEL_*` variables, with secrets as secrets.
66
+
67
+ 5. Push to `main`. The build installs the dependencies, which runs `space gen`, then runs the two commands.
68
+
69
+ > [!WARNING]
70
+ > Change the app's variables in **Build variables and secrets**, then deploy again. A deploy doesn't read the Worker's own **Variables and Secrets**, and replaces the plain variables set there.
71
+
72
+ For another stage, such as `staging`, do the same with that stage's Worker, its branch and `--stage staging`. For a stage per pull request, use [GitHub Actions](#a-stage-per-pull-request): Workers Builds has no step to destroy a stage when the pull request closes.
73
+
74
+ Workers Builds has its own default versions of Node and the package managers. If installing fails there but works on your machine, pin yours with `packageManager` in `package.json` and a `.node-version` file.
75
+
76
+ ## GitHub
77
+
78
+ Deploy `main` to `prod` after the tests pass:
79
+
80
+ ```yaml [.github/workflows/deploy.yml]
81
+ name: Deploy
82
+
83
+ on:
84
+ push:
85
+ branches: [main]
86
+
87
+ concurrency: deploy-prod
88
+
89
+ jobs:
90
+ deploy:
91
+ runs-on: ubuntu-latest
92
+ steps:
93
+ - uses: actions/checkout@v4
94
+ - uses: actions/setup-node@v4
95
+ with:
96
+ node-version: 22
97
+ cache: npm
98
+ - run: npm ci
99
+ - run: npm test
100
+ - run: npx space deploy --stage prod --yes
101
+ env:
102
+ CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
103
+ CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
104
+ # configs/env.ts's fields:
105
+ SITE_URL: ${{ vars.SITE_URL }}
106
+ STRIPE_KEY: ${{ secrets.STRIPE_KEY }}
107
+ ```
108
+
109
+ `concurrency` keeps two deploys of the same stage from running at once.
110
+
111
+ ### A stage per pull request
112
+
113
+ Each pull request gets its own copy of the app, and loses it when it closes:
114
+
115
+ ```yaml [.github/workflows/preview.yml]
116
+ name: Preview
117
+
118
+ on:
119
+ pull_request:
120
+ types: [opened, synchronize, reopened, closed]
121
+
122
+ concurrency: preview-${{ github.event.number }}
123
+
124
+ jobs:
125
+ preview:
126
+ runs-on: ubuntu-latest
127
+ env:
128
+ CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
129
+ CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
130
+ SITE_URL: https://pr-${{ github.event.number }}.example.com
131
+ steps:
132
+ - uses: actions/checkout@v4
133
+ - uses: actions/setup-node@v4
134
+ with:
135
+ node-version: 22
136
+ cache: npm
137
+ - run: npm ci
138
+ - if: github.event.action != 'closed'
139
+ run: npx space deploy --stage pr-${{ github.event.number }} --yes
140
+ - if: github.event.action == 'closed'
141
+ run: npx space destroy --stage pr-${{ github.event.number }} --yes
142
+ ```
143
+
144
+ ## GitLab
145
+
146
+ ```yaml [.gitlab-ci.yml]
147
+ default:
148
+ image: node:22
149
+ cache:
150
+ paths: [.npm/]
151
+ before_script:
152
+ - npm ci --cache .npm --prefer-offline
153
+
154
+ stages: [test, deploy]
155
+
156
+ test:
157
+ stage: test
158
+ script:
159
+ - npm test
160
+
161
+ deploy:
162
+ stage: deploy
163
+ resource_group: prod
164
+ script:
165
+ - npx space deploy --stage prod --yes
166
+ rules:
167
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
168
+ ```
169
+
170
+ Set `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID` and the app's variables in **Settings → CI/CD → Variables**, masked and protected for the secrets. `resource_group` keeps two deploys of the stage from running at once.
171
+
172
+ ## A Bun app from CI
173
+
174
+ A Bun deploy builds a Docker image and runs it, so CI needs Docker and a way to reach the server:
175
+
176
+ - Give the stack a Docker context over SSH to the server, as in [Bun](2-bun.md#on-a-server), and give CI the SSH key.
177
+ - Move the deploy state off the runner, which is thrown away after each job: use a shared store such as `Cloudflare.state()` in place of `Alchemy.localState()` in `configs/infra.ts`.
178
+
179
+ Then the same `npx space deploy --stage prod --yes` runs from the job.
@@ -0,0 +1,48 @@
1
+ ---
2
+ icon: rocket
3
+ ---
4
+
5
+ # Deployment
6
+
7
+ One command deploys the app, to the target in `configs/vite.ts`:
8
+
9
+ ```sh
10
+ space deploy # stage prod
11
+ space deploy --stage staging # another copy, with its own resources
12
+ space destroy --stage staging # delete that copy, its data included
13
+ ```
14
+
15
+ `space deploy` generates `.space/` for production and runs `alchemy deploy configs/infra.ts --stage <stage>`. [Alchemy](https://alchemy.run) creates or updates what the stack declares and shows you the plan to approve; `--yes` skips the question, for CI.
16
+
17
+ ```mermaid
18
+ flowchart LR
19
+ app["app/"] -->|space gen --prod| space[".space/"]
20
+ space --> infra["configs/infra.ts"]
21
+ env[".env.stage"] --> infra
22
+ infra -->|alchemy deploy| target["Worker, or container"]
23
+ ```
24
+
25
+ ## Stages
26
+
27
+ A stage is a separate copy of the app: its own Worker or container, databases, queues and state. `prod` is the default. Use one per environment (`staging`, `prod`) or per pull request (`pr-42`), and `space destroy` the ones you're done with.
28
+
29
+ Each stage reads its variables from `.env.<stage>` and from the environment, never from `.env`. See [`.env`](../4-folders/8-env.md).
30
+
31
+ ## Where it runs
32
+
33
+ | Target | What a deploy creates |
34
+ | ----------------------------- | ------------------------------------------------------------------------------------ |
35
+ | [Cloudflare](1-cloudflare.md) | A Worker with D1, KV, R2, Queues, Durable Objects and Cron Triggers, in your account |
36
+ | [Bun](2-bun.md) | A Docker image of the app, and a container running it with a volume for its data |
37
+
38
+ What the stack creates, and how to change it, is in [Infrastructure](3-infrastructure.md). Deploying from GitHub, GitLab or Cloudflare's own builds is in [CI/CD](4-ci-cd.md).
39
+
40
+ ## Telemetry
41
+
42
+ Traces, logs and metrics go over OTLP when `OTEL_EXPORTER_OTLP_ENDPOINT` is set (with `OTEL_EXPORTER_OTLP_HEADERS` for the key), to any OpenTelemetry backend. Requests and queries are traced already; add spans with `Effect.withSpan`. The service name is the app's name unless `OTEL_SERVICE_NAME` says otherwise. `telemetry(manifest.name)` in `app/entry.ts` turns it on.
43
+
44
+ ## Before the first deploy
45
+
46
+ - `space doctor` checks the tools the target needs, the config, and that `configs/infra.ts` gives every binding `app/` asks for.
47
+ - Create `.env.prod` with the production values, or set them in CI.
48
+ - On Cloudflare, enable R2 on the account, or remove the bucket from `configs/infra.ts`.