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.
- package/LICENSE +200 -0
- package/README.md +15 -2
- package/assets/reader.css +1131 -0
- package/assets/reader.js +324 -0
- package/content/1-getting-started.md +107 -0
- package/content/2-conventions.md +138 -0
- package/content/3-best-practices.md +68 -0
- package/content/4-folders/1-app/1-entry.md +48 -0
- package/content/4-folders/1-app/2-routes.md +92 -0
- package/content/4-folders/1-app/3-db.md +81 -0
- package/content/4-folders/1-app/4-queues.md +46 -0
- package/content/4-folders/1-app/5-crons.md +30 -0
- package/content/4-folders/1-app/6-assets.md +53 -0
- package/content/4-folders/1-app/7-durable-objects.md +60 -0
- package/content/4-folders/1-app/8-workflows.md +46 -0
- package/content/4-folders/1-app/index.md +43 -0
- package/content/4-folders/2-modules.md +71 -0
- package/content/4-folders/3-lib.md +60 -0
- package/content/4-folders/4-public.md +24 -0
- package/content/4-folders/5-docs.md +23 -0
- package/content/4-folders/6-configs.md +57 -0
- package/content/4-folders/7-space.md +34 -0
- package/content/4-folders/8-env.md +34 -0
- package/content/4-folders/9-package-json.md +37 -0
- package/content/4-folders/index.md +50 -0
- package/content/5-deployment/1-cloudflare.md +56 -0
- package/content/5-deployment/2-bun.md +68 -0
- package/content/5-deployment/3-infrastructure.md +67 -0
- package/content/5-deployment/4-ci-cd.md +131 -0
- package/content/5-deployment/index.md +48 -0
- package/content/6-guides/1-entry.md +113 -0
- package/content/6-guides/2-routes.md +162 -0
- package/content/6-guides/3-pages.md +148 -0
- package/content/6-guides/4-frontend.md +232 -0
- package/content/6-guides/5-database.md +178 -0
- package/content/6-guides/6-services.md +125 -0
- package/content/6-guides/7-jobs.md +61 -0
- package/content/6-guides/8-auth.md +111 -0
- package/content/6-guides/9-testing.md +70 -0
- package/content/6-guides/index.md +21 -0
- package/content/7-reference/1-config.md +67 -0
- package/content/7-reference/2-cli.md +27 -0
- package/content/7-reference/3-writing-docs.md +206 -0
- package/content/7-reference/index.md +15 -0
- package/content/index.md +49 -0
- package/content/logo.svg +12 -0
- package/dist/index.d.mts +72 -0
- package/dist/index.mjs +713 -0
- package/examples/README.md +18 -0
- package/examples/datastar/.env.example +2 -0
- package/examples/datastar/README.md +17 -0
- package/examples/datastar/app/assets/main.ts +4 -0
- package/examples/datastar/app/assets/site.css +3 -0
- package/examples/datastar/app/db/main/config.json +5 -0
- package/examples/datastar/app/db/main/migrations/0001_votes.sql +8 -0
- package/examples/datastar/app/db/main/queries/add-vote.sql +3 -0
- package/examples/datastar/app/db/main/queries/tally.sql +1 -0
- package/examples/datastar/app/entry.ts +28 -0
- package/examples/datastar/app/routes/_middleware.ts +4 -0
- package/examples/datastar/app/routes/health.ts +7 -0
- package/examples/datastar/app/routes/index.ts +43 -0
- package/examples/datastar/configs/env.ts +6 -0
- package/examples/datastar/configs/infra.ts +85 -0
- package/examples/datastar/configs/tsconfig.json +15 -0
- package/examples/datastar/configs/vite.ts +4 -0
- package/examples/datastar/configs/vitest.ts +9 -0
- package/examples/datastar/lib/types/rocket.d.ts +30 -0
- package/examples/datastar/lib/ui/base.css +17 -0
- package/examples/datastar/lib/ui/layout.ts +27 -0
- package/examples/datastar/modules/poll/client/poll-meter.ts +39 -0
- package/examples/datastar/modules/poll/poll.css +13 -0
- package/examples/datastar/modules/poll/poll.test.ts +48 -0
- package/examples/datastar/modules/poll/poll.ts +62 -0
- package/examples/datastar/modules/poll/views.ts +52 -0
- package/examples/datastar/package.json +33 -0
- package/examples/datastar/tsconfig.json +4 -0
- package/examples/lightningcss/.env.example +1 -0
- package/examples/lightningcss/README.md +15 -0
- package/examples/lightningcss/app/assets/site.css +3 -0
- package/examples/lightningcss/app/entry.ts +28 -0
- package/examples/lightningcss/app/routes/_middleware.ts +4 -0
- package/examples/lightningcss/app/routes/health.ts +7 -0
- package/examples/lightningcss/app/routes/index.ts +12 -0
- package/examples/lightningcss/configs/Dockerfile +26 -0
- package/examples/lightningcss/configs/Dockerfile.dockerignore +9 -0
- package/examples/lightningcss/configs/env.ts +4 -0
- package/examples/lightningcss/configs/infra.ts +55 -0
- package/examples/lightningcss/configs/tsconfig.json +15 -0
- package/examples/lightningcss/configs/vite.ts +19 -0
- package/examples/lightningcss/configs/vitest.ts +9 -0
- package/examples/lightningcss/lib/ui/layout.ts +17 -0
- package/examples/lightningcss/lib/ui/tokens.css +23 -0
- package/examples/lightningcss/modules/releases/releases.css +20 -0
- package/examples/lightningcss/modules/releases/releases.test.ts +18 -0
- package/examples/lightningcss/modules/releases/releases.ts +21 -0
- package/examples/lightningcss/modules/releases/views.ts +25 -0
- package/examples/lightningcss/package.json +33 -0
- package/examples/lightningcss/tsconfig.json +4 -0
- package/examples/mini-shopify/.env.example +6 -0
- package/examples/mini-shopify/README.md +19 -0
- package/examples/mini-shopify/app/assets/site.css +2 -0
- package/examples/mini-shopify/app/db/platform/config.json +5 -0
- package/examples/mini-shopify/app/db/platform/migrations/0001_shops.sql +10 -0
- package/examples/mini-shopify/app/db/platform/queries/add-shop.sql +4 -0
- package/examples/mini-shopify/app/db/platform/queries/find-shop.sql +3 -0
- package/examples/mini-shopify/app/db/platform/queries/list-shops.sql +1 -0
- package/examples/mini-shopify/app/db/shop/config.json +6 -0
- package/examples/mini-shopify/app/db/shop/migrations/0001_products.sql +11 -0
- package/examples/mini-shopify/app/db/shop/queries/add-product.sql +4 -0
- package/examples/mini-shopify/app/db/shop/queries/list-products.sql +1 -0
- package/examples/mini-shopify/app/db/shop/queries/sell-product.sql +2 -0
- package/examples/mini-shopify/app/entry.ts +25 -0
- package/examples/mini-shopify/app/routes/_middleware.ts +4 -0
- package/examples/mini-shopify/app/routes/health.ts +7 -0
- package/examples/mini-shopify/app/routes/index.ts +26 -0
- package/examples/mini-shopify/app/routes/s/[shop]/_middleware.ts +6 -0
- package/examples/mini-shopify/app/routes/s/[shop]/index.ts +32 -0
- package/examples/mini-shopify/configs/Dockerfile +26 -0
- package/examples/mini-shopify/configs/Dockerfile.dockerignore +9 -0
- package/examples/mini-shopify/configs/env.ts +14 -0
- package/examples/mini-shopify/configs/infra.ts +55 -0
- package/examples/mini-shopify/configs/tsconfig.json +15 -0
- package/examples/mini-shopify/configs/vite.ts +4 -0
- package/examples/mini-shopify/configs/vitest.ts +9 -0
- package/examples/mini-shopify/lib/ui/base.css +19 -0
- package/examples/mini-shopify/lib/ui/layout.ts +17 -0
- package/examples/mini-shopify/modules/catalog/catalog.ts +31 -0
- package/examples/mini-shopify/modules/catalog/views.ts +39 -0
- package/examples/mini-shopify/modules/shops/host.test.ts +38 -0
- package/examples/mini-shopify/modules/shops/host.ts +73 -0
- package/examples/mini-shopify/modules/shops/shops.test.ts +63 -0
- package/examples/mini-shopify/modules/shops/shops.ts +64 -0
- package/examples/mini-shopify/modules/shops/views.ts +28 -0
- package/examples/mini-shopify/package.json +35 -0
- package/examples/mini-shopify/tsconfig.json +4 -0
- package/examples/react/.env.example +2 -0
- package/examples/react/README.md +18 -0
- package/examples/react/app/assets/site.css +3 -0
- package/examples/react/app/entry.ts +28 -0
- package/examples/react/app/routes/_middleware.ts +4 -0
- package/examples/react/app/routes/about.ts +10 -0
- package/examples/react/app/routes/health.ts +7 -0
- package/examples/react/app/routes/index.ts +12 -0
- package/examples/react/configs/Dockerfile +26 -0
- package/examples/react/configs/Dockerfile.dockerignore +9 -0
- package/examples/react/configs/env.ts +6 -0
- package/examples/react/configs/infra.ts +55 -0
- package/examples/react/configs/tsconfig.json +16 -0
- package/examples/react/configs/vite.ts +7 -0
- package/examples/react/configs/vitest.ts +9 -0
- package/examples/react/lib/ui/base.css +12 -0
- package/examples/react/lib/ui/layout.ts +18 -0
- package/examples/react/modules/about/views.ts +8 -0
- package/examples/react/modules/shop/products.ts +18 -0
- package/examples/react/modules/shop/shop.css +13 -0
- package/examples/react/modules/shop/shop.test.ts +28 -0
- package/examples/react/modules/shop/shop.ts +13 -0
- package/examples/react/modules/shop/ui/Cart.island.tsx +31 -0
- package/examples/react/modules/shop/views.ts +16 -0
- package/examples/react/package.json +38 -0
- package/examples/react/tsconfig.json +4 -0
- package/examples/services-bun/README.md +10 -0
- package/examples/services-bun/app/assets/main.ts +4 -0
- package/examples/services-bun/app/assets/style.css +1 -0
- package/examples/services-bun/app/crons/nightly.ts +5 -0
- package/examples/services-bun/app/entry.ts +9 -0
- package/examples/services-bun/app/queues/jobs.ts +5 -0
- package/examples/services-bun/app/routes/index.ts +10 -0
- package/examples/services-bun/app/routes/runtime.ts +5 -0
- package/examples/services-bun/app/routes/send.ts +8 -0
- package/examples/services-bun/app/routes/version.ts +5 -0
- package/examples/services-bun/configs/Dockerfile +10 -0
- package/examples/services-bun/configs/Dockerfile.dockerignore +4 -0
- package/examples/services-bun/configs/infra.ts +28 -0
- package/examples/services-bun/configs/tsconfig.json +15 -0
- package/examples/services-bun/configs/vite.ts +4 -0
- package/examples/services-bun/lib/ui/base.css +3 -0
- package/examples/services-bun/lib/ui/layout.ts +13 -0
- package/examples/services-bun/modules/status/client/ready.ts +4 -0
- package/examples/services-bun/modules/status/status.ts +20 -0
- package/examples/services-bun/modules/status/views.ts +4 -0
- package/examples/services-bun/package.json +30 -0
- package/examples/services-bun/public/robots.txt +1 -0
- package/examples/services-bun/tsconfig.json +4 -0
- package/examples/services-cloudflare/README.md +9 -0
- package/examples/services-cloudflare/app/assets/main.ts +4 -0
- package/examples/services-cloudflare/app/crons/nightly.ts +5 -0
- package/examples/services-cloudflare/app/db/main/config.json +4 -0
- package/examples/services-cloudflare/app/db/main/migrations/0001_notes.sql +2 -0
- package/examples/services-cloudflare/app/db/main/queries/add-note.sql +1 -0
- package/examples/services-cloudflare/app/db/main/queries/count-notes.sql +3 -0
- package/examples/services-cloudflare/app/entry.ts +10 -0
- package/examples/services-cloudflare/app/queues/jobs.ts +5 -0
- package/examples/services-cloudflare/app/routes/files.ts +5 -0
- package/examples/services-cloudflare/app/routes/index.ts +10 -0
- package/examples/services-cloudflare/app/routes/limited.ts +7 -0
- package/examples/services-cloudflare/app/routes/send.ts +8 -0
- package/examples/services-cloudflare/configs/env.ts +3 -0
- package/examples/services-cloudflare/configs/infra.ts +85 -0
- package/examples/services-cloudflare/configs/tsconfig.json +15 -0
- package/examples/services-cloudflare/configs/vite.ts +4 -0
- package/examples/services-cloudflare/lib/ui/layout.ts +12 -0
- package/examples/services-cloudflare/modules/files/files.ts +9 -0
- package/examples/services-cloudflare/modules/status/client/ready.ts +4 -0
- package/examples/services-cloudflare/modules/status/status.ts +27 -0
- package/examples/services-cloudflare/modules/status/views.ts +8 -0
- package/examples/services-cloudflare/package.json +30 -0
- package/examples/services-cloudflare/public/robots.txt +1 -0
- package/examples/services-cloudflare/tsconfig.json +4 -0
- package/examples/solid/.env.example +2 -0
- package/examples/solid/README.md +18 -0
- package/examples/solid/app/assets/site.css +3 -0
- package/examples/solid/app/entry.ts +28 -0
- package/examples/solid/app/routes/_middleware.ts +4 -0
- package/examples/solid/app/routes/about.ts +10 -0
- package/examples/solid/app/routes/health.ts +7 -0
- package/examples/solid/app/routes/index.ts +12 -0
- package/examples/solid/configs/Dockerfile +26 -0
- package/examples/solid/configs/Dockerfile.dockerignore +9 -0
- package/examples/solid/configs/env.ts +6 -0
- package/examples/solid/configs/infra.ts +55 -0
- package/examples/solid/configs/tsconfig.json +17 -0
- package/examples/solid/configs/vite.ts +7 -0
- package/examples/solid/configs/vitest.ts +12 -0
- package/examples/solid/lib/ui/base.css +12 -0
- package/examples/solid/lib/ui/layout.ts +18 -0
- package/examples/solid/modules/about/views.ts +8 -0
- package/examples/solid/modules/shop/products.ts +18 -0
- package/examples/solid/modules/shop/shop.css +13 -0
- package/examples/solid/modules/shop/shop.test.ts +28 -0
- package/examples/solid/modules/shop/shop.ts +13 -0
- package/examples/solid/modules/shop/ui/Cart.island.tsx +31 -0
- package/examples/solid/modules/shop/views.ts +16 -0
- package/examples/solid/package.json +35 -0
- package/examples/solid/tsconfig.json +4 -0
- package/examples/starter-bun/.env.example +2 -0
- package/examples/starter-bun/AGENTS.md +9 -0
- package/examples/starter-bun/README.md +47 -0
- package/examples/starter-bun/app/assets/site.css +3 -0
- package/examples/starter-bun/app/db/main/config.json +5 -0
- package/examples/starter-bun/app/db/main/migrations/0001_todos.sql +9 -0
- package/examples/starter-bun/app/db/main/queries/add-todo.sql +2 -0
- package/examples/starter-bun/app/db/main/queries/list-todos.sql +2 -0
- package/examples/starter-bun/app/db/main/queries/toggle-todo.sql +2 -0
- package/examples/starter-bun/app/entry.ts +28 -0
- package/examples/starter-bun/app/routes/_middleware.ts +4 -0
- package/examples/starter-bun/app/routes/health.ts +7 -0
- package/examples/starter-bun/app/routes/index.ts +44 -0
- package/examples/starter-bun/configs/Dockerfile +26 -0
- package/examples/starter-bun/configs/Dockerfile.dockerignore +9 -0
- package/examples/starter-bun/configs/env.ts +6 -0
- package/examples/starter-bun/configs/infra.ts +55 -0
- package/examples/starter-bun/configs/tsconfig.json +15 -0
- package/examples/starter-bun/configs/vite.ts +4 -0
- package/examples/starter-bun/configs/vitest.ts +9 -0
- package/examples/starter-bun/docs/index.md +5 -0
- package/examples/starter-bun/lib/ui/base.css +17 -0
- package/examples/starter-bun/lib/ui/layout.ts +22 -0
- package/examples/starter-bun/modules/todos/todos.css +16 -0
- package/examples/starter-bun/modules/todos/todos.test.ts +33 -0
- package/examples/starter-bun/modules/todos/todos.ts +31 -0
- package/examples/starter-bun/modules/todos/views.ts +38 -0
- package/examples/starter-bun/package.json +32 -0
- package/examples/starter-bun/public/favicon.svg +1 -0
- package/examples/starter-bun/tsconfig.json +4 -0
- package/examples/starter-cloudflare/.env.example +2 -0
- package/examples/starter-cloudflare/AGENTS.md +9 -0
- package/examples/starter-cloudflare/README.md +47 -0
- package/examples/starter-cloudflare/app/assets/site.css +3 -0
- package/examples/starter-cloudflare/app/db/main/config.json +5 -0
- package/examples/starter-cloudflare/app/db/main/migrations/0001_todos.sql +9 -0
- package/examples/starter-cloudflare/app/db/main/queries/add-todo.sql +2 -0
- package/examples/starter-cloudflare/app/db/main/queries/list-todos.sql +2 -0
- package/examples/starter-cloudflare/app/db/main/queries/toggle-todo.sql +2 -0
- package/examples/starter-cloudflare/app/entry.ts +28 -0
- package/examples/starter-cloudflare/app/routes/_middleware.ts +4 -0
- package/examples/starter-cloudflare/app/routes/health.ts +7 -0
- package/examples/starter-cloudflare/app/routes/index.ts +44 -0
- package/examples/starter-cloudflare/configs/env.ts +6 -0
- package/examples/starter-cloudflare/configs/infra.ts +85 -0
- package/examples/starter-cloudflare/configs/tsconfig.json +15 -0
- package/examples/starter-cloudflare/configs/vite.ts +4 -0
- package/examples/starter-cloudflare/configs/vitest.ts +9 -0
- package/examples/starter-cloudflare/docs/index.md +5 -0
- package/examples/starter-cloudflare/lib/ui/base.css +17 -0
- package/examples/starter-cloudflare/lib/ui/layout.ts +22 -0
- package/examples/starter-cloudflare/modules/todos/todos.css +16 -0
- package/examples/starter-cloudflare/modules/todos/todos.test.ts +33 -0
- package/examples/starter-cloudflare/modules/todos/todos.ts +31 -0
- package/examples/starter-cloudflare/modules/todos/views.ts +38 -0
- package/examples/starter-cloudflare/package.json +32 -0
- package/examples/starter-cloudflare/public/favicon.svg +1 -0
- package/examples/starter-cloudflare/tsconfig.json +4 -0
- package/examples/svelte/.env.example +2 -0
- package/examples/svelte/README.md +18 -0
- package/examples/svelte/app/assets/site.css +3 -0
- package/examples/svelte/app/entry.ts +28 -0
- package/examples/svelte/app/routes/_middleware.ts +4 -0
- package/examples/svelte/app/routes/about.ts +10 -0
- package/examples/svelte/app/routes/health.ts +7 -0
- package/examples/svelte/app/routes/index.ts +12 -0
- package/examples/svelte/configs/env.ts +6 -0
- package/examples/svelte/configs/infra.ts +85 -0
- package/examples/svelte/configs/tsconfig.json +15 -0
- package/examples/svelte/configs/vite.ts +9 -0
- package/examples/svelte/configs/vitest.ts +9 -0
- package/examples/svelte/lib/types/svelte.d.ts +8 -0
- package/examples/svelte/lib/ui/base.css +12 -0
- package/examples/svelte/lib/ui/layout.ts +18 -0
- package/examples/svelte/modules/about/views.ts +8 -0
- package/examples/svelte/modules/shop/products.ts +18 -0
- package/examples/svelte/modules/shop/shop.css +13 -0
- package/examples/svelte/modules/shop/shop.test.ts +28 -0
- package/examples/svelte/modules/shop/shop.ts +13 -0
- package/examples/svelte/modules/shop/ui/Cart.island.svelte +23 -0
- package/examples/svelte/modules/shop/views.ts +16 -0
- package/examples/svelte/package.json +35 -0
- package/examples/svelte/tsconfig.json +4 -0
- package/examples/tailwind/.env.example +2 -0
- package/examples/tailwind/README.md +16 -0
- package/examples/tailwind/app/assets/site.css +2 -0
- package/examples/tailwind/app/entry.ts +28 -0
- package/examples/tailwind/app/routes/_middleware.ts +4 -0
- package/examples/tailwind/app/routes/health.ts +7 -0
- package/examples/tailwind/app/routes/index.ts +30 -0
- package/examples/tailwind/configs/Dockerfile +26 -0
- package/examples/tailwind/configs/Dockerfile.dockerignore +9 -0
- package/examples/tailwind/configs/env.ts +6 -0
- package/examples/tailwind/configs/infra.ts +55 -0
- package/examples/tailwind/configs/tsconfig.json +15 -0
- package/examples/tailwind/configs/vite.ts +7 -0
- package/examples/tailwind/configs/vitest.ts +9 -0
- package/examples/tailwind/lib/ui/components.ts +21 -0
- package/examples/tailwind/lib/ui/layout.ts +21 -0
- package/examples/tailwind/lib/ui/theme.css +10 -0
- package/examples/tailwind/modules/team/team.test.ts +30 -0
- package/examples/tailwind/modules/team/team.ts +34 -0
- package/examples/tailwind/modules/team/views.ts +45 -0
- package/examples/tailwind/package.json +35 -0
- package/examples/tailwind/tsconfig.json +4 -0
- package/examples/vue/.env.example +2 -0
- package/examples/vue/README.md +18 -0
- package/examples/vue/app/assets/site.css +3 -0
- package/examples/vue/app/entry.ts +28 -0
- package/examples/vue/app/routes/_middleware.ts +4 -0
- package/examples/vue/app/routes/about.ts +10 -0
- package/examples/vue/app/routes/health.ts +7 -0
- package/examples/vue/app/routes/index.ts +12 -0
- package/examples/vue/configs/env.ts +6 -0
- package/examples/vue/configs/infra.ts +85 -0
- package/examples/vue/configs/tsconfig.json +15 -0
- package/examples/vue/configs/vite.ts +7 -0
- package/examples/vue/configs/vitest.ts +9 -0
- package/examples/vue/lib/types/vue.d.ts +8 -0
- package/examples/vue/lib/ui/base.css +12 -0
- package/examples/vue/lib/ui/layout.ts +18 -0
- package/examples/vue/modules/about/views.ts +8 -0
- package/examples/vue/modules/shop/products.ts +18 -0
- package/examples/vue/modules/shop/shop.css +13 -0
- package/examples/vue/modules/shop/shop.test.ts +28 -0
- package/examples/vue/modules/shop/shop.ts +13 -0
- package/examples/vue/modules/shop/ui/Cart.island.vue +27 -0
- package/examples/vue/modules/shop/views.ts +16 -0
- package/examples/vue/package.json +35 -0
- package/examples/vue/tsconfig.json +4 -0
- package/package.json +44 -3
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: routes/
|
|
3
|
+
icon: route
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# app/routes/
|
|
7
|
+
|
|
8
|
+
A file per URL. The path of a file is the URL it answers, and its default export says how: a `page(...)` is a server-rendered page with forms, a `route(...)` answers per HTTP method.
|
|
9
|
+
|
|
10
|
+
```txt
|
|
11
|
+
app/routes/
|
|
12
|
+
├── _middleware.ts wraps every request
|
|
13
|
+
├── index.ts /
|
|
14
|
+
├── about.ts /about
|
|
15
|
+
├── health.ts /health
|
|
16
|
+
├── todos/
|
|
17
|
+
│ ├── index.ts /todos
|
|
18
|
+
│ └── [id].ts /todos/:id
|
|
19
|
+
├── files/
|
|
20
|
+
│ └── [...path].ts /files/*
|
|
21
|
+
├── (admin)/
|
|
22
|
+
│ ├── _middleware.ts wraps only the files in (admin)/
|
|
23
|
+
│ └── users.ts /users
|
|
24
|
+
└── debug.dev.ts /debug, only under space dev
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## File names
|
|
28
|
+
|
|
29
|
+
| Name | Matches |
|
|
30
|
+
| ---------------- | ----------------------------------------------------- |
|
|
31
|
+
| `index.ts` | the folder's own URL |
|
|
32
|
+
| `about.ts` | `/about` |
|
|
33
|
+
| `[id].ts` | one segment, read with `Input.params` |
|
|
34
|
+
| `[...path].ts` | the rest of the path, as `path` |
|
|
35
|
+
| `(group)/` | nothing: a group organizes files without a URL |
|
|
36
|
+
| `_middleware.ts` | wraps the requests to its folder and the ones below |
|
|
37
|
+
| `_anything.ts` | nothing: private, never a page or route |
|
|
38
|
+
| `name.dev.ts` | only under `space dev`; `name.prod.ts` only in builds |
|
|
39
|
+
|
|
40
|
+
Parameter names are identifiers (`[userId]`, not `[user-id]`). Two files for the same URL shape, such as `[id].ts` and `[slug].ts` in one folder, are an error from `space gen`, and so is a file in [`public/`](../4-public.md) at a route's URL.
|
|
41
|
+
|
|
42
|
+
## A route
|
|
43
|
+
|
|
44
|
+
```ts [app/routes/todos/[id].ts]
|
|
45
|
+
import { Effect, Schema } from "effect";
|
|
46
|
+
import { Input, route } from "spacefn";
|
|
47
|
+
|
|
48
|
+
import * as Todos from "#modules/todos/todos.ts";
|
|
49
|
+
|
|
50
|
+
const id = Effect.map(Input.params(Schema.Struct({ id: Schema.FiniteFromString })), (p) => p.id);
|
|
51
|
+
|
|
52
|
+
export default route({
|
|
53
|
+
GET: Effect.flatMap(id, Todos.find),
|
|
54
|
+
DELETE: Effect.flatMap(id, Todos.remove),
|
|
55
|
+
});
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
A value is answered as JSON, a string as text, `` html`...` `` as HTML, nothing as `204`. A method the file doesn't handle is `405`.
|
|
59
|
+
|
|
60
|
+
## A page
|
|
61
|
+
|
|
62
|
+
```ts [app/routes/index.ts]
|
|
63
|
+
import { Effect } from "effect";
|
|
64
|
+
import { action, page, redirect } from "spacefn";
|
|
65
|
+
|
|
66
|
+
import { layout } from "#lib/ui/layout.ts";
|
|
67
|
+
import * as Todos from "#modules/todos/todos.ts";
|
|
68
|
+
import { todosPage } from "#modules/todos/views.ts";
|
|
69
|
+
|
|
70
|
+
export default page({
|
|
71
|
+
loader: Effect.map(Todos.list, (todos) => ({ todos })),
|
|
72
|
+
actions: {
|
|
73
|
+
add: action({
|
|
74
|
+
input: Todos.NewTodo,
|
|
75
|
+
handler: (todo) => Effect.as(Todos.add(todo), redirect("/")),
|
|
76
|
+
}),
|
|
77
|
+
},
|
|
78
|
+
render: (ctx) => layout("Todos", todosPage({ todos: ctx.data.todos, add: ctx.actions.add.url })),
|
|
79
|
+
});
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## Middleware
|
|
83
|
+
|
|
84
|
+
`_middleware.ts` exports one `middleware(...)`, or an array that runs in order. The one at the top wraps every request, including the 404 for a URL nothing serves; one in a folder wraps that folder and its subfolders, inside the outer ones. For a single page or route, pass the same middleware as its `handle`.
|
|
85
|
+
|
|
86
|
+
```ts [app/routes/_middleware.ts]
|
|
87
|
+
import { csrf } from "spacefn";
|
|
88
|
+
|
|
89
|
+
export default csrf();
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Read more in [Routes and middleware](../../6-guides/2-routes.md) and [Pages](../../6-guides/3-pages.md).
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: db/
|
|
3
|
+
icon: database
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# app/db/
|
|
7
|
+
|
|
8
|
+
One folder per database. Its name is the database's: `app/db/main/` is `main`, imported as `MainDb` from `#space/db/main.ts`. You write the schema and the queries in SQL, and `space gen` turns them into a typed service.
|
|
9
|
+
|
|
10
|
+
```txt
|
|
11
|
+
app/db/
|
|
12
|
+
├── main/
|
|
13
|
+
│ ├── config.json how it's reached, and when it migrates
|
|
14
|
+
│ ├── migrations/
|
|
15
|
+
│ │ ├── 0001_todos.sql -- up and -- down
|
|
16
|
+
│ │ └── 0002_due_dates.sql
|
|
17
|
+
│ └── queries/
|
|
18
|
+
│ ├── list-todos.sql MainDb.listTodos()
|
|
19
|
+
│ ├── add-todo.sql MainDb.addTodo({ title })
|
|
20
|
+
│ └── todos/
|
|
21
|
+
│ └── mark-done.sql MainDb.todos.markDone({ id })
|
|
22
|
+
└── analytics/ a second database, AnalyticsDb
|
|
23
|
+
└── ...
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## `config.json`
|
|
27
|
+
|
|
28
|
+
Required in each database folder:
|
|
29
|
+
|
|
30
|
+
```json [app/db/main/config.json]
|
|
31
|
+
{
|
|
32
|
+
"$schema": "../../../node_modules/spacefn/schemas/db.json",
|
|
33
|
+
"driver": "d1",
|
|
34
|
+
"migrateOn": "startup"
|
|
35
|
+
}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
| Key | Values |
|
|
39
|
+
| ----------- | ----------------------------------------------------------------------------------------- |
|
|
40
|
+
| `driver` | `d1` or `durable-object` (Cloudflare), `libsql` (both targets) |
|
|
41
|
+
| `migrateOn` | `startup`: pending migrations run as the app starts. `call`: you run them |
|
|
42
|
+
| `open` | `startup` (the default): the entry opens it. `manual`: your code does, for one per tenant |
|
|
43
|
+
|
|
44
|
+
## `migrations/`
|
|
45
|
+
|
|
46
|
+
`NNNN_name.sql`, applied in number order, each once. An `-- up` section, and optionally a `-- down` that undoes it:
|
|
47
|
+
|
|
48
|
+
```sql [app/db/main/migrations/0001_todos.sql]
|
|
49
|
+
-- up
|
|
50
|
+
CREATE TABLE todos (id INTEGER PRIMARY KEY, title TEXT NOT NULL, done INTEGER NOT NULL DEFAULT 0);
|
|
51
|
+
|
|
52
|
+
-- down
|
|
53
|
+
DROP TABLE todos;
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
A migration edited after it ran is refused, so change the schema with a new one.
|
|
57
|
+
|
|
58
|
+
## `queries/`
|
|
59
|
+
|
|
60
|
+
One statement per file. The file name is the function's, `find-todo.sql` is `findTodo`, and a folder groups its queries under its name. Comments type what SQL can't say:
|
|
61
|
+
|
|
62
|
+
```sql [app/db/main/queries/find-todo.sql]
|
|
63
|
+
-- :one
|
|
64
|
+
-- @param id number
|
|
65
|
+
SELECT id, title, done FROM todos WHERE id = :id;
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
`space gen` checks every query against the migrations, and reports a wrong table or column with its file.
|
|
69
|
+
|
|
70
|
+
## Using it
|
|
71
|
+
|
|
72
|
+
```ts [modules/todos/todos.ts]
|
|
73
|
+
import MainDb from "#space/db/main.ts";
|
|
74
|
+
|
|
75
|
+
export const list = MainDb.listTodos();
|
|
76
|
+
export const add = (title: string) => MainDb.addTodo({ title });
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Files and folders starting with `_` are drafts, skipped in all three places.
|
|
80
|
+
|
|
81
|
+
Read more in [Database](../../6-guides/5-database.md).
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: queues/
|
|
3
|
+
icon: stack-2
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# app/queues/
|
|
7
|
+
|
|
8
|
+
One file per queue: the file consumes the queue of its name. `app/queues/emails.ts` is the queue `emails`, and code anywhere in the app sends to it with `Queue.send("emails", body)`.
|
|
9
|
+
|
|
10
|
+
```txt
|
|
11
|
+
app/queues/
|
|
12
|
+
├── emails.ts the queue "emails"
|
|
13
|
+
└── order-jobs.ts the queue "order-jobs"
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Only files directly in the folder count. Names are lowercase letters, digits and `-`, starting with a letter.
|
|
17
|
+
|
|
18
|
+
```ts [app/queues/emails.ts]
|
|
19
|
+
import { queue } from "spacefn";
|
|
20
|
+
|
|
21
|
+
import * as Emails from "#modules/emails/emails.ts";
|
|
22
|
+
|
|
23
|
+
export default queue({ body: Emails.Email, handler: Emails.send, retryDelay: "30 seconds" });
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
| Option | What it does |
|
|
27
|
+
| ------------- | ---------------------------------------------------------------- |
|
|
28
|
+
| `body` | The Schema each message is decoded with before `handler` sees it |
|
|
29
|
+
| `handler` | `(body, message) => Effect`; a failure retries that message |
|
|
30
|
+
| `concurrency` | How many messages of a batch run at once (default 1, in order) |
|
|
31
|
+
| `retryDelay` | How long to wait before a retry |
|
|
32
|
+
|
|
33
|
+
The schema and the handler belong to the feature, in `modules/`, next to a function that sends:
|
|
34
|
+
|
|
35
|
+
```ts [modules/emails/emails.ts]
|
|
36
|
+
import { Schema } from "effect";
|
|
37
|
+
import { Queue } from "spacefn";
|
|
38
|
+
|
|
39
|
+
export const Email = Schema.Struct({ to: Schema.String, subject: Schema.String });
|
|
40
|
+
|
|
41
|
+
export const later = (email: typeof Email.Type) => Queue.send("emails", email);
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Delivery is at least once, so make handlers safe to run twice. On Cloudflare each file is a Cloudflare Queue and its consumer; on Bun, a table in the state database read by the queue process.
|
|
45
|
+
|
|
46
|
+
Read more in [Queues and crons](../../6-guides/7-jobs.md).
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: crons/
|
|
3
|
+
icon: clock
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# app/crons/
|
|
7
|
+
|
|
8
|
+
One scheduled job per file. The default export is `cron(schedule, job)`:
|
|
9
|
+
|
|
10
|
+
```txt
|
|
11
|
+
app/crons/
|
|
12
|
+
├── nightly.ts 0 3 * * *
|
|
13
|
+
└── hourly-sync.ts 0 * * * *
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
```ts [app/crons/nightly.ts]
|
|
17
|
+
import { cron } from "spacefn";
|
|
18
|
+
|
|
19
|
+
import * as Sessions from "#modules/accounts/sessions.ts";
|
|
20
|
+
|
|
21
|
+
export default cron("0 3 * * *", Sessions.deleteExpired);
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
The schedule is five fields in UTC: minute, hour, day of month, month, day of week, with lists (`1,15`), ranges (`9-17`), steps (`*/5`) and names (`MON-FRI`). Write it as a string literal: the infra reads it from the file without running it, and `space gen` stops on one it can't read.
|
|
25
|
+
|
|
26
|
+
Only files directly in the folder count, named in lowercase letters, digits and `-`. Jobs on the same schedule run at once; one failing is logged and doesn't stop the others.
|
|
27
|
+
|
|
28
|
+
On Cloudflare each schedule is a Cron Trigger on the Worker. On Bun the cron process runs them at the start of each matching minute, so run one cron process only.
|
|
29
|
+
|
|
30
|
+
Read more in [Queues and crons](../../6-guides/7-jobs.md#crons).
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: assets/
|
|
3
|
+
icon: browser
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# app/assets/
|
|
7
|
+
|
|
8
|
+
The browser's entries. Each script or stylesheet directly in the folder is an entry that Vite bundles, named after its file: `main.ts` is `main`, `site.css` is `site`. A page loads the entries it needs with `assets("name", ...)`.
|
|
9
|
+
|
|
10
|
+
```txt
|
|
11
|
+
app/assets/
|
|
12
|
+
├── site.css @imports the base styles and each feature's
|
|
13
|
+
├── main.ts what every page runs
|
|
14
|
+
└── charts.ts only on the pages with a chart
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
`.ts`, `.tsx`, `.js` and `.css` files are entries; subfolders, `_` files and tests aren't. A framework component doesn't need one: an [island](../../6-guides/4-frontend.md#client-components) is an entry of its own. Two entries can't share a name (`main.ts` and `main.css`): import the stylesheet from the script instead.
|
|
18
|
+
|
|
19
|
+
Keep each entry to a few lines that import from `modules/` and `lib/`, so the code lives with its feature:
|
|
20
|
+
|
|
21
|
+
```ts [app/assets/charts.ts]
|
|
22
|
+
import { defineSalesChart } from "#modules/sales/client/sales-chart.ts";
|
|
23
|
+
|
|
24
|
+
defineSalesChart();
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
```css [app/assets/site.css]
|
|
28
|
+
@import "#lib/ui/base.css";
|
|
29
|
+
@import "#modules/todos/todos.css";
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Loading entries
|
|
33
|
+
|
|
34
|
+
```ts [lib/ui/layout.ts]
|
|
35
|
+
import { html, type HtmlValue } from "spacefn";
|
|
36
|
+
import { assets } from "spacefn/assets";
|
|
37
|
+
|
|
38
|
+
export const layout = (title: string, body: HtmlValue, head: HtmlValue = "") =>
|
|
39
|
+
html`<!doctype html>
|
|
40
|
+
<html lang="en">
|
|
41
|
+
<head>
|
|
42
|
+
<title>${title}</title>
|
|
43
|
+
${assets("site")} ${head}
|
|
44
|
+
</head>
|
|
45
|
+
<body>
|
|
46
|
+
${body}
|
|
47
|
+
</body>
|
|
48
|
+
</html>`;
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
`assets(...)` gives the `<script>` and `<link>` tags, in the order you name them, pointing at the sources in dev and at the hashed files in a build. The names are typed from this folder, so a misspelt or deleted entry is a type error.
|
|
52
|
+
|
|
53
|
+
Read more in [Frontend](../../6-guides/4-frontend.md).
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: durable-objects/
|
|
3
|
+
icon: cube
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# app/durable-objects/
|
|
7
|
+
|
|
8
|
+
Your own [Durable Objects](https://developers.cloudflare.com/durable-objects/), on Cloudflare only. Each file's default export is a Durable Object class. The file name gives the class its name and the Worker its binding:
|
|
9
|
+
|
|
10
|
+
```txt
|
|
11
|
+
app/durable-objects/
|
|
12
|
+
├── chat-room.ts class ChatRoom, binding DO_CHAT_ROOM
|
|
13
|
+
└── counter.ts class Counter, binding DO_COUNTER
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
spacefn exports each class from the Worker, and the scaffolded `configs/infra.ts` binds it. Only files directly in the folder count, named in lowercase letters, digits and `-`. On Bun, a file here stops `space gen`.
|
|
17
|
+
|
|
18
|
+
```ts [app/durable-objects/counter.ts]
|
|
19
|
+
import { DurableObject } from "cloudflare:workers";
|
|
20
|
+
import { Effect, ManagedRuntime, Option } from "effect";
|
|
21
|
+
import { durableObjectSql } from "spacefn/cloudflare";
|
|
22
|
+
|
|
23
|
+
import CounterDb from "#space/db/counter.ts";
|
|
24
|
+
|
|
25
|
+
export default class Counter extends DurableObject {
|
|
26
|
+
readonly #runtime;
|
|
27
|
+
|
|
28
|
+
constructor(ctx: DurableObjectState, env: unknown) {
|
|
29
|
+
super(ctx, env);
|
|
30
|
+
// app/db/counter/ has "driver": "durable-object": each object has its own SQLite.
|
|
31
|
+
this.#runtime = ManagedRuntime.make(CounterDb.layer(durableObjectSql(ctx.storage)));
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
override fetch() {
|
|
35
|
+
return this.#runtime.runPromise(
|
|
36
|
+
Effect.gen(function* () {
|
|
37
|
+
yield* CounterDb.bump();
|
|
38
|
+
const total = yield* CounterDb.total();
|
|
39
|
+
return Response.json(Option.getOrThrow(total).n);
|
|
40
|
+
}),
|
|
41
|
+
);
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Reach it from a route through `CloudflareEnv`, which gives the Worker's bindings:
|
|
47
|
+
|
|
48
|
+
```ts [modules/counter/counter.ts]
|
|
49
|
+
import { Effect } from "effect";
|
|
50
|
+
import { CloudflareEnv } from "spacefn/cloudflare";
|
|
51
|
+
|
|
52
|
+
export const bump = (name: string) =>
|
|
53
|
+
Effect.gen(function* () {
|
|
54
|
+
const { DO_COUNTER } = (yield* CloudflareEnv) as { DO_COUNTER: DurableObjectNamespace };
|
|
55
|
+
const stub = DO_COUNTER.get(DO_COUNTER.idFromName(name));
|
|
56
|
+
return yield* Effect.promise(async () => (await stub.fetch("https://counter/")).json());
|
|
57
|
+
});
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
A database with `"driver": "durable-object"` lives inside each object, opened with `durableObjectSql(ctx.storage)`; it migrates as the object starts. spacefn's own `Bus` and `RateLimiter` are Durable Objects too, which `configs/infra.ts` binds beside yours.
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: workflows/
|
|
3
|
+
icon: git-branch
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# app/workflows/
|
|
7
|
+
|
|
8
|
+
Your [Workflows](https://developers.cloudflare.com/workflows/), on Cloudflare only: durable, multi-step jobs that survive restarts and retry each step. Each file's default export is a `WorkflowEntrypoint` class, named after the file:
|
|
9
|
+
|
|
10
|
+
```txt
|
|
11
|
+
app/workflows/
|
|
12
|
+
└── onboarding.ts class Onboarding, binding WF_ONBOARDING
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
spacefn exports each class from the Worker, and the scaffolded `configs/infra.ts` creates the workflow and binds it. Only files directly in the folder count, named in lowercase letters, digits and `-`. On Bun, a file here stops `space gen`; use a queue there instead.
|
|
16
|
+
|
|
17
|
+
```ts [app/workflows/onboarding.ts]
|
|
18
|
+
import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from "cloudflare:workers";
|
|
19
|
+
|
|
20
|
+
export default class Onboarding extends WorkflowEntrypoint<unknown, { email: string }> {
|
|
21
|
+
override async run(event: WorkflowEvent<{ email: string }>, step: WorkflowStep) {
|
|
22
|
+
await step.do("send the welcome email", async () => {
|
|
23
|
+
/* ... */
|
|
24
|
+
});
|
|
25
|
+
await step.sleep("wait a day", "1 day");
|
|
26
|
+
await step.do("send the tips email", async () => {
|
|
27
|
+
/* ... */
|
|
28
|
+
});
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Start one from your code through `CloudflareEnv`:
|
|
34
|
+
|
|
35
|
+
```ts [modules/accounts/onboarding.ts]
|
|
36
|
+
import { Effect } from "effect";
|
|
37
|
+
import { CloudflareEnv } from "spacefn/cloudflare";
|
|
38
|
+
|
|
39
|
+
export const startOnboarding = (email: string) =>
|
|
40
|
+
Effect.gen(function* () {
|
|
41
|
+
const { WF_ONBOARDING } = (yield* CloudflareEnv) as { WF_ONBOARDING: Workflow };
|
|
42
|
+
yield* Effect.promise(() => WF_ONBOARDING.create({ params: { email } }));
|
|
43
|
+
});
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
A workflow runs outside spacefn's request handling, so it doesn't get the entry's services. Keep each step's work in `modules/`, as plain functions or Effects run with a runtime of their own, as in [`durable-objects/`](7-durable-objects.md).
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
---
|
|
2
|
+
icon: folder-code
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# app/
|
|
6
|
+
|
|
7
|
+
`app/` is the folder spacefn reads. It finds the pages, routes, databases, queues and jobs by where their files are, and writes the wiring for them into [`.space/`](../7-space.md). It reads the files without running them, so `space gen` is fast and safe.
|
|
8
|
+
|
|
9
|
+
```txt
|
|
10
|
+
app/
|
|
11
|
+
├── entry.ts
|
|
12
|
+
├── routes/
|
|
13
|
+
├── db/
|
|
14
|
+
├── queues/
|
|
15
|
+
├── crons/
|
|
16
|
+
├── assets/
|
|
17
|
+
├── durable-objects/
|
|
18
|
+
└── workflows/
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Every folder is optional; `entry.ts` is required. A folder the target can't run, such as `durable-objects/` on Bun, stops `space gen` with an error that says so.
|
|
22
|
+
|
|
23
|
+
## Wiring only
|
|
24
|
+
|
|
25
|
+
A file in `app/` connects code to something spacefn serves: a URL, a queue, a schedule. The code itself lives in [`modules/`](../2-modules.md) and [`lib/`](../3-lib.md). A route reads its input and calls a module; a page passes a module's data to a view. That keeps each file in `app/` short enough to read as a list of what's connected:
|
|
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 });
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
spacefn doesn't check this; it's how the docs and the examples are written.
|
|
36
|
+
|
|
37
|
+
## Rules for every folder
|
|
38
|
+
|
|
39
|
+
- **One default export**, made with its helper: `page(...)`, `route(...)`, `middleware(...)`, `queue(...)`, `cron(...)`. Anything else is an error naming the file.
|
|
40
|
+
- **Private files:** a file or folder starting with `_` is skipped, except `_middleware.ts`.
|
|
41
|
+
- **Tests:** `*.test.ts` and `*.spec.ts` are skipped, so a test can sit beside the file it tests.
|
|
42
|
+
- **Dev-only and prod-only routes:** in `routes/`, `name.dev.ts` exists only under `space dev`, `name.prod.ts` only in builds and deploys.
|
|
43
|
+
- **Names:** queue, cron, Durable Object and workflow files are named in lowercase letters, digits and `-`, starting with a letter: `order-jobs.ts`.
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: modules/
|
|
3
|
+
icon: puzzle
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# modules/
|
|
7
|
+
|
|
8
|
+
One folder per feature: what it does, how it looks, its browser code and its tests, side by side. `app/` files import from here and connect it to URLs, queues and schedules.
|
|
9
|
+
|
|
10
|
+
```txt
|
|
11
|
+
modules/
|
|
12
|
+
├── todos/
|
|
13
|
+
│ ├── todos.ts what the feature does: Effects over the database and services
|
|
14
|
+
│ ├── views.ts its HTML: functions from props to html
|
|
15
|
+
│ ├── todos.css its styles, imported by app/assets/site.css
|
|
16
|
+
│ ├── ui/ its client components
|
|
17
|
+
│ │ ├── TodoItem.tsx
|
|
18
|
+
│ │ └── TodoList.island.tsx an island, rendered with island("TodoList", props)
|
|
19
|
+
│ ├── client/ its other browser code, such as web components
|
|
20
|
+
│ └── todos.test.ts its tests
|
|
21
|
+
└── billing/
|
|
22
|
+
├── billing.ts
|
|
23
|
+
├── stripe.ts a service only this feature uses
|
|
24
|
+
└── billing.test.ts
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Import it with `#modules/...`, declared in `package.json`:
|
|
28
|
+
|
|
29
|
+
```ts [app/routes/index.ts]
|
|
30
|
+
import * as Todos from "#modules/todos/todos.ts";
|
|
31
|
+
import { todosPage } from "#modules/todos/views.ts";
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## What goes in a feature
|
|
35
|
+
|
|
36
|
+
**Logic** is Effects over the generated databases and spacefn's services. Name them for what the feature does, not for the HTTP call that triggers them:
|
|
37
|
+
|
|
38
|
+
```ts [modules/todos/todos.ts]
|
|
39
|
+
import { Effect, Schema } from "effect";
|
|
40
|
+
import { Bus } from "spacefn";
|
|
41
|
+
|
|
42
|
+
import MainDb from "#space/db/main.ts";
|
|
43
|
+
|
|
44
|
+
export const TOPIC = "todos";
|
|
45
|
+
export const NewTodo = Schema.Struct({ title: Schema.NonEmptyString });
|
|
46
|
+
|
|
47
|
+
export const list = MainDb.listTodos();
|
|
48
|
+
|
|
49
|
+
/** Adds a todo, and tells every open page. */
|
|
50
|
+
export const add = ({ title }: typeof NewTodo.Type) =>
|
|
51
|
+
MainDb.addTodo({ title }).pipe(Effect.andThen(Bus.publish(TOPIC, "changed")));
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
**Views** take plain props: what they show and the URLs they post to. Not a page's `ctx`, so a test or a live update can render them alone:
|
|
55
|
+
|
|
56
|
+
```ts [modules/todos/views.ts]
|
|
57
|
+
import { html } from "spacefn";
|
|
58
|
+
|
|
59
|
+
export const todoList = (props: { readonly todos: readonly { title: string }[] }) =>
|
|
60
|
+
html`<ul id="todo-list">
|
|
61
|
+
${props.todos.map((todo) => html`<li>${todo.title}</li>`)}
|
|
62
|
+
</ul>`;
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
**Tests** sit next to the code, as `*.test.ts`; `npm test` finds them.
|
|
66
|
+
|
|
67
|
+
## Between features
|
|
68
|
+
|
|
69
|
+
A feature can use another's exported functions, but keep the arrows one way: if `billing` uses `accounts`, `accounts` doesn't use `billing`. Code that two features need and neither owns moves to [`lib/`](3-lib.md).
|
|
70
|
+
|
|
71
|
+
spacefn doesn't read this folder; it's a convention, not a rule. Read more in [Best practices](../3-best-practices.md).
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: lib/
|
|
3
|
+
icon: components
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# lib/
|
|
7
|
+
|
|
8
|
+
Code the features share and none of them owns: the UI kit and its design tokens, the layout around every page, your own services, and small helpers.
|
|
9
|
+
|
|
10
|
+
```txt
|
|
11
|
+
lib/
|
|
12
|
+
├── ui/
|
|
13
|
+
│ ├── layout.ts the HTML around every page
|
|
14
|
+
│ ├── base.css design tokens and base styles
|
|
15
|
+
│ └── button.ts components every feature uses
|
|
16
|
+
├── auth/
|
|
17
|
+
│ └── admin.ts requireAdmin, for _middleware.ts files
|
|
18
|
+
├── mailer.ts a service, listed in app/entry.ts
|
|
19
|
+
└── format.ts money, dates, plurals
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Import it with `#lib/...`, in TypeScript and in CSS:
|
|
23
|
+
|
|
24
|
+
```ts
|
|
25
|
+
import { layout } from "#lib/ui/layout.ts";
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
```css [app/assets/site.css]
|
|
29
|
+
@import "#lib/ui/base.css";
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Design tokens and components
|
|
33
|
+
|
|
34
|
+
Keep the tokens in one stylesheet as custom properties, and have components use them:
|
|
35
|
+
|
|
36
|
+
```css [lib/ui/base.css]
|
|
37
|
+
:root {
|
|
38
|
+
--color-text: #1f2328;
|
|
39
|
+
--color-accent: #c2185b;
|
|
40
|
+
--space-2: 0.5rem;
|
|
41
|
+
--radius: 8px;
|
|
42
|
+
}
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
```ts [lib/ui/button.ts]
|
|
46
|
+
import { html } from "spacefn";
|
|
47
|
+
|
|
48
|
+
export const button = (props: { readonly label: string; readonly action: string }) =>
|
|
49
|
+
html`<form method="post" action="${props.action}">
|
|
50
|
+
<button class="button">${props.label}</button>
|
|
51
|
+
</form>`;
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## Services
|
|
55
|
+
|
|
56
|
+
A service of your own is an Effect `Context.Service` with a layer. Put it in `lib/` when every feature can use it, and list its layer in [`app/entry.ts`](1-app/1-entry.md). See [Services](../6-guides/6-services.md#your-own-services).
|
|
57
|
+
|
|
58
|
+
## The rule
|
|
59
|
+
|
|
60
|
+
`lib/` doesn't import `modules/`. That keeps it reusable, and makes the direction of every import obvious: `app/` → `modules/` → `lib/`.
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: public/
|
|
3
|
+
icon: world-www
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# public/
|
|
7
|
+
|
|
8
|
+
Files served as they are, at the app's root URL: `public/favicon.svg` is `/favicon.svg`, `public/images/og.png` is `/images/og.png`. They're copied into the build unchanged, without hashed names.
|
|
9
|
+
|
|
10
|
+
```txt
|
|
11
|
+
public/
|
|
12
|
+
├── favicon.svg /favicon.svg
|
|
13
|
+
├── robots.txt /robots.txt
|
|
14
|
+
└── images/
|
|
15
|
+
└── og.png /images/og.png
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
On both targets they're answered before the app runs: by Cloudflare's assets on Cloudflare, by `staticFiles()` in the entry on Bun. So a public file at a route's URL would hide the route, and `space gen` stops with `PUBLIC_SHADOWS_ROUTE` instead. An HTML file counts at its clean URL too: `about.html` is also `/about`.
|
|
19
|
+
|
|
20
|
+
Use it for files that need a fixed URL: icons, `robots.txt`, `.well-known/` files, images linked from elsewhere. Import everything else from [`app/assets/`](1-app/6-assets.md), so it gets a hashed name and caches safely:
|
|
21
|
+
|
|
22
|
+
```html
|
|
23
|
+
<link rel="icon" href="/favicon.svg" />
|
|
24
|
+
```
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: docs/
|
|
3
|
+
icon: book
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# docs/
|
|
7
|
+
|
|
8
|
+
Notes on this app, for whoever works on it next: how it fits together, runbooks, decisions. `npm run docs` (`space docs`) shows them in the same reader as these docs, with spacefn's docs beside them, and `npm run dev` serves it at `/__space/docs/`.
|
|
9
|
+
|
|
10
|
+
```txt
|
|
11
|
+
docs/
|
|
12
|
+
├── index.md the home page
|
|
13
|
+
├── 1-architecture.md /architecture.md
|
|
14
|
+
├── logo.svg the reader's logo
|
|
15
|
+
└── 2-runbooks/
|
|
16
|
+
├── index.md names and orders the group
|
|
17
|
+
├── 1-deploys.md /runbooks/deploys.md
|
|
18
|
+
└── 2-incidents.md /runbooks/incidents.md
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Every Markdown file is a page and every folder a group in the sidebar. A number before a name orders it and is left out of the URL and the label. Pages can have frontmatter (`title`, `order`, `description`, `icon`), code with file names and tabs, callouts, Mermaid diagrams and HTML. Edit a file and the open page reloads.
|
|
22
|
+
|
|
23
|
+
Read more in [Writing docs](../7-reference/3-writing-docs.md).
|