spacefn-docs 0.0.0-stage → 0.11.0

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 +34 -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 +56 -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 +131 -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 +27 -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 +85 -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 +85 -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 +85 -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 +32 -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 +85 -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 +85 -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,178 @@
1
+ ---
2
+ icon: database
3
+ ---
4
+
5
+ # Database
6
+
7
+ Each folder in `app/db/` is a SQLite database: `app/db/main/` is `main`. You write the schema and the queries in SQL; `space gen` turns them into a typed service.
8
+
9
+ ```txt
10
+ app/db/main/
11
+ ├── config.json
12
+ ├── migrations/
13
+ │ ├── 0001_todos.sql
14
+ │ └── 0002_due_dates.sql
15
+ └── queries/
16
+ ├── list-todos.sql
17
+ └── add-todo.sql
18
+ ```
19
+
20
+ ## `config.json`
21
+
22
+ Each database says how it's reached and when it migrates:
23
+
24
+ ```json [app/db/main/config.json]
25
+ {
26
+ "$schema": "../../../node_modules/spacefn/schemas/db.json",
27
+ "driver": "d1",
28
+ "migrateOn": "startup"
29
+ }
30
+ ```
31
+
32
+ - `driver`: `d1`, `durable-object` or `libsql`; see [Drivers](#drivers). A driver the target doesn't have stops `space gen`.
33
+ - `migrateOn`: `startup` applies pending migrations as the app starts. `call` never migrates by itself: your code calls `MainDb.migrate()`, or you run `space db migrate`.
34
+ - `open` (optional): `startup`, the default, has `databases(manifest)` in `app/entry.ts` open the database once. `manual` leaves it to your code, for a database per tenant; see [Databases the app opens](#databases-the-app-opens).
35
+
36
+ The file is required, so each database's settings are written down, not guessed from the target. `$schema` gives completion and checks in the editor.
37
+
38
+ ## Migrations
39
+
40
+ `NNNN_name.sql`, run in number order. Each has an `-- up` section and, optionally, a `-- down` section that undoes it:
41
+
42
+ ```sql
43
+ -- up
44
+ CREATE TABLE todos (
45
+ id INTEGER PRIMARY KEY,
46
+ title TEXT NOT NULL,
47
+ done INTEGER NOT NULL DEFAULT 0
48
+ );
49
+
50
+ -- down
51
+ DROP TABLE todos;
52
+ ```
53
+
54
+ A migration runs all at once or not at all, so don't write `BEGIN` or `COMMIT`. Applied migrations are recorded with a checksum in a `space_migrations` table, and a migration edited after it ran is refused, so add a new one instead. Files starting with `_` are drafts and are skipped.
55
+
56
+ With `"migrateOn": "startup"`, a database migrates when the app starts, on every target. To migrate at a time you choose instead, set `"call"` and run them yourself: with `space db migrate` for a libSQL database (below), or from your own code, such as a route behind admin middleware:
57
+
58
+ ```ts [app/routes/admin/migrate.ts]
59
+ import { route } from "spacefn";
60
+
61
+ import MainDb from "#space/db/main.ts";
62
+
63
+ // POST /admin/migrate, guarded by app/routes/admin/_middleware.ts. Answers the ids it applied.
64
+ export default route({ POST: MainDb.migrate() });
65
+ ```
66
+
67
+ ## Queries
68
+
69
+ One query per file. The file's name is the function's: `find-todo.sql` (or `find_todo.sql`, or `findTodo.sql`) is `findTodo`. What it returns comes from the statement:
70
+
71
+ | Statement | Returns |
72
+ | ------------------------------------------------------------ | -------------------- |
73
+ | `SELECT`, `VALUES`, a `WITH` that only reads, or `RETURNING` | `ReadonlyArray<Row>` |
74
+ | anything else: `INSERT`, `UPDATE`, `DELETE`, ... | nothing |
75
+ | any statement, with a `-- :one` line | `Option<Row>` |
76
+
77
+ `-- :many` and `-- :exec` set the other two the same way, when the statement says otherwise.
78
+
79
+ ```sql [app/db/main/queries/find-todo.sql]
80
+ -- :one
81
+ -- @param id number
82
+ SELECT id, title, done FROM todos WHERE id = :id;
83
+ ```
84
+
85
+ - **Parameters** are `:name`. Declare their type with `-- @param name type`, or they're `unknown`.
86
+ - **Columns** are typed from the schema. An expression (`count(*) AS n`) needs `-- @column n number`, and a `0`/`1` column becomes a boolean with `-- @column done boolean`.
87
+ - **Types:** `string`, `number`, `boolean`, `bytes` (`Uint8Array`) and `unknown`; add `?` for nullable (`string?`).
88
+ - **Optional filters:** lines between `-- case` and `-- end` are included only when their `-- when` parameters are given, so one query serves a search form:
89
+
90
+ ```sql [app/db/main/queries/search-todos.sql]
91
+ -- @param done boolean
92
+ -- @param q string
93
+ SELECT id, title, done FROM todos WHERE 1 = 1
94
+ -- case
95
+ -- when done
96
+ AND done = :done
97
+ -- when q
98
+ AND title LIKE '%' || :q || '%'
99
+ -- end
100
+ ORDER BY id;
101
+ ```
102
+
103
+ A folder in `queries/` groups its queries under its name, as deep as you like:
104
+
105
+ ```txt
106
+ app/db/main/queries/
107
+ ├── list-todos.sql MainDb.listTodos()
108
+ └── todos/
109
+ ├── mark-done.sql MainDb.todos.markDone({ id })
110
+ └── stats/
111
+ └── count-done.sql MainDb.todos.stats.countDone()
112
+ ```
113
+
114
+ A query and a folder can't share a name (`todos.sql` beside `todos/`). Files and folders starting with `_` are drafts and skipped.
115
+
116
+ `space gen` checks each query against the migrations and reports a wrong column or table with its file. The VS Code extension shows the same as you type.
117
+
118
+ ## Using a database
119
+
120
+ Import the generated class and call its queries on it:
121
+
122
+ ```ts
123
+ import MainDb from "#space/db/main.ts";
124
+
125
+ const todos = yield * MainDb.listTodos();
126
+ yield * MainDb.addTodo({ title: "Ship" });
127
+ ```
128
+
129
+ `yield* MainDb` gives every query at once, as a service to pass around. Queries fail with Effect's `SqlError`, which says why (a constraint, for example), so you can handle it. A row that doesn't match the generated types is a defect. For SQL that doesn't fit a query file, get Effect's `SqlClient` with `` sql`...` `` templates; the VS Code extension checks those too.
130
+
131
+ ## Drivers
132
+
133
+ Every driver is SQLite, so the same SQL runs everywhere. Each database names its own in `config.json`, so one app can mix them: `main` on D1 and `rooms` inside Durable Objects, say.
134
+
135
+ | Driver | Target | Where the data is |
136
+ | ---------------- | ---------- | --------------------------------------------------------------------------------------------- |
137
+ | `d1` | Cloudflare | A D1 database, created on deploy. |
138
+ | `durable-object` | Cloudflare | Inside each Durable Object: `MainDb.layer(durableObjectSql(ctx.storage))` in its constructor. |
139
+ | `libsql` | both | `DB_<NAME>_URL` (and `DB_<NAME>_AUTH_TOKEN`): Turso, `sqld`, or a `file:`. |
140
+
141
+ On Bun, a libSQL database without a URL is a local file, `.space/data/<name>.db` (or `$SPACE_DATA_DIR/<name>.db`), in WAL mode so the web, queue and cron processes share it. D1 has no transactions, so spacefn runs atomic work there as one batch.
142
+
143
+ ## Databases the app opens
144
+
145
+ Some apps have many databases of one shape, such as one per customer. Write the shape once as a folder in `app/db/`, with `"open": "manual"`:
146
+
147
+ ```json [app/db/shop/config.json]
148
+ {
149
+ "driver": "libsql",
150
+ "migrateOn": "startup",
151
+ "open": "manual"
152
+ }
153
+ ```
154
+
155
+ `space gen` types `ShopDb`'s queries as usual, but `databases(manifest)` doesn't open it, a deploy creates nothing for it, and `space db` skips it unless `--db shop` names it. Open each database yourself with `ShopDb.layer(connection)`, which applies the migrations when it builds, and provide it where it's used:
156
+
157
+ ```ts
158
+ import { libsql } from "spacefn/libsql";
159
+
160
+ const acme = ShopDb.layer(libsql({ url: "libsql://shop-acme.turso.io", authToken }));
161
+ yield * ShopDb.listProducts().pipe(Effect.provide(acme));
162
+ ```
163
+
164
+ `libsql` from `spacefn/libsql` talks to libSQL over HTTP (Turso, `sqld`, `turso dev`) with the fetch-only client, so it runs on both targets, in Workers and Durable Objects too. A local `file:` database needs the native client, `libsqlDatabase` from `spacefn/bun`.
165
+
166
+ To keep one connection per tenant across requests, an Effect `LayerMap` from the tenant's key to its layer opens each on first use and closes it when idle, and a `_middleware.ts` provides the request's: `examples/mini-shopify` does this, creating each shop's database with Turso's Platform API.
167
+
168
+ ## `space db`
169
+
170
+ For libSQL databases:
171
+
172
+ ```sh
173
+ space db status # applied, pending, and edited migrations
174
+ space db migrate # apply what's pending
175
+ space db rollback --steps 2 --db main
176
+ ```
177
+
178
+ It reads `.env`, like the app. D1 and Durable Object databases migrate when the Worker starts.
@@ -0,0 +1,125 @@
1
+ ---
2
+ icon: server
3
+ ---
4
+
5
+ # Services
6
+
7
+ spacefn gives every app five services. Call them through their class, `yield* Kv.get(key)`, the same way on every target; what backs them depends on where the app runs. `yield* Kv` gives the whole service, to pass around.
8
+
9
+ | Service | What it's for | Cloudflare | Bun |
10
+ | ------------- | --------------------------------------- | -------------------------- | ------------------------------- |
11
+ | `Kv` | strings by key, with an optional expiry | Workers KV | the state database |
12
+ | `Blob` | files and uploads | R2 | a folder, `.space/data/blob` |
13
+ | `Queue` | background jobs | Cloudflare Queues | the state database |
14
+ | `Bus` | change notices to live pages | a Durable Object per topic | the state database, plus memory |
15
+ | `RateLimiter` | counting hits per key | a Durable Object per key | the state database |
16
+
17
+ On Cloudflare, `configs/infra.ts` creates the KV namespace and the R2 bucket behind `Kv` and `Blob` (R2 must be enabled on the account); remove the one the app doesn't use.
18
+
19
+ On Bun, the web server, the queue consumers and the crons run in separate processes, so these services keep their data in a shared libSQL **state database**: `.space/data/state.db` locally, or `SPACE_STATE_URL` (and `SPACE_STATE_AUTH_TOKEN`) for a remote one. See [Deploying](../5-deployment/2-bun.md).
20
+
21
+ ## Kv
22
+
23
+ ```ts
24
+ yield * Kv.set("greeting", "hi", { ttl: "10 minutes" });
25
+ const greeting = yield * Kv.get("greeting"); // Option<string>
26
+ yield * Kv.delete("greeting");
27
+ ```
28
+
29
+ Workers KV is eventually consistent and keeps a value for at least 60 seconds, so shorter TTLs are raised to 60 there. Don't use it for counters; that's what `RateLimiter` is for.
30
+
31
+ ## Blob
32
+
33
+ ```ts
34
+ // An `Upload` from Input.body is a File.
35
+ const bytes = new Uint8Array(yield * Effect.promise(() => upload.arrayBuffer()));
36
+ yield * Blob.put(`avatars/${userId}.png`, bytes, { contentType: upload.type });
37
+ const avatar = yield * Blob.get(`avatars/${userId}.png`); // Option<{ body, size, contentType, uploadedAt }>
38
+ const keys = yield * Blob.list({ prefix: "avatars/", limit: 100 });
39
+ yield * Blob.delete(`avatars/${userId}.png`);
40
+ ```
41
+
42
+ ## Queue
43
+
44
+ ```ts
45
+ yield * Queue.send("emails", { to: "ada@example.com" }, { delay: "5 minutes" });
46
+ ```
47
+
48
+ The queue is named after its consumer file, `app/queues/emails.ts`; sending to a queue without one is an error. Bodies must survive structured cloning. See [Queues and crons](7-jobs.md).
49
+
50
+ ## Bus
51
+
52
+ ```ts
53
+ yield * Bus.publish("todos", "changed");
54
+ ```
55
+
56
+ Every subscriber to the topic gets the message; nothing is stored, so only those subscribed right now see it. Pages subscribe through `Datastar.watch` (see [Pages](3-pages.md)). On Bun, subscribers in the same process get it at once and those in other processes within about a quarter of a second.
57
+
58
+ ## RateLimiter
59
+
60
+ Use it through `rateLimit`, which fails with `TooManyRequests` (a 429 with `Retry-After`) past the limit:
61
+
62
+ ```ts
63
+ yield * rateLimit(`sign-in:${email}`, { limit: 5, window: "15 minutes" });
64
+ yield * rateLimit(`sign-in:${yield * clientAddress}`, { limit: 20, window: "15 minutes" });
65
+ ```
66
+
67
+ Counts are fixed windows, and every process and instance agrees on them. `clientAddress` is Cloudflare's `cf-connecting-ip`, else the connection's address; trust it only behind a proxy that sets or strips that header.
68
+
69
+ ## Your own services
70
+
71
+ A service of your own is an Effect `Context.Service` with a layer, in `lib/` when every feature can use it, or in its feature's `modules/` folder. Here a mailer, over the `HttpClient` that `platform(manifest)` gives:
72
+
73
+ ```ts [lib/mailer.ts]
74
+ import { Context, Effect, Layer } from "effect";
75
+ import { HttpClient, HttpClientRequest } from "effect/http";
76
+
77
+ import Env from "#configs/env.ts";
78
+
79
+ export class Mailer extends Context.Service<
80
+ Mailer,
81
+ { readonly send: (to: string, subject: string) => Effect.Effect<void, unknown> }
82
+ >()("app/Mailer") {
83
+ static readonly layer = Layer.effect(
84
+ Mailer,
85
+ Effect.gen(function* () {
86
+ const env = yield* Env;
87
+ const http = yield* HttpClient.HttpClient;
88
+ return {
89
+ send: (to, subject) =>
90
+ HttpClientRequest.post("https://api.mail.example/send").pipe(
91
+ HttpClientRequest.bearerToken(env.MAIL_TOKEN),
92
+ HttpClientRequest.bodyJsonUnsafe({ to, subject }),
93
+ http.execute,
94
+ Effect.asVoid,
95
+ ),
96
+ };
97
+ }),
98
+ );
99
+
100
+ static readonly send = (to: string, subject: string) =>
101
+ Mailer.use((mailer) => mailer.send(to, subject));
102
+ }
103
+ ```
104
+
105
+ The static `send` lets code call `Mailer.send(to, subject)`, as spacefn's own services are called. In a test, provide `Layer.succeed(Mailer)({ send: ... })` instead.
106
+
107
+ List the layer in the entry's `services`, after spacefn's. It can use the env, the databases and the services above, and everything in the app can use it:
108
+
109
+ ```ts [app/entry.ts]
110
+ import { Mailer } from "#lib/mailer.ts";
111
+
112
+ export default app(manifest, {
113
+ services: [
114
+ platform(manifest),
115
+ Env.layer,
116
+ databases(manifest),
117
+ telemetry(manifest.name),
118
+ Mailer.layer,
119
+ ],
120
+ });
121
+ ```
122
+
123
+ See [The entry](1-entry.md).
124
+
125
+ On Cloudflare, `CloudflareEnv` from `spacefn/cloudflare` gives bindings spacefn doesn't wrap, such as your Durable Objects (`DO_CHAT_ROOM` for `app/durable-objects/chat-room.ts`) or ones you add in `configs/infra.ts`.
@@ -0,0 +1,61 @@
1
+ ---
2
+ icon: clock-play
3
+ ---
4
+
5
+ # Queues and crons
6
+
7
+ ## Queues
8
+
9
+ A file in `app/queues/` consumes the queue of its name. Its body is decoded with a schema before your handler sees it:
10
+
11
+ ```ts [modules/emails/emails.ts]
12
+ import { Schema } from "effect";
13
+ import { Queue } from "spacefn";
14
+
15
+ import { Mailer } from "#lib/mailer.ts";
16
+
17
+ /** What the `emails` queue carries. */
18
+ export const Email = Schema.Struct({ to: Schema.String, subject: Schema.String });
19
+
20
+ /** Sends it later: puts it on the queue. */
21
+ export const later = (email: typeof Email.Type) => Queue.send("emails", email);
22
+
23
+ /** Sends it now: the queue's consumer. */
24
+ export const send = ({ to, subject }: typeof Email.Type) => Mailer.send(to, subject);
25
+ ```
26
+
27
+ ```ts [app/queues/emails.ts]
28
+ import { queue } from "spacefn";
29
+
30
+ import * as Emails from "#modules/emails/emails.ts";
31
+
32
+ export default queue({ body: Emails.Email, handler: Emails.send, retryDelay: "30 seconds" });
33
+ ```
34
+
35
+ Send to it from anywhere with `Emails.later({ to, subject })`, which calls `Queue.send("emails", ...)`. The handler also gets the message as a second argument, `(body, message)`.
36
+
37
+ - Each message is acknowledged once its handler succeeds and retried when it fails, so one bad message doesn't redeliver the batch. A body that doesn't decode is retried too.
38
+ - After 3 retries a message is dropped; on Bun with an error in the log, on Cloudflare as the consumer's `settings` in `configs/infra.ts` say (`maxRetries`, `deadLetterQueue`).
39
+ - `message.attempts` is 1 on the first delivery; `message.id` identifies it in logs.
40
+ - `concurrency` (default 1, in order) is how many messages of a batch run at once; `retryDelay` is the wait before a retry.
41
+ - Delivery is at least once, so make handlers safe to run twice.
42
+
43
+ On Cloudflare it's a Cloudflare Queue and a consumer, which `configs/infra.ts` creates for each file. On Bun the queue is a table in the state database, consumed by the queue process; a message whose process died is delivered again about a minute later.
44
+
45
+ ## Crons
46
+
47
+ A file in `app/crons/` runs a job on a schedule:
48
+
49
+ ```ts [app/crons/nightly.ts]
50
+ import { cron } from "spacefn";
51
+
52
+ import * as Sessions from "#modules/accounts/sessions.ts";
53
+
54
+ export default cron("0 3 * * *", Sessions.deleteExpired);
55
+ ```
56
+
57
+ The schedule is five fields in UTC: minute, hour, day of month, month, day of week. Lists (`1,15`), ranges (`9-17`), steps (`*/5`) and names (`MON-FRI`, `JAN`) work; when both day fields are set, a day matching either runs the job, as in cron.
58
+
59
+ Write the schedule as a string literal: the infra reads it from the file without running it. Jobs on the same schedule run at once, and one failing doesn't stop the others; a failure is logged.
60
+
61
+ On Cloudflare these are Cron Triggers on the Worker. On Bun the cron process runs them at the start of each matching minute; run only one cron process, or each job runs once per process.
@@ -0,0 +1,111 @@
1
+ ---
2
+ icon: lock
3
+ ---
4
+
5
+ # Auth
6
+
7
+ spacefn gives building blocks, not a user system: your users and sessions live in your own tables, and you decide the flows. All of it runs on Workers and Bun alike.
8
+
9
+ ## Passwords
10
+
11
+ ```ts
12
+ const hash = yield * Password.hash(password); // fails with WeakPassword under 12 characters
13
+ const { valid, needsRehash } = yield * Password.verify(password, user.passwordHash);
14
+ ```
15
+
16
+ PBKDF2-SHA256 at 100,000 iterations, the most Workers allow. That is below OWASP's advice, so rate-limit sign-in (below). The stored hash records its parameters, so they can change later without breaking old hashes; `needsRehash` says when to store a new one. Both take a `pepper`, a secret from your env mixed in so a stolen database alone can't be brute-forced.
17
+
18
+ ## Sessions
19
+
20
+ `sessionAuth` gives cookie sessions over your own sessions table. Only a hash of each token is stored, so a leaked table signs nobody in.
21
+
22
+ ```ts [modules/accounts/sessions.ts]
23
+ import { sessionAuth } from "spacefn";
24
+
25
+ import MainDb from "#space/db/main.ts";
26
+
27
+ export const auth = sessionAuth({
28
+ lookup: (tokenHash) => MainDb.findSession({ tokenHash }),
29
+ touch: (tokenHash, lastSeenAt) => MainDb.touchSession({ tokenHash, lastSeenAt }),
30
+ policy: { absolute: "30 days", idle: "7 days" },
31
+ });
32
+ ```
33
+
34
+ `lookup` returns `Option<{ user, expiresAt, lastSeenAt }>`. Then:
35
+
36
+ - `auth.user`: the signed-in user as an `Option`, looked up once per request.
37
+ - `auth.requireUser`: the user, or a `401`.
38
+ - `auth.create`: a new session. Store its `tokenHash` and `expiresAt`, then answer with `auth.signIn(response, session.token)`.
39
+ - `auth.signOut(response)`: clears the cookie. Delete the row too.
40
+
41
+ The cookie is HttpOnly, Secure and SameSite=Lax, named `session` unless you set `cookie`. Pass the name to `csrf({ cookie: "session" })` too. Set `secure: false` only for plain-http local dev.
42
+
43
+ ## Rate limiting
44
+
45
+ ```ts
46
+ yield * rateLimit(`sign-in:${email}`, { limit: 5, window: "15 minutes" });
47
+ yield * rateLimit(`sign-in:${yield * clientAddress}`, { limit: 20, window: "15 minutes" });
48
+ ```
49
+
50
+ Past the limit it fails with `TooManyRequests`, a `429` with `Retry-After`. Limit by what you protect: the account and the address. See [Services](6-services.md).
51
+
52
+ ## Two-factor codes (TOTP)
53
+
54
+ ```ts
55
+ const secret = Totp.newSecret(); // store it as a secret
56
+ const qr = Totp.uri({ secret, issuer: "Todo", account: user.email }); // show as a QR code
57
+ const check = yield * Totp.verify(code, secret, { afterStep: user.lastTotpStep }); // { valid, step }
58
+ ```
59
+
60
+ Codes from authenticator apps (RFC 6238). `verify` accepts a step either side for clock drift and refuses steps at or before `afterStep`, so store the `step` it returns and a code can't be used twice.
61
+
62
+ ## Signed tokens
63
+
64
+ For links in emails: verification, password reset, invites.
65
+
66
+ ```ts
67
+ const token =
68
+ yield * SignedToken.sign({ purpose: "reset", subject: user.id }, env.TOKEN_SECRET, "1 hour");
69
+ const claims = yield * SignedToken.verify(token, env.TOKEN_SECRET, "reset"); // fails with InvalidToken
70
+ ```
71
+
72
+ HMAC-signed, with a purpose, an expiry and a unique `jti` you can record to make a link single-use.
73
+
74
+ ## Sign in with Google, GitHub or Facebook
75
+
76
+ ```ts [modules/accounts/google.ts]
77
+ import { Effect } from "effect";
78
+ import { OAuth, redirect } from "spacefn";
79
+
80
+ import Env from "#configs/env.ts";
81
+
82
+ import { auth } from "./sessions.ts";
83
+
84
+ const google = Effect.map(Env, (env) =>
85
+ OAuth.google({
86
+ clientId: env.GOOGLE_CLIENT_ID,
87
+ clientSecret: env.GOOGLE_CLIENT_SECRET,
88
+ redirectUri: `${env.ORIGIN}/auth/google`,
89
+ }),
90
+ );
91
+
92
+ /** Sends the browser to Google, or, on its way back, signs the user in. */
93
+ export const signIn = Effect.gen(function* () {
94
+ const provider = yield* google;
95
+ if (!(yield* provider.isCallback)) return yield* provider.start;
96
+ const profile = yield* provider.finish; // { provider, id, email, emailVerified, name, avatarUrl }
97
+ // find or create the user by profile.provider + profile.id, then:
98
+ const session = yield* auth.create;
99
+ return provider.clear(auth.signIn(redirect("/"), session.token));
100
+ });
101
+ ```
102
+
103
+ ```ts [app/routes/auth/google.ts]
104
+ import { route } from "spacefn";
105
+
106
+ import { signIn } from "#modules/accounts/google.ts";
107
+
108
+ export default route({ GET: signIn });
109
+ ```
110
+
111
+ The code flow with PKCE and a state cookie, so a callback only completes a sign-in this browser started. `OAuth.github` and `OAuth.facebook` work the same, and `oauthProvider(spec, client)` builds others. Match existing accounts by email only when `emailVerified` is true; Facebook never says so.
@@ -0,0 +1,70 @@
1
+ ---
2
+ icon: test-pipe
3
+ ---
4
+
5
+ # Testing
6
+
7
+ Tests sit next to the code they test, as `*.test.ts`: a feature's in its `modules/<feature>/` folder, shared code's in `lib/`. `npm test` runs every one in `app/`, `modules/` and `lib/` with Vitest, through `configs/vitest.ts`, which merges `configs/vite.ts` so the spacefn plugin runs too. They run in Node, in memory: no Worker, no Docker, no database server.
8
+
9
+ `spacefn/testing` has what you need:
10
+
11
+ | Helper | What it gives |
12
+ | ----------------------------- | --------------------------------------------------------------------------------- |
13
+ | `testApp(manifest, services)` | Serves the app's pages, routes and middleware in memory; `fetch` it like a server |
14
+ | `form(fields)` | A form post for `fetch`, as a browser sends one |
15
+ | `testDb(MainDb)` | A fresh in-memory SQLite database with every migration applied |
16
+ | `memoryServices` | `Kv`, `Blob`, `Queue`, `Bus` and `RateLimiter` in memory |
17
+ | `testEnv(values)` | Values for `configs/env.ts` |
18
+ | `QueueInbox` | What was sent to `Queue.memory`, to assert on |
19
+
20
+ ## A feature through its pages
21
+
22
+ Test a feature as a browser uses it: through the pages and routes that wire it up.
23
+
24
+ ```ts [modules/todos/todos.test.ts]
25
+ import { Layer } from "effect";
26
+ import { form, memoryServices, testApp, testDb, testEnv } from "spacefn/testing";
27
+ import { expect, it } from "vitest";
28
+
29
+ import Env from "#configs/env.ts";
30
+ import MainDb from "#space/db/main.ts";
31
+ import { manifest } from "#space/manifest.ts";
32
+
33
+ it("adds a todo", async () => {
34
+ await using app = testApp(
35
+ manifest,
36
+ Layer.mergeAll(testDb(MainDb), memoryServices, Env.layer.pipe(Layer.provide(testEnv({})))),
37
+ );
38
+ const response = await app.fetch("/?__action=add", form({ title: "Ship" }));
39
+ expect(response.status).toBe(303);
40
+ expect(await (await app.fetch("/")).text()).toContain("Ship");
41
+ });
42
+ ```
43
+
44
+ `testApp` takes the generated manifest, so every page, route and `_middleware.ts` is served as in the app; pass `{ routes: [...] }` instead to serve only some. The services are what the entry's `services` would give, in memory. Each `testApp` builds them once, so a fresh one gives a fresh database, and `await using` releases them at the end of the test.
45
+
46
+ ## A feature's code directly
47
+
48
+ The functions in `modules/` are Effects, so a test can run them without HTTP: provide the layers they use. `it.effect` comes from `@effect/vitest` (add it to your dev dependencies):
49
+
50
+ ```ts [modules/todos/todos.test.ts]
51
+ import { it } from "@effect/vitest";
52
+ import { Effect, Layer } from "effect";
53
+ import { memoryServices, testDb } from "spacefn/testing";
54
+ import { expect } from "vitest";
55
+
56
+ import MainDb from "#space/db/main.ts";
57
+
58
+ import * as Todos from "./todos.ts";
59
+
60
+ it.effect("adds a todo, and lists it", () =>
61
+ Effect.gen(function* () {
62
+ yield* Todos.add({ title: "Ship" });
63
+ expect((yield* Todos.list).map((todo) => todo.title)).toEqual(["Ship"]);
64
+ }).pipe(Effect.provide(Layer.mergeAll(testDb(MainDb), memoryServices))),
65
+ );
66
+ ```
67
+
68
+ `memoryServices` is there because `Todos.add` publishes on the `Bus`.
69
+
70
+ Time-based code (TTLs, rate-limit windows, cron schedules) follows Effect's `Clock`, so `TestClock.adjust("2 minutes")` moves it.
@@ -0,0 +1,21 @@
1
+ ---
2
+ icon: compass
3
+ ---
4
+
5
+ # Guides
6
+
7
+ How to build each part of an app, with the code in `modules/` and `lib/` and the `app/` files that wire it. Read them in order the first time; each stands alone after that.
8
+
9
+ | Guide | What it covers |
10
+ | ------------------------------------ | --------------------------------------------------------------------- |
11
+ | [The entry](1-entry.md) | `app/entry.ts`: services, middleware, extra routes, `onError` |
12
+ | [Routes and middleware](2-routes.md) | HTTP endpoints, reading input, errors, middleware, CSRF |
13
+ | [Pages](3-pages.md) | Server-rendered pages, form actions, live updates with Datastar |
14
+ | [Frontend](4-frontend.md) | Asset entries, `public/`, CSS, framework islands, Datastar components |
15
+ | [Database](5-database.md) | Migrations, typed SQL queries, drivers, a database per tenant |
16
+ | [Services](6-services.md) | Kv, Blob, Queue, Bus and RateLimiter, and what backs them per target |
17
+ | [Queues and crons](7-jobs.md) | Background jobs and scheduled jobs |
18
+ | [Auth](8-auth.md) | Passwords, sessions, rate limiting, TOTP, signed tokens, OAuth |
19
+ | [Testing](9-testing.md) | Testing modules, pages and routes in memory |
20
+
21
+ Each guide's code is taken from an app in `examples/`, which ships with these docs in `node_modules/spacefn-docs/examples/`.
@@ -0,0 +1,67 @@
1
+ ---
2
+ icon: adjustments
3
+ ---
4
+
5
+ # Configuration
6
+
7
+ Everything you configure is in `configs/`, including `configs/env.ts`, the variables the app reads.
8
+
9
+ The files there are the tools' own, so what you know about Vite, Vitest and TypeScript applies as is. spacefn adds a plugin, not a config format of its own.
10
+
11
+ ## `configs/vite.ts`
12
+
13
+ The app's Vite config. spacefn is a plugin in it, and its `target` says where the app runs:
14
+
15
+ ```ts [configs/vite.ts]
16
+ import { space } from "spacefn/vite";
17
+ import { defineConfig } from "vite";
18
+
19
+ export default defineConfig({ plugins: [space({ target: "cloudflare" })] }); // or "bun"
20
+ ```
21
+
22
+ When Vite starts (`space dev`, `space build`, `npm test`), the plugin writes `.space/` from `app/`, then serves and builds the app for its target. Add your own plugins and options beside it, as in any Vite project. For Tailwind:
23
+
24
+ ```ts [configs/vite.ts]
25
+ import tailwind from "@tailwindcss/vite";
26
+ import { space } from "spacefn/vite";
27
+ import { defineConfig } from "vite";
28
+
29
+ export default defineConfig({ plugins: [space({ target: "cloudflare" }), tailwind()] });
30
+ ```
31
+
32
+ `configs/vitest.ts` merges it, so tests run with the same plugins. The app's name, for the Worker, the container and the deploy, is `package.json`'s `name`.
33
+
34
+ Imports such as `#lib/...` are declared in `package.json`; see [Conventions](../2-conventions.md#imports). Each database's driver is in its own `app/db/<name>/config.json`; see [Database](../6-guides/5-database.md#configjson).
35
+
36
+ ## `configs/env.ts`
37
+
38
+ The variables the app reads, checked when it starts:
39
+
40
+ ```ts
41
+ import { defineEnv, Env } from "spacefn";
42
+
43
+ export default defineEnv({
44
+ GREETING: Env.string({ default: "Hello" }),
45
+ MAX_TODOS: Env.int({ default: 100 }),
46
+ DEBUG: Env.boolean({ optional: true }),
47
+ SITE_URL: Env.url(),
48
+ STRIPE_KEY: Env.secret(),
49
+ });
50
+ ```
51
+
52
+ Read it as a service: `const env = yield* Env` (the default export) gives typed values. A secret is `Redacted`, so it never shows up in logs; `Redacted.value(env.STRIPE_KEY)` reads it. `Env.schema(schema)` takes any Effect Schema that decodes from a string. A missing or invalid variable stops the app at start with an error naming it.
53
+
54
+ Deploys import `configs/env.ts` to know which variables to pass on, so import only `spacefn` and `effect` there.
55
+
56
+ ## `.env` files
57
+
58
+ | File | Read by |
59
+ | -------------- | ---------------------------------------------------- |
60
+ | `.env` | `space dev` and `space db` |
61
+ | `.env.<stage>` | `space deploy --stage <stage>` (default `.env.prod`) |
62
+
63
+ A deploy never reads `.env`, so local values can't reach production. Variables already in the environment, as CI sets them, are passed on too. `configs/infra.ts` passes on what it lists: the scaffolded one passes the fields of `configs/env.ts` (secrets as Worker secrets on Cloudflare), the `DB_<NAME>_URL` and `_AUTH_TOKEN` of libSQL databases, and `OTEL_EXPORTER_OTLP_ENDPOINT` and `_HEADERS`. Commit `.env.example`, never `.env`.
64
+
65
+ ## `configs/infra.ts`
66
+
67
+ A plain Alchemy stack: what `space deploy` and, on Cloudflare, `space dev` run. It loops over `#space/infra.ts` for the resources the file conventions need and passes the variables on with `variables(...)`. See [Deploying](../5-deployment/3-infrastructure.md).
@@ -0,0 +1,27 @@
1
+ ---
2
+ icon: terminal-2
3
+ ---
4
+
5
+ # CLI
6
+
7
+ `space` comes with `spacefn`. Run it with `npx space <command>`, or through the app's scripts (`npm run dev`).
8
+
9
+ | Command | What it does |
10
+ | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
11
+ | `space dev [--port N]` | Runs the app locally and regenerates `.space/` on every change. Cloudflare: workerd through Alchemy. Bun: Vite inside Bun, with queues and crons in the same process. |
12
+ | `space build` | `vite build` with `configs/vite.ts`, into `dist/` (Bun). Cloudflare builds during `deploy`. |
13
+ | `space deploy [--stage S] [--yes]` | `alchemy deploy configs/infra.ts` for stage `S` (default `prod`). `--yes` skips the approval. |
14
+ | `space destroy [--stage S] [--yes]` | `alchemy destroy configs/infra.ts`: deletes everything stage `S` deployed, its data included. |
15
+ | `space gen [--watch] [--prod]` | Writes `.space/` from `app/` and `configs/`. `--prod` takes `.prod.ts` files instead of `.dev.ts`. |
16
+ | `space db status\|migrate\|rollback [--db name] [--steps N]` | Migrations of libSQL databases. See [Database](../6-guides/5-database.md). |
17
+ | `space doctor` | Checks Node, the config, `.space/`, the target's tools, the bindings in `configs/infra.ts` and `configs/env.ts`, and says what to fix. |
18
+ | `space upgrade` | Updates spacefn, its Alchemy provider and `spacefn-docs`, then regenerates. |
19
+ | `space docs [--port N]` | Serves your `docs/` and spacefn's docs at `http://localhost:4321/`. `space dev` serves them too, at `/__space/docs/`. See [Writing docs](3-writing-docs.md). |
20
+ | `space clean` | Deletes generated files and builds. Keeps local data. |
21
+
22
+ Every command prints errors with a code, the file and a hint, for example:
23
+
24
+ ```txt
25
+ [CRON_SCHEDULE_LITERAL] app/crons/nightly.ts: The schedule must be a string literal
26
+ hint: Write it in the file: export default cron("0 3 * * *", job). The infra reads it without running the file.
27
+ ```