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,324 @@
1
+ // The spacefn docs reader in the browser: theme, navigation, code tabs, search,
2
+ // Mermaid, and a reload when a docs file changes.
3
+ const d = document;
4
+ const root = d.documentElement;
5
+ const config = JSON.parse(d.getElementById("docs-config")?.textContent ?? "{}");
6
+ const base = config.base ?? "/";
7
+
8
+ const store = {
9
+ get: (key) => {
10
+ try {
11
+ return localStorage.getItem(key);
12
+ } catch {
13
+ return null;
14
+ }
15
+ },
16
+ set: (key, value) => {
17
+ try {
18
+ localStorage.setItem(key, value);
19
+ } catch {
20
+ // Private windows can refuse storage; the reader works without it.
21
+ }
22
+ },
23
+ };
24
+
25
+ // Theme
26
+ const themeChanged = new Set();
27
+ d.querySelector(".theme-toggle")?.addEventListener("click", () => {
28
+ const dark = root.classList.toggle("dark");
29
+ store.set("spacefn-docs-theme", dark ? "dark" : "light");
30
+ for (const listener of themeChanged) listener();
31
+ });
32
+
33
+ // Sidebar folders: remember which ones you opened or closed (see NAV_BOOT in layout.ts).
34
+ for (const folder of d.querySelectorAll("#sidebar details[data-nav]"))
35
+ folder.addEventListener("toggle", () => {
36
+ let saved = {};
37
+ try {
38
+ saved = JSON.parse(store.get("spacefn-docs-nav") ?? "{}");
39
+ } catch {
40
+ // A bad value starts over.
41
+ }
42
+ saved[folder.dataset.nav] = folder.open;
43
+ store.set("spacefn-docs-nav", JSON.stringify(saved));
44
+ });
45
+
46
+ // Navigation on narrow screens
47
+ const menu = d.querySelector(".menu-btn");
48
+ menu?.addEventListener("click", () => {
49
+ menu.setAttribute("aria-expanded", String(d.body.classList.toggle("nav-open")));
50
+ });
51
+ d.addEventListener("click", (event) => {
52
+ if (d.body.classList.contains("nav-open") && !event.target.closest(".sidebar,.menu-btn"))
53
+ d.body.classList.remove("nav-open");
54
+ });
55
+ const sidebar = d.querySelector(".sidebar");
56
+ const current = sidebar?.querySelector("a.active");
57
+ if (sidebar && current) sidebar.scrollTop = current.offsetTop - sidebar.clientHeight / 2;
58
+
59
+ // Copy buttons
60
+ for (const block of d.querySelectorAll(".prose .code-block")) {
61
+ const pre = block.querySelector("pre");
62
+ if (!pre) continue;
63
+ const button = d.createElement("button");
64
+ button.type = "button";
65
+ button.className = "copy-btn";
66
+ button.textContent = "Copy";
67
+ button.addEventListener("click", () => {
68
+ const text = [...pre.querySelectorAll(".line")]
69
+ .filter((line) => !line.classList.contains("remove"))
70
+ .map((line) => line.textContent)
71
+ .join("\n");
72
+ void navigator.clipboard.writeText(text || pre.innerText).then(() => {
73
+ button.textContent = "Copied";
74
+ button.classList.add("copied");
75
+ setTimeout(() => {
76
+ button.textContent = "Copy";
77
+ button.classList.remove("copied");
78
+ }, 1500);
79
+ });
80
+ });
81
+ block.append(button);
82
+ }
83
+
84
+ // Code groups: choosing a tab chooses it in every group with one of that name, and is remembered.
85
+ const TABS = "spacefn-docs-tabs";
86
+ const chosen = new Set(JSON.parse(store.get(TABS) ?? "[]"));
87
+ const selectTab = (group, label) => {
88
+ const tabs = [...group.querySelectorAll('[role="tab"]')];
89
+ const index = tabs.findIndex((tab) => tab.dataset.label === label);
90
+ if (index === -1) return false;
91
+ const panels = group.querySelectorAll('[role="tabpanel"]');
92
+ tabs.forEach((tab, i) => {
93
+ tab.setAttribute("aria-selected", String(i === index));
94
+ panels[i]?.toggleAttribute("hidden", i !== index);
95
+ });
96
+ return true;
97
+ };
98
+ const groups = [...d.querySelectorAll(".code-group")];
99
+ for (const group of groups) {
100
+ for (const label of chosen) if (selectTab(group, label)) break;
101
+ group.querySelector(".code-tabs")?.addEventListener("click", (event) => {
102
+ const tab = event.target.closest('[role="tab"]');
103
+ if (!tab) return;
104
+ const label = tab.dataset.label;
105
+ const top = tab.getBoundingClientRect().top;
106
+ for (const other of groups) selectTab(other, label);
107
+ // Keep the clicked tab where it was, though groups above it changed height.
108
+ window.scrollBy(0, tab.getBoundingClientRect().top - top);
109
+ for (const other of group.querySelectorAll('[role="tab"]')) chosen.delete(other.dataset.label);
110
+ chosen.add(label);
111
+ store.set(TABS, JSON.stringify([...chosen].slice(-12)));
112
+ });
113
+ }
114
+
115
+ // "On this page" follows the scroll
116
+ const links = [...d.querySelectorAll(".toc a")];
117
+ if (links.length > 0 && "IntersectionObserver" in window) {
118
+ const visible = new Set();
119
+ const observer = new IntersectionObserver(
120
+ (entries) => {
121
+ for (const entry of entries)
122
+ if (entry.isIntersecting) visible.add(entry.target.id);
123
+ else visible.delete(entry.target.id);
124
+ const first = links.find((link) => visible.has(decodeURIComponent(link.hash.slice(1))));
125
+ if (first) for (const link of links) link.classList.toggle("active", link === first);
126
+ },
127
+ { rootMargin: "-64px 0px -60% 0px" },
128
+ );
129
+ for (const link of links) {
130
+ const heading = d.getElementById(decodeURIComponent(link.hash.slice(1)));
131
+ if (heading) observer.observe(heading);
132
+ }
133
+ }
134
+
135
+ // "Edit this page" opens the file in your editor without leaving the page.
136
+ d.querySelector(`.edit-link[href^="${base}_/open"]`)?.addEventListener("click", (event) => {
137
+ event.preventDefault();
138
+ void fetch(event.currentTarget.href);
139
+ });
140
+
141
+ // Search
142
+ const dialog = d.querySelector(".search-dialog");
143
+ const input = dialog?.querySelector("input");
144
+ const list = dialog?.querySelector(".search-results");
145
+ let pages;
146
+ let selected = 0;
147
+
148
+ const escapeHtml = (text) =>
149
+ text.replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
150
+ const highlight = (text, query) => {
151
+ const i = text.toLowerCase().indexOf(query);
152
+ if (i < 0) return escapeHtml(text);
153
+ return `${escapeHtml(text.slice(0, i))}<mark>${escapeHtml(text.slice(i, i + query.length))}</mark>${escapeHtml(text.slice(i + query.length))}`;
154
+ };
155
+ const score = (text, query) => {
156
+ const i = text.toLowerCase().indexOf(query);
157
+ if (i < 0) return 0;
158
+ if (i === 0) return 3;
159
+ return /[a-z0-9]/i.test(text[i - 1]) ? 1 : 2;
160
+ };
161
+ const snippet = (text, query) => {
162
+ const i = text.toLowerCase().indexOf(query);
163
+ const start = Math.max(0, i - 40);
164
+ return (start > 0 ? "…" : "") + text.slice(start, i + query.length + 80);
165
+ };
166
+
167
+ const search = (raw) => {
168
+ const query = raw.trim().toLowerCase();
169
+ const results = [];
170
+ for (const page of pages ?? []) {
171
+ const where = [page.source, page.group].filter(Boolean).join(" › ");
172
+ if (!query) {
173
+ results.push({
174
+ rank: 0,
175
+ href: page.href,
176
+ title: escapeHtml(page.title),
177
+ meta: escapeHtml(where),
178
+ });
179
+ continue;
180
+ }
181
+ const inTitle = score(page.title, query);
182
+ if (inTitle)
183
+ results.push({
184
+ rank: 20 + inTitle,
185
+ href: page.href,
186
+ title: highlight(page.title, query),
187
+ meta: escapeHtml(where),
188
+ });
189
+ for (const section of page.sections) {
190
+ const href = section.id ? `${page.href}#${section.id}` : page.href;
191
+ const title = section.heading ?? page.title;
192
+ const inHeading = section.heading ? score(section.heading, query) : 0;
193
+ if (inHeading) {
194
+ results.push({
195
+ rank: 10 + inHeading,
196
+ href,
197
+ title: highlight(title, query),
198
+ meta: escapeHtml(`${page.title} · ${where}`),
199
+ });
200
+ continue;
201
+ }
202
+ if (section.text.toLowerCase().includes(query))
203
+ results.push({
204
+ rank: score(section.text, query),
205
+ href,
206
+ title: escapeHtml(title),
207
+ meta: escapeHtml(page.title),
208
+ snippet: highlight(snippet(section.text, query), query),
209
+ });
210
+ }
211
+ }
212
+ return results.sort((a, b) => b.rank - a.rank).slice(0, 50);
213
+ };
214
+
215
+ const render = () => {
216
+ if (!pages) {
217
+ list.innerHTML = '<li class="search-empty">Loading…</li>';
218
+ return;
219
+ }
220
+ const results = search(input.value);
221
+ selected = 0;
222
+ list.innerHTML = results.length
223
+ ? results
224
+ .map(
225
+ (result, i) =>
226
+ `<li><a href="${result.href}" aria-selected="${i === 0}"><span class="r-title">${result.title}</span>${result.snippet ? `<span class="r-snippet">${result.snippet}</span>` : ""}${result.meta ? `<span class="r-meta">${result.meta}</span>` : ""}</a></li>`,
227
+ )
228
+ .join("")
229
+ : `<li class="search-empty">No results for “${escapeHtml(input.value)}”</li>`;
230
+ };
231
+
232
+ const move = (by) => {
233
+ const anchors = list.querySelectorAll("a");
234
+ if (anchors.length === 0) return;
235
+ anchors[selected].setAttribute("aria-selected", "false");
236
+ selected = (selected + by + anchors.length) % anchors.length;
237
+ anchors[selected].setAttribute("aria-selected", "true");
238
+ anchors[selected].scrollIntoView({ block: "nearest" });
239
+ };
240
+
241
+ const open = () => {
242
+ input.value = "";
243
+ render();
244
+ dialog.showModal();
245
+ input.focus();
246
+ if (!pages)
247
+ void fetch(`${base}_/search.json`)
248
+ .then((response) => response.json())
249
+ .then((index) => {
250
+ pages = index;
251
+ render();
252
+ });
253
+ };
254
+
255
+ if (dialog && input && list) {
256
+ d.querySelector(".topbar-search")?.addEventListener("click", open);
257
+ d.addEventListener("keydown", (event) => {
258
+ const typing = /INPUT|TEXTAREA|SELECT/.test(d.activeElement?.tagName ?? "");
259
+ if (
260
+ ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "k") ||
261
+ (event.key === "/" && !typing)
262
+ ) {
263
+ event.preventDefault();
264
+ if (dialog.open) dialog.close();
265
+ else open();
266
+ }
267
+ });
268
+ input.addEventListener("input", render);
269
+ input.addEventListener("keydown", (event) => {
270
+ if (event.key === "ArrowDown") {
271
+ event.preventDefault();
272
+ move(1);
273
+ } else if (event.key === "ArrowUp") {
274
+ event.preventDefault();
275
+ move(-1);
276
+ } else if (event.key === "Enter") {
277
+ const anchor = list.querySelectorAll("a")[selected];
278
+ if (anchor) {
279
+ dialog.close();
280
+ location.href = anchor.href;
281
+ }
282
+ }
283
+ });
284
+ dialog.addEventListener("click", (event) => {
285
+ if (event.target === dialog || event.target.closest("a")) dialog.close();
286
+ });
287
+ }
288
+
289
+ // Mermaid, from a CDN: offline, the diagram's source shows instead.
290
+ if (config.mermaid) {
291
+ const blocks = [...d.querySelectorAll("pre.mermaid")];
292
+ const sources = blocks.map((block) => block.textContent);
293
+ import(config.mermaid)
294
+ .then(({ default: mermaid }) => {
295
+ // Diagrams set in the code font, like the source they're drawn from, a size below the text.
296
+ const fontFamily = getComputedStyle(root).getPropertyValue("--mono").trim();
297
+ const fontSize = 13;
298
+ const draw = () => {
299
+ blocks.forEach((block, i) => {
300
+ block.removeAttribute("data-processed");
301
+ block.textContent = sources[i];
302
+ });
303
+ mermaid.initialize({
304
+ startOnLoad: false,
305
+ theme: root.classList.contains("dark") ? "dark" : "default",
306
+ fontFamily,
307
+ fontSize,
308
+ themeVariables: { fontFamily, fontSize: `${fontSize}px` },
309
+ });
310
+ return mermaid.run({ nodes: blocks });
311
+ };
312
+ themeChanged.add(() => void draw());
313
+ return draw();
314
+ })
315
+ .catch((error) => console.warn("space docs: Mermaid didn't load", error));
316
+ }
317
+
318
+ // Reload when a docs file changes.
319
+ if ("EventSource" in window) {
320
+ const events = new EventSource(`${base}_/events`);
321
+ events.onmessage = (event) => {
322
+ if (event.data === "reload") location.reload();
323
+ };
324
+ }
@@ -0,0 +1,107 @@
1
+ ---
2
+ icon: flag
3
+ ---
4
+
5
+ # Getting started
6
+
7
+ ## Create an app
8
+
9
+ ```sh
10
+ npm create spacefn@latest my-app
11
+ ```
12
+
13
+ It asks where the app runs: **Cloudflare** (Workers, D1, KV, R2, Queues, Durable Objects) or **Bun** (one Docker container, with local SQLite files or a remote libSQL database). Pass `--target cloudflare` or `--target bun` to skip the question. You can change it later: it's the `target` in `configs/vite.ts`.
14
+
15
+ ```sh
16
+ cd my-app
17
+ cp .env.example .env
18
+ npm install # also runs `space gen`
19
+ npm run dev
20
+ ```
21
+
22
+ The new app is a small todo list: one page with a form, a SQLite table, and a list that updates live in every open tab. Open the URL `npm run dev` prints.
23
+
24
+ You need Node 22 or later. A Bun app also needs [Bun](https://bun.sh), and Docker to deploy. If something doesn't start, run `npx space doctor`: it checks all of this and says what to install.
25
+
26
+ ## What's in it
27
+
28
+ `app/` holds what spacefn reads, and its files only connect the code in `modules/` and `lib/`:
29
+
30
+ ```txt
31
+ my-app/
32
+ ├── app/
33
+ │ ├── entry.ts what runs with the rest: services, middleware, onError
34
+ │ ├── routes/
35
+ │ │ ├── index.ts the page at /: the todos module's actions and views, wired up
36
+ │ │ ├── health.ts GET /health
37
+ │ │ └── _middleware.ts refuses cross-site form posts, on every request
38
+ │ ├── db/
39
+ │ │ └── main/
40
+ │ │ ├── migrations/ the schema, in SQL
41
+ │ │ └── queries/ one SQL query per file, typed for you
42
+ │ └── assets/
43
+ │ └── site.css the stylesheet entry, loaded by assets("site")
44
+ ├── modules/
45
+ │ └── todos/
46
+ │ ├── todos.ts what the app does with todos: list, add, toggle
47
+ │ ├── views.ts the todos' HTML, from plain props
48
+ │ ├── todos.css their styles, imported by app/assets/site.css
49
+ │ └── todos.test.ts the feature tested through the page, in memory
50
+ ├── lib/
51
+ │ └── ui/
52
+ │ ├── layout.ts the HTML around every page
53
+ │ └── base.css the design tokens and base styles
54
+ ├── public/
55
+ │ └── favicon.svg served as it is, at /favicon.svg
56
+ ├── configs/
57
+ │ ├── env.ts the variables the app reads
58
+ │ ├── infra.ts what a deploy creates: a plain Alchemy stack
59
+ │ ├── vite.ts the Vite config, with spacefn's plugin and the target
60
+ │ ├── vitest.ts
61
+ │ ├── tsconfig.json
62
+ │ └── Dockerfile the image a Bun deploy builds (Bun only)
63
+ └── .space/ generated; don't edit or commit it
64
+ ```
65
+
66
+ Add a file to `app/routes/` and it is a page or a route; add one to `app/db/main/queries/` and `MainDb.yourQuery()` exists. `npm run dev` regenerates `.space/` as you go. See [Conventions](2-conventions.md).
67
+
68
+ ## Change something
69
+
70
+ Add a query, `app/db/main/queries/clear-done.sql`. Its file name makes it `clearDone`:
71
+
72
+ ```sql
73
+ DELETE FROM todos WHERE done = 1;
74
+ ```
75
+
76
+ Then what it means for the feature, in `modules/todos/todos.ts`:
77
+
78
+ ```ts
79
+ /** Deletes the done todos, and tells every open page. */
80
+ export const clearDone = MainDb.clearDone().pipe(Effect.andThen(Bus.publish(TOPIC, "changed")));
81
+ ```
82
+
83
+ Wire it to the page as an action, in `app/routes/index.ts`:
84
+
85
+ ```ts
86
+ clearDone: action({
87
+ input: Schema.Struct({}),
88
+ handler: () => Effect.as(Todos.clearDone, redirect("/")),
89
+ }),
90
+ ```
91
+
92
+ and give the view a button that posts to it: pass `clearDone: ctx.actions.clearDone.url` to `todosPage`, and in `modules/todos/views.ts`:
93
+
94
+ ```ts
95
+ html`<form method="post" action="${props.clearDone}"><button>Clear done</button></form>`;
96
+ ```
97
+
98
+ The editor knows `clearDone` exists because `space gen` typed it from the SQL.
99
+
100
+ ## Test and deploy
101
+
102
+ ```sh
103
+ npm test # every *.test.ts in app/, modules/ and lib/
104
+ npm run deploy # stage `prod`
105
+ ```
106
+
107
+ `deploy` runs `configs/infra.ts`, a plain Alchemy stack. On Cloudflare it creates the D1 database, the queues and the rest in your account; Alchemy asks you to sign in the first time. On Bun it builds an image with `configs/Dockerfile` and runs it in Docker. See [Deploying](5-deployment/index.md).
@@ -0,0 +1,138 @@
1
+ ---
2
+ icon: list-tree
3
+ ---
4
+
5
+ # Conventions
6
+
7
+ An app is a folder. spacefn reads it (without running your code) and writes the wiring into `.space/`: `space gen` does it once, `space dev` on every change.
8
+
9
+ ```txt
10
+ my-app/
11
+ ├── app/
12
+ │ ├── entry.ts what runs with the rest → The entry
13
+ │ ├── routes/ pages and HTTP endpoints → Pages, Routes
14
+ │ ├── db/<name>/ migrations/ and queries/ → Database
15
+ │ ├── queues/ one consumer per file → Queues and crons
16
+ │ ├── crons/ one scheduled job per file → Queues and crons
17
+ │ ├── assets/ browser scripts and styles → Frontend
18
+ │ ├── durable-objects/ Durable Object classes (Cloudflare only)
19
+ │ └── workflows/ Workflow classes (Cloudflare only)
20
+ ├── modules/<feature>/ a feature's code: logic, views, client code, tests
21
+ ├── lib/ code features share: UI kit, design tokens, helpers
22
+ ├── public/ files served as they are at / → Frontend
23
+ ├── configs/
24
+ │ ├── env.ts the variables the app reads
25
+ │ ├── infra.ts the Alchemy stack
26
+ │ ├── vite.ts, vitest.ts, tsconfig.json
27
+ │ └── Dockerfile on Bun
28
+ └── .space/ generated
29
+ ```
30
+
31
+ [Folders](4-folders/index.md) has a page for each of these, with what goes in it and an example.
32
+
33
+ Each convention file has one default export, made with a helper: `route(...)`, `page(...)`, `middleware(...)`, `queue(...)`, `cron(...)`. Exporting something else is an error that names the file.
34
+
35
+ ## Where code goes
36
+
37
+ `app/` is what spacefn reads, so keep it to wiring: a file there connects code from `modules/` and `lib/` to a URL, a queue or the entry, and has no logic or markup of its own. The code itself goes in two folders:
38
+
39
+ - **`modules/<feature>/`**, one folder per feature: what it does (Effects over the databases and services), its views, its client code and its tests. `modules/todos/`, `modules/billing/`.
40
+ - **`lib/`** for what features share and that belongs to none of them: a UI kit with its design tokens, the layout, formatting and auth helpers. `lib/` doesn't import `modules/`.
41
+
42
+ spacefn doesn't enforce this; it's the layout the docs, the new app and the examples use, so each kind of code has one place to look. A page file then reads as a list of what's connected:
43
+
44
+ ```ts [app/routes/index.ts]
45
+ import { Effect, Schema } from "effect";
46
+ import { action, actionUrl, Datastar, page, redirect } from "spacefn";
47
+
48
+ import { layout } from "#lib/ui/layout.ts";
49
+ import * as Todos from "#modules/todos/todos.ts";
50
+ import { todoList, todosPage } from "#modules/todos/views.ts";
51
+
52
+ const list = Todos.list.pipe(
53
+ Effect.map((todos) => todoList({ todos, toggle: actionUrl("toggle") })),
54
+ );
55
+
56
+ export default page({
57
+ loader: Effect.map(list, (list) => ({ list })),
58
+ actions: {
59
+ add: action({
60
+ input: Todos.NewTodo,
61
+ handler: (todo) => Effect.as(Todos.add(todo), redirect("/")),
62
+ }),
63
+ toggle: action({
64
+ input: Todos.TodoRef,
65
+ handler: (todo) => Effect.as(Todos.toggle(todo), redirect("/")),
66
+ }),
67
+ live: action({
68
+ method: "get",
69
+ input: Schema.Struct({}),
70
+ handler: () => Datastar.watch([Todos.TOPIC], list),
71
+ }),
72
+ },
73
+ render: (ctx) =>
74
+ layout(
75
+ "Todos",
76
+ todosPage({ list: ctx.data.list, add: ctx.actions.add.url, live: ctx.actions.live.url }),
77
+ ),
78
+ });
79
+ ```
80
+
81
+ ```ts [modules/todos/todos.ts]
82
+ import { Effect, Schema } from "effect";
83
+ import { Bus } from "spacefn";
84
+
85
+ import MainDb from "#space/db/main.ts";
86
+
87
+ export const TOPIC = "todos";
88
+ export const NewTodo = Schema.Struct({ title: Schema.NonEmptyString });
89
+
90
+ export const list = MainDb.listTodos();
91
+
92
+ /** Adds a todo, and tells every open page. */
93
+ export const add = ({ title }: typeof NewTodo.Type) =>
94
+ MainDb.addTodo({ title }).pipe(Effect.andThen(Bus.publish(TOPIC, "changed")));
95
+ ```
96
+
97
+ Views are functions from plain props to `html`, not from the page's `ctx`: the page passes what they show and the URLs they post to. That keeps them testable alone, and usable from more than one page.
98
+
99
+ ## File names
100
+
101
+ In `app/routes/`, the path of a file is its URL. Its export decides what it is: a `page(...)` is a server-rendered page, a `route(...)` answers per HTTP method.
102
+
103
+ | File | URL |
104
+ | -------------------- | ------------------------------------------- |
105
+ | `index.ts` | `/` |
106
+ | `about.ts` | `/about` |
107
+ | `todos/index.ts` | `/todos` |
108
+ | `todos/[id].ts` | `/todos/:id`, read with `Input.params` |
109
+ | `files/[...path].ts` | `/files/*`, the rest of the path as `path` |
110
+ | `(admin)/users.ts` | `/users`: a `(group)` folder only organizes |
111
+
112
+ Parameter names must be identifiers (`[userId]`, not `[user-id]`). Two files for the same URL shape, such as `[id].ts` and `[slug].ts`, are an error.
113
+
114
+ - **Private files:** a file or folder starting with `_` is never a page, route or job, such as `app/routes/_shared.ts`. Most such code belongs in `modules/` or `lib/` instead.
115
+ - **Tests:** `*.test.ts` and `*.spec.ts` files are skipped too, so tests sit next to what they test.
116
+ - **Dev-only and prod-only files:** `debug.dev.ts` exists only in `space dev`, `banner.prod.ts` only in builds and deploys.
117
+ - **Middleware:** `_middleware.ts` in `app/routes/` wraps every request; in a folder below, it wraps that folder's pages and routes. See [Routes](6-guides/2-routes.md#middleware).
118
+ - **Queues and crons** are named after their file: `app/queues/emails.ts` is the queue `emails`.
119
+
120
+ ## Imports
121
+
122
+ Imports from the app root are [subpath imports](https://nodejs.org/api/packages.html#subpath-imports), declared in `package.json`. Node, TypeScript, Vite, Vitest and Bun all read them, so nothing else needs configuring:
123
+
124
+ ```json [package.json]
125
+ {
126
+ "imports": {
127
+ "#lib/*": "./lib/*",
128
+ "#modules/*": "./modules/*",
129
+ "#space/*": "./.space/*"
130
+ }
131
+ }
132
+ ```
133
+
134
+ - `#space/db/<name>.ts` is the generated database for `app/db/<name>/`, and `#space/islands.ts` gives `island(name, props)` for the `*.island.*` files (see [Frontend](6-guides/4-frontend.md#client-components)).
135
+ - `#modules/...` and `#lib/...` are your own code. Add a line for another folder, such as `"#ui/*": "./src/ui/*"`.
136
+ - `spacefn/assets` gives `assets("main", ...)`, the `<script>` and `<link>` tags of `app/assets/` entries (see [Frontend](6-guides/4-frontend.md#loading-entries)). The Vite plugin provides it.
137
+
138
+ Use relative imports with the `.ts` extension inside a folder.
@@ -0,0 +1,68 @@
1
+ ---
2
+ icon: bulb
3
+ ---
4
+
5
+ # Best practices
6
+
7
+ How to keep a spacefn app easy to change as it grows. None of this is enforced; it's how the docs, the new app and the examples are written, so following it means every example applies to your app as is.
8
+
9
+ ## Keep `app/` to wiring
10
+
11
+ A file in `app/` connects code to a URL, a queue or a schedule. It reads input, calls a module, and passes the result to a view. When a route or page file grows logic of its own, move that logic into the feature's module.
12
+
13
+ ```ts [app/routes/todos/[id].ts]
14
+ // Good: the route says what's connected, the module does the work.
15
+ export default route({ GET: Effect.flatMap(id, Todos.find) });
16
+ ```
17
+
18
+ ## One folder per feature
19
+
20
+ Put everything about a feature in `modules/<feature>/`: its logic, views, styles, browser code and tests. Deleting the folder (and the `app/` files that point at it) removes the feature. Shared code goes in `lib/`, which never imports `modules/`, so imports run one way: `app/` → `modules/` → `lib/`.
21
+
22
+ When two features need the same thing, move it to `lib/` instead of importing one feature from the other in both directions.
23
+
24
+ ## Name what the feature does
25
+
26
+ Export functions named for the domain, not for HTTP: `Todos.add`, `Orders.refund`, `Sessions.deleteExpired`. Then a page action, a route, a queue consumer and a cron can all call the same one, and the name still fits.
27
+
28
+ ## Views take props
29
+
30
+ A view is a function from plain props to `html`. Pass it what it shows and the URLs it posts to, never the page's `ctx`:
31
+
32
+ ```ts
33
+ todosPage({ todos: ctx.data.todos, add: ctx.actions.add.url });
34
+ ```
35
+
36
+ It can then be tested alone, reused by another page, and rendered again by a live update. Give an element that Datastar patches a fixed `id`, exported beside its view.
37
+
38
+ ## Decode at the edge
39
+
40
+ Read every input through a Schema: `Input.params`, `Input.query`, `Input.body`, an action's `input`, a queue's `body`. Inside the module, values are already the right type, so the code doesn't check them again. Keep the schema in the module, next to the function that takes it (`Todos.NewTodo`), and let the `app/` file reference it.
41
+
42
+ ## Fail with typed errors
43
+
44
+ Fail with spacefn's errors (`NotFound`, `Forbidden`, `Conflict`, ...) for what a client should see, and your own tagged errors for the rest. Don't throw: an exception is a defect, logged and answered with an opaque `500`. Handle a failure where you can do something about it, with `Effect.catchTag`.
45
+
46
+ ## Keep SQL in files
47
+
48
+ One query per file in `app/db/<name>/queries/`, so `space gen` types and checks it against the schema. Reach for `` sql`...` `` only when a query really is dynamic. Migrations only move forward: never edit one that has run, add the next.
49
+
50
+ ## Make jobs safe to repeat
51
+
52
+ Queue messages are delivered at least once, and a failed one is retried. Write handlers so running one twice does no harm: check whether the work is done, or use an `INSERT ... ON CONFLICT`. Crons run once per process on Bun, so run one cron process.
53
+
54
+ ## Configure through `configs/env.ts`
55
+
56
+ Declare every variable the app reads, with its type, and read it with `yield* Env`. Don't read `process.env`: it isn't checked, and it doesn't exist the same way on every target. Mark keys and tokens `Env.secret()`, so they stay out of logs and become secrets on deploy.
57
+
58
+ ## Load only what a page uses
59
+
60
+ Every page loads the layout's entries; a page that needs more passes its own with `assets(...)`. A framework island loads its own script, and only on the pages that render it, so pages without it stay light. Prefer server-rendered HTML with Datastar for interactivity, and use a framework island where a component really needs client state.
61
+
62
+ ## Test through the app
63
+
64
+ Test a feature the way it's used: `testApp(manifest, services)` serves the real pages and routes in memory, and `fetch` drives them. Test a module's functions directly when the logic has cases a page can't easily reach. Keep each test next to the code it tests.
65
+
66
+ ## Don't touch what's generated
67
+
68
+ `.space/` is rewritten from `app/` on every change. When something there looks wrong, the cause is in `app/` or `configs/`, and `space gen` names the file. Never commit it.
@@ -0,0 +1,48 @@
1
+ ---
2
+ title: entry.ts
3
+ icon: file-type-ts
4
+ ---
5
+
6
+ # app/entry.ts
7
+
8
+ The app itself: which services run, what wraps every request, extra routes beside the files, and how a failure is answered. Every app has one, and it's yours to change. spacefn never adds a service or a middleware you didn't list here, and the same file runs on Cloudflare and on Bun.
9
+
10
+ ```ts [app/entry.ts]
11
+ import { app, databases, errorPage, staticFiles, telemetry } from "spacefn";
12
+ import { platform } from "spacefn/platform";
13
+
14
+ import Env from "#configs/env.ts";
15
+ import { Mailer } from "#lib/mailer.ts";
16
+ import { manifest } from "#space/manifest.ts";
17
+
18
+ export default app(manifest, {
19
+ services: [
20
+ platform(manifest),
21
+ Env.layer,
22
+ databases(manifest),
23
+ telemetry(manifest.name),
24
+ Mailer.layer,
25
+ ],
26
+ before: [staticFiles()],
27
+ routes: [],
28
+ onError: errorPage,
29
+ });
30
+ ```
31
+
32
+ | Option | What it holds |
33
+ | ------------ | -------------------------------------------------------------------------------------------------- |
34
+ | `services` | Layers, in order: each can use the ones before it, and every page, route, queue and cron uses them |
35
+ | `before` | Middleware around every request, outside `app/routes/_middleware.ts` |
36
+ | `routes` | Effect `HttpRouter` layers beside the file routes, such as an `HttpApi` |
37
+ | `onError` | What a failed request answers, from its `Cause` |
38
+ | `bun` | Bun-only settings: `port`, `hostname`, `idleTimeout` |
39
+ | `cloudflare` | Cloudflare-only settings: extra Worker `handlers`, such as `email` |
40
+
41
+ `manifest` is what `space gen` found in `app/`, as a plain object: the routes, middleware, queues, crons and databases. The entry can filter it or add to it before passing it on.
42
+
43
+ Keep the entry to this list. A service of your own is written in `lib/` or its feature's folder and only listed here.
44
+
45
+ > [!TIP]
46
+ > Leave a piece out and it's gone: without `telemetry(...)` nothing is exported, and without `databases(manifest)` no database connects.
47
+
48
+ Read more in [The entry](../../6-guides/1-entry.md).