spacefn-docs 0.0.0-stage → 0.11.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- 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 +35 -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 +70 -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 +179 -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 +45 -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 +88 -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 +88 -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 +88 -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 +35 -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 +88 -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 +88 -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,113 @@
|
|
|
1
|
+
---
|
|
2
|
+
icon: door-enter
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# The entry
|
|
6
|
+
|
|
7
|
+
`app/entry.ts` says what runs with the file conventions: the services, what wraps every request, and how failures are answered. Every app has one, and it's yours. spacefn provides the pieces and never adds one you didn't list. The same file runs on Cloudflare and on Bun.
|
|
8
|
+
|
|
9
|
+
```ts [app/entry.ts]
|
|
10
|
+
import { app, databases, errorPage, staticFiles, telemetry } from "spacefn";
|
|
11
|
+
import { platform } from "spacefn/platform";
|
|
12
|
+
|
|
13
|
+
import Env from "#configs/env.ts";
|
|
14
|
+
import { manifest } from "#space/manifest.ts";
|
|
15
|
+
|
|
16
|
+
export default app(manifest, {
|
|
17
|
+
services: [platform(manifest), Env.layer, databases(manifest), telemetry(manifest.name)],
|
|
18
|
+
before: [staticFiles()],
|
|
19
|
+
routes: [],
|
|
20
|
+
onError: errorPage,
|
|
21
|
+
});
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
`manifest` is the file conventions as data, generated from `app/`: the routes and pages, the `_middleware.ts` files, queues, crons and databases. It's a plain object, so the entry can filter it or add to it before passing it on.
|
|
25
|
+
|
|
26
|
+
## `services`
|
|
27
|
+
|
|
28
|
+
The app's services, in order: each layer can use the ones listed before it, and routes, pages, queues and crons can use them all.
|
|
29
|
+
|
|
30
|
+
| Piece | What it gives |
|
|
31
|
+
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
32
|
+
| `platform(manifest)` | The target's `Kv`, `Blob`, `Queue`, `Bus`, `RateLimiter`, an `HttpClient`, and how databases connect. On Cloudflare also the Worker's vars and secrets as config, and `CloudflareEnv`. |
|
|
33
|
+
| `Env.layer` | `configs/env.ts`, read and checked when the app starts. |
|
|
34
|
+
| `databases(manifest)` | Every database in `app/db/`, migrated as its `config.json` says. |
|
|
35
|
+
| `telemetry(manifest.name)` | Traces, logs and metrics over OTLP, once `OTEL_EXPORTER_OTLP_ENDPOINT` is set. See [Deploying](../5-deployment/index.md#telemetry). |
|
|
36
|
+
|
|
37
|
+
Your own services go after them, so they can use everything above:
|
|
38
|
+
|
|
39
|
+
```ts [app/entry.ts]
|
|
40
|
+
import { Mailer } from "#lib/mailer.ts";
|
|
41
|
+
|
|
42
|
+
export default app(manifest, {
|
|
43
|
+
services: [
|
|
44
|
+
platform(manifest),
|
|
45
|
+
Env.layer,
|
|
46
|
+
databases(manifest),
|
|
47
|
+
telemetry(manifest.name),
|
|
48
|
+
Mailer.layer,
|
|
49
|
+
],
|
|
50
|
+
});
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Leave a piece out and it's gone: without `telemetry(...)` nothing is exported, and without `databases(manifest)` no database connects.
|
|
54
|
+
|
|
55
|
+
`spacefn/platform` is the same import on both targets. The spacefn Vite plugin hands it the `platform` of `spacefn/cloudflare` or `spacefn/bun`, by the `target` in `configs/vite.ts`.
|
|
56
|
+
|
|
57
|
+
## `before`
|
|
58
|
+
|
|
59
|
+
Middleware around every request, outside `app/routes/_middleware.ts`. `staticFiles()` serves the client build on Bun; on Cloudflare, the assets are served before the Worker runs, so it lets every request through.
|
|
60
|
+
|
|
61
|
+
## `routes`
|
|
62
|
+
|
|
63
|
+
Effect `HttpRouter` layers beside the file routes, for what a file per URL doesn't fit, such as an `HttpApi` with its OpenAPI document:
|
|
64
|
+
|
|
65
|
+
```ts [app/entry.ts]
|
|
66
|
+
import { HttpRouter, HttpServerResponse } from "effect/http";
|
|
67
|
+
|
|
68
|
+
export default app(manifest, {
|
|
69
|
+
routes: [HttpRouter.add("GET", "/version", Effect.succeed(HttpServerResponse.text("1.4.0")))],
|
|
70
|
+
});
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
They get the same services, `before` and `app/routes/_middleware.ts` as file routes.
|
|
74
|
+
|
|
75
|
+
## `onError`
|
|
76
|
+
|
|
77
|
+
What a failed request answers with, given its `Cause`. `errorPage`, spacefn's, answers the HTTP errors (`NotFound`, `Unauthorized`, ...) with their status: an HTML page for a browser navigation, JSON otherwise. Anything else is logged and answered with an opaque `500`. A URL nothing serves arrives as `NotFound`.
|
|
78
|
+
|
|
79
|
+
```ts [app/entry.ts]
|
|
80
|
+
import { Cause, Effect, Option } from "effect";
|
|
81
|
+
import { HttpServerResponse } from "effect/http";
|
|
82
|
+
import { errorPage, NotFound } from "spacefn";
|
|
83
|
+
|
|
84
|
+
export default app(manifest, {
|
|
85
|
+
onError: (cause) =>
|
|
86
|
+
Option.match(Cause.findErrorOption(cause), {
|
|
87
|
+
onSome: (error) =>
|
|
88
|
+
error instanceof NotFound
|
|
89
|
+
? Effect.succeed(HttpServerResponse.text("Nothing here", { status: 404 }))
|
|
90
|
+
: errorPage(cause),
|
|
91
|
+
onNone: () => errorPage(cause),
|
|
92
|
+
}),
|
|
93
|
+
});
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## Target options
|
|
97
|
+
|
|
98
|
+
`bun` and `cloudflare` hold what only one target reads, so the file stays the same on both:
|
|
99
|
+
|
|
100
|
+
```ts [app/entry.ts]
|
|
101
|
+
export default app(manifest, {
|
|
102
|
+
bun: { port: 8080, hostname: "127.0.0.1", idleTimeout: 120 },
|
|
103
|
+
cloudflare: {
|
|
104
|
+
handlers: {
|
|
105
|
+
email: async (message, env, ctx) => {
|
|
106
|
+
/* ... */
|
|
107
|
+
},
|
|
108
|
+
},
|
|
109
|
+
},
|
|
110
|
+
});
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
`bun.port` defaults to `PORT`, else 3000. `cloudflare.handlers` adds Worker handlers beside the `fetch`, `queue` and `scheduled` that spacefn makes.
|
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
---
|
|
2
|
+
icon: route
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# Routes and middleware
|
|
6
|
+
|
|
7
|
+
## Routes
|
|
8
|
+
|
|
9
|
+
A file in `app/routes/` answers HTTP requests. Give `route` one `Effect` per method. The route reads the request and calls the feature's code in `modules/`, which does the work (see [Conventions](../2-conventions.md#where-code-goes)):
|
|
10
|
+
|
|
11
|
+
```ts [modules/todos/todos.ts]
|
|
12
|
+
import { Effect, Option } from "effect";
|
|
13
|
+
import { NotFound } from "spacefn";
|
|
14
|
+
|
|
15
|
+
import MainDb from "#space/db/main.ts";
|
|
16
|
+
|
|
17
|
+
/** The todo, or a 404. */
|
|
18
|
+
export const find = (id: number) =>
|
|
19
|
+
Effect.flatMap(MainDb.findTodo({ id }), (todo) =>
|
|
20
|
+
Option.isSome(todo)
|
|
21
|
+
? Effect.succeed(todo.value)
|
|
22
|
+
: Effect.fail(new NotFound({ message: `No todo ${id}` })),
|
|
23
|
+
);
|
|
24
|
+
|
|
25
|
+
export const remove = (id: number) => MainDb.deleteTodo({ id });
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
```ts [app/routes/todos/[id].ts]
|
|
29
|
+
import { Effect, Schema } from "effect";
|
|
30
|
+
import { Input, route } from "spacefn";
|
|
31
|
+
|
|
32
|
+
import * as Todos from "#modules/todos/todos.ts";
|
|
33
|
+
|
|
34
|
+
// /todos/:id
|
|
35
|
+
const id = Effect.map(Input.params(Schema.Struct({ id: Schema.FiniteFromString })), (p) => p.id);
|
|
36
|
+
|
|
37
|
+
export default route({
|
|
38
|
+
GET: Effect.flatMap(id, Todos.find),
|
|
39
|
+
DELETE: Effect.flatMap(id, Todos.remove),
|
|
40
|
+
});
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
What the handler returns becomes the response:
|
|
44
|
+
|
|
45
|
+
| Returned | Response |
|
|
46
|
+
| ---------------------------------------- | ---------------- |
|
|
47
|
+
| a value | JSON |
|
|
48
|
+
| a string | `text/plain` |
|
|
49
|
+
| `` html`...` `` | `text/html` |
|
|
50
|
+
| nothing (`undefined`) | `204 No Content` |
|
|
51
|
+
| an `HttpServerResponse`, `redirect("/")` | sent as it is |
|
|
52
|
+
|
|
53
|
+
A method the file doesn't handle is `405` with an `Allow` header, and an unknown URL is `404`.
|
|
54
|
+
|
|
55
|
+
## Input
|
|
56
|
+
|
|
57
|
+
Read the request with a [Schema](https://effect.website/docs/schema/introduction); input that doesn't decode never reaches your code.
|
|
58
|
+
|
|
59
|
+
- `Input.params(schema)`: path parameters. One that doesn't decode is a `404` (the URL names nothing), not a `400`.
|
|
60
|
+
- `Input.query(schema)`: the query string. Repeated keys arrive as arrays.
|
|
61
|
+
- `Input.body(schema, limits?)`: JSON, a URL-encoded form, or multipart. Files arrive as `Upload`s; check them with the `Upload` schema. Too large is `413`, an unexpected content or file type `415`, anything that doesn't match `400` with the issues listed by field.
|
|
62
|
+
|
|
63
|
+
Use `Schema.FiniteFromString` for numbers in params and forms.
|
|
64
|
+
|
|
65
|
+
## Errors
|
|
66
|
+
|
|
67
|
+
Fail with spacefn's errors and they become their status:
|
|
68
|
+
|
|
69
|
+
| Error | Status |
|
|
70
|
+
| ---------------------- | ----------------------- |
|
|
71
|
+
| `BadRequest` | 400 |
|
|
72
|
+
| `Unauthorized` | 401 |
|
|
73
|
+
| `Forbidden` | 403 |
|
|
74
|
+
| `NotFound` | 404 |
|
|
75
|
+
| `Conflict` | 409 |
|
|
76
|
+
| `PayloadTooLarge` | 413 |
|
|
77
|
+
| `UnsupportedMediaType` | 415 |
|
|
78
|
+
| `TooManyRequests` | 429, with `Retry-After` |
|
|
79
|
+
|
|
80
|
+
The body is JSON, `{ "error": "NotFound", "message": "No todo 7" }`. A browser navigating to a page gets a plain HTML error page with the same status instead. Any other failure or defect is logged with its full cause and answered with an opaque `500`, so internals never reach the client. They're schema-backed tagged errors, so `Effect.catchTag("NotFound", ...)` works.
|
|
81
|
+
|
|
82
|
+
## Middleware
|
|
83
|
+
|
|
84
|
+
A `_middleware.ts` file wraps requests. `next` is the rest of the request: run code before it, change its response after, or answer without it.
|
|
85
|
+
|
|
86
|
+
```ts [app/routes/_middleware.ts]
|
|
87
|
+
import { Effect } from "effect";
|
|
88
|
+
import { HttpServerResponse } from "effect/http";
|
|
89
|
+
import { csrf, middleware } from "spacefn";
|
|
90
|
+
|
|
91
|
+
export default [
|
|
92
|
+
csrf(),
|
|
93
|
+
middleware((next) => Effect.map(next, HttpServerResponse.setHeader("x-frame-options", "DENY"))),
|
|
94
|
+
];
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Export one middleware, or an array that runs in order, the first outermost.
|
|
98
|
+
|
|
99
|
+
- `app/routes/_middleware.ts` wraps every request, pages and routes alike, and the 404 for a URL nothing serves.
|
|
100
|
+
- One in a folder below wraps only the pages and routes in that folder and its subfolders, inside the outer ones. `app/routes/admin/_middleware.ts` guards `/admin/...` and nothing else. The check itself is shared code, in `lib/`:
|
|
101
|
+
|
|
102
|
+
```ts [lib/auth/admin.ts]
|
|
103
|
+
import { Effect, Redacted } from "effect";
|
|
104
|
+
import { HttpServerRequest } from "effect/http";
|
|
105
|
+
import { Unauthorized } from "spacefn";
|
|
106
|
+
|
|
107
|
+
import Env from "#configs/env.ts";
|
|
108
|
+
|
|
109
|
+
/** Fails with a 401 unless the request carries the admin key. */
|
|
110
|
+
export const requireAdmin = Effect.gen(function* () {
|
|
111
|
+
const request = yield* HttpServerRequest.HttpServerRequest;
|
|
112
|
+
if (request.headers["x-admin-key"] !== Redacted.value((yield* Env).ADMIN_KEY))
|
|
113
|
+
return yield* new Unauthorized({ message: "Admins only" });
|
|
114
|
+
});
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
```ts [app/routes/admin/_middleware.ts]
|
|
118
|
+
import { Effect } from "effect";
|
|
119
|
+
import { middleware } from "spacefn";
|
|
120
|
+
|
|
121
|
+
import { requireAdmin } from "#lib/auth/admin.ts";
|
|
122
|
+
|
|
123
|
+
export default middleware((next) => Effect.andThen(requireAdmin, next));
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
A `(group)` folder works too, so `(account)/_middleware.ts` covers its pages without adding to their URLs.
|
|
127
|
+
|
|
128
|
+
### One page or route
|
|
129
|
+
|
|
130
|
+
`handle` wraps a single page or route the same way. A middleware is the function `(next) => ...` itself, so the same value works in both places:
|
|
131
|
+
|
|
132
|
+
```ts [lib/auth/admin.ts]
|
|
133
|
+
export const adminOnly = middleware((next) => Effect.andThen(requireAdmin, next));
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
```ts [app/routes/reports.ts]
|
|
137
|
+
import { adminOnly } from "#lib/auth/admin.ts";
|
|
138
|
+
|
|
139
|
+
export default route({
|
|
140
|
+
handle: adminOnly,
|
|
141
|
+
GET: Reports.list,
|
|
142
|
+
DELETE: Reports.clear,
|
|
143
|
+
});
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
On a route it wraps every method; a method it doesn't handle still gets the `405`. On a page it wraps every request the page answers: the `GET`, and each action. It runs inside the folders' middleware. Written inline, `next` is typed from the option, and two combine as plain functions:
|
|
147
|
+
|
|
148
|
+
```ts
|
|
149
|
+
handle: (next) => adminOnly(Effect.map(next, HttpServerResponse.setHeader("cache-control", "no-store"))),
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
When only one method needs the check, chain it on that method instead: `DELETE: Effect.andThen(requireAdmin, Reports.clear)`.
|
|
153
|
+
|
|
154
|
+
### CSRF
|
|
155
|
+
|
|
156
|
+
New apps have it in `app/routes/_middleware.ts`:
|
|
157
|
+
|
|
158
|
+
```ts
|
|
159
|
+
export default csrf();
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
It refuses state-changing requests (anything but `GET`, `HEAD` and `OPTIONS`) that a browser marks as cross-site, through `Origin` or `Sec-Fetch-Site`, with a `403`. Browsers always send one of them, so that covers login CSRF too. Requests with neither header come from other clients and pass, unless you name your session cookie: with `csrf({ cookie: "session" })`, one that carries it is refused. `origins` lists other origins allowed to post, such as an admin site.
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
---
|
|
2
|
+
icon: file-text
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# Pages
|
|
6
|
+
|
|
7
|
+
A file in `app/routes/` whose default export is a `page(...)` is a server-rendered page. `page` takes a `loader` (what the page needs), `actions` (what its forms do) and `render` (the HTML). The page connects them to the feature's code in `modules/`: what to do with todos, and how they look.
|
|
8
|
+
|
|
9
|
+
```ts [modules/todos/todos.ts]
|
|
10
|
+
import { Effect, Option, Schema } from "effect";
|
|
11
|
+
import { NotFound } from "spacefn";
|
|
12
|
+
|
|
13
|
+
import MainDb from "#space/db/main.ts";
|
|
14
|
+
|
|
15
|
+
export const Rename = Schema.Struct({ id: Schema.FiniteFromString, title: Schema.NonEmptyString });
|
|
16
|
+
|
|
17
|
+
export const find = (id: number) =>
|
|
18
|
+
Effect.flatMap(MainDb.findTodo({ id }), (todo) =>
|
|
19
|
+
Option.isSome(todo)
|
|
20
|
+
? Effect.succeed(todo.value)
|
|
21
|
+
: Effect.fail(new NotFound({ message: `No todo ${id}` })),
|
|
22
|
+
);
|
|
23
|
+
|
|
24
|
+
export const rename = ({ id, title }: typeof Rename.Type) => MainDb.renameTodo({ id, title });
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
```ts [modules/todos/views.ts]
|
|
28
|
+
import { html } from "spacefn";
|
|
29
|
+
|
|
30
|
+
/** A form to rename the todo, posting to `rename`. */
|
|
31
|
+
export const renameForm = (props: {
|
|
32
|
+
readonly todo: { readonly id: number; readonly title: string };
|
|
33
|
+
readonly rename: string;
|
|
34
|
+
}) =>
|
|
35
|
+
html`<form method="post" action="${props.rename}">
|
|
36
|
+
<input type="hidden" name="id" value="${props.todo.id}" />
|
|
37
|
+
<input name="title" value="${props.todo.title}" />
|
|
38
|
+
<button>Rename</button>
|
|
39
|
+
</form>`;
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
```ts [app/routes/todos/[id].ts]
|
|
43
|
+
import { Effect, Schema } from "effect";
|
|
44
|
+
import { action, Input, page, redirect } from "spacefn";
|
|
45
|
+
|
|
46
|
+
import { layout } from "#lib/ui/layout.ts";
|
|
47
|
+
import * as Todos from "#modules/todos/todos.ts";
|
|
48
|
+
import { renameForm } from "#modules/todos/views.ts";
|
|
49
|
+
|
|
50
|
+
// /todos/:id
|
|
51
|
+
export default page({
|
|
52
|
+
loader: Effect.gen(function* () {
|
|
53
|
+
const { id } = yield* Input.params(Schema.Struct({ id: Schema.FiniteFromString }));
|
|
54
|
+
return yield* Todos.find(id);
|
|
55
|
+
}),
|
|
56
|
+
actions: {
|
|
57
|
+
rename: action({
|
|
58
|
+
input: Todos.Rename,
|
|
59
|
+
handler: (todo) => Effect.as(Todos.rename(todo), redirect(`/todos/${todo.id}`)),
|
|
60
|
+
}),
|
|
61
|
+
},
|
|
62
|
+
render: (ctx) =>
|
|
63
|
+
layout(ctx.data.title, renameForm({ todo: ctx.data, rename: ctx.actions.rename.url })),
|
|
64
|
+
});
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Keep `loader` and `actions` before `render`, so TypeScript can type `ctx`. Write the loader with `Effect.gen` or `.pipe`; TypeScript can't infer its type through the data-first `Effect.map(effect, fn)`.
|
|
68
|
+
|
|
69
|
+
## The loader
|
|
70
|
+
|
|
71
|
+
An `Effect` that reads input (`Input.params`, `Input.query`), uses services, and returns `ctx.data`. It can fail with the errors of [Routes](2-routes.md) (`NotFound` is a 404 page), or return a response to answer instead of rendering, such as `redirect("/login")`.
|
|
72
|
+
|
|
73
|
+
## Actions
|
|
74
|
+
|
|
75
|
+
Each action is `action({ method?, input, handler })`, reached at `ctx.actions.<name>.url` (`?__action=<name>` on the page's own URL). Where there's no `ctx`, as in a live action that renders part of the page again, `actionUrl("<name>")` gives the same URL:
|
|
76
|
+
|
|
77
|
+
- **`post`** (the default) decodes the form, a multipart body, or the JSON a Datastar `@post` sends.
|
|
78
|
+
- **`get`** decodes the query string, or the signals of a Datastar `@get`.
|
|
79
|
+
|
|
80
|
+
When the input decodes, `handler` runs. Return a response such as `redirect(...)` to send it, which is right after a form post (the browser then reloads the page with `GET`). Return anything else and the page renders again with it as `ctx.actions.<name>.data`.
|
|
81
|
+
|
|
82
|
+
When the input doesn't decode, the page renders again with status `422` and `ctx.actions.<name>.error`, typed from the action's input. `fields` holds the first message for each field, `issues` every issue with its dotted `path`, and `values` what was sent, so the form can show it back:
|
|
83
|
+
|
|
84
|
+
```ts
|
|
85
|
+
<input name="title" value="${ctx.actions.rename.error?.values.title ?? ctx.data.title}" />
|
|
86
|
+
${ctx.actions.rename.error?.fields.title && html`<p role="alert">${ctx.actions.rename.error.fields.title}</p>`}
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
`ctx.actions.<name>.ok` says whether this render answers a submission of that action: `true` when its handler ran (so a handler that returns nothing still shows as done), `false` when its input didn't decode, and `undefined` otherwise, when `error` and `data` are `undefined` too.
|
|
90
|
+
|
|
91
|
+
### Guarding a page
|
|
92
|
+
|
|
93
|
+
The loader and each action's handler run on separate requests, so a check on the loader alone leaves the actions open. `handle` wraps them all:
|
|
94
|
+
|
|
95
|
+
```ts
|
|
96
|
+
export default page({
|
|
97
|
+
handle: (next) => Effect.andThen(requireAdmin, next),
|
|
98
|
+
loader: ...,
|
|
99
|
+
actions: { ... },
|
|
100
|
+
render: ...,
|
|
101
|
+
});
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
It takes the same function as `middleware(...)`, so a middleware from `lib/` works too. See [one page or route](2-routes.md#one-page-or-route).
|
|
105
|
+
|
|
106
|
+
## HTML
|
|
107
|
+
|
|
108
|
+
`` html`...` `` escapes every value, so user input is safe to interpolate. Arrays render each item, and `null`, `undefined` and `false` render nothing. `raw(string)` inserts markup you trust as it is. Routes can return `html` too.
|
|
109
|
+
|
|
110
|
+
`once(markup)` outputs its markup only where it first appears in the response, like Laravel's `@once`: a component that needs a script can include it, and a page with three of them sends one. Its key is the markup itself; `once("key", markup)` names it instead.
|
|
111
|
+
|
|
112
|
+
```ts
|
|
113
|
+
const datePicker = (name: string) =>
|
|
114
|
+
html`${once(html`<script type="module" src="/date-picker.js"></script>`)}
|
|
115
|
+
<input name="${name}" type="text" />`;
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
## Scripts, styles and public files
|
|
119
|
+
|
|
120
|
+
A page loads the browser code it needs with `assets("name")`, for the entries in `app/assets/`. [Frontend](4-frontend.md) covers them, `public/`, CSS, client components from React, Vue, Solid or Svelte, and how to write Datastar components.
|
|
121
|
+
|
|
122
|
+
## Live updates with Datastar
|
|
123
|
+
|
|
124
|
+
Pages speak [Datastar](https://data-star.dev): the new app's layout loads its client from a CDN (or install it and import it from `app/assets/`). A `get` action that returns `Datastar.watch(topics, render)` keeps part of the page current:
|
|
125
|
+
|
|
126
|
+
```ts
|
|
127
|
+
live: action({
|
|
128
|
+
method: "get",
|
|
129
|
+
input: Schema.Struct({}),
|
|
130
|
+
handler: () => Datastar.watch(["todos"], todoList),
|
|
131
|
+
}),
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
```ts
|
|
135
|
+
html`<main data-init="@get('${ctx.actions.live.url}')">${ctx.data.list}</main>`;
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
When the page loads, Datastar opens the action. `watch` subscribes to the `todos` topic on the [Bus](6-services.md), sends `todoList`'s HTML, and sends it again after each message, until the tab closes. Datastar swaps elements in by `id`, so give the rendered elements one. Anything that changes the todos publishes the topic, from a page, a route, a queue consumer or a cron:
|
|
139
|
+
|
|
140
|
+
```ts
|
|
141
|
+
yield * Bus.publish("todos", "changed");
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
A burst of messages causes one re-render. How to name the ids and signals, and split the markup into components, is in [Frontend](4-frontend.md#datastar). For more control, `Datastar.sse(stream)` sends your own events, built with `Datastar.patchElements`, `removeElements`, `patchSignals` and `executeScript`. `Datastar.signals(schema)` decodes the signals a request sent, and `Datastar.isRequest` tells a Datastar request from a plain one.
|
|
145
|
+
|
|
146
|
+
## Error pages
|
|
147
|
+
|
|
148
|
+
When a browser navigates to a page and the loader fails, it gets a small HTML page with the status, such as "404 Not Found", and the error's message. Datastar requests, `fetch` and API clients get the JSON error instead. A custom error page isn't supported yet; until then, catch the error in the loader and render your own.
|
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
---
|
|
2
|
+
icon: palette
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# Frontend
|
|
6
|
+
|
|
7
|
+
Pages are server-rendered `html` (see [Pages](3-pages.md)). What runs in the browser is bundled by Vite from `app/assets/`, and each page loads only what it uses. Every section below has a tested app in `examples/`, which also ships in `node_modules/spacefn-docs/examples/`.
|
|
8
|
+
|
|
9
|
+
## Where browser code goes
|
|
10
|
+
|
|
11
|
+
The same split as the rest of the app (see [Conventions](../2-conventions.md#where-code-goes)):
|
|
12
|
+
|
|
13
|
+
```txt
|
|
14
|
+
my-app/
|
|
15
|
+
├── app/
|
|
16
|
+
│ └── assets/
|
|
17
|
+
│ ├── main.ts an entry: imports from modules/ and lib/, and starts them
|
|
18
|
+
│ └── site.css an entry: @imports the stylesheets
|
|
19
|
+
├── modules/
|
|
20
|
+
│ └── <feature>/
|
|
21
|
+
│ ├── ui/ its client components; Name.island.tsx files are islands
|
|
22
|
+
│ ├── client/ its other browser code, such as web components
|
|
23
|
+
│ └── <feature>.css its styles
|
|
24
|
+
├── lib/
|
|
25
|
+
│ └── ui/ the UI kit: layout, components, design tokens
|
|
26
|
+
└── public/ files served as they are at /
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
An entry is each file directly in `app/assets/`, named after the file: `app/assets/main.ts` is `main`. Keep entries to a few lines, so the code itself lives with its feature:
|
|
30
|
+
|
|
31
|
+
```ts [app/assets/main.ts]
|
|
32
|
+
import { definePollMeter } from "#modules/poll/client/poll-meter.ts";
|
|
33
|
+
|
|
34
|
+
definePollMeter();
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
```css [app/assets/site.css]
|
|
38
|
+
@import "#lib/ui/base.css";
|
|
39
|
+
@import "#modules/todos/todos.css";
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
`#lib/...` and `#modules/...` imports work in CSS too.
|
|
43
|
+
|
|
44
|
+
## Loading entries
|
|
45
|
+
|
|
46
|
+
`assets(...)` from `spacefn/assets` gives the `<script>` and `<link>` tags of the entries you name, in that order. The layout loads what every page needs; a page that needs more passes its own, so a heavy script is only downloaded where it's used:
|
|
47
|
+
|
|
48
|
+
```ts [lib/ui/layout.ts]
|
|
49
|
+
import { html, type HtmlValue } from "spacefn";
|
|
50
|
+
import { assets } from "spacefn/assets";
|
|
51
|
+
|
|
52
|
+
export const layout = (title: string, body: HtmlValue, head: HtmlValue = "") =>
|
|
53
|
+
html`<!doctype html>
|
|
54
|
+
<html lang="en">
|
|
55
|
+
<head>
|
|
56
|
+
<title>${title}</title>
|
|
57
|
+
${assets("site")} ${head}
|
|
58
|
+
</head>
|
|
59
|
+
<body>
|
|
60
|
+
${body}
|
|
61
|
+
</body>
|
|
62
|
+
</html>`;
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
```ts [app/routes/index.ts]
|
|
66
|
+
render: (ctx) => layout("Sales", salesPage(ctx.data), assets("charts")),
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
In dev the tags point at the sources, after Vite's client and what plugins add to a page's head (React's refresh preamble, for one). In a build they point at the hashed files, with their CSS and preloads. A tag two entries share comes once. The names are typed: `assets("mian")` is a type error, and so is loading an entry that was deleted.
|
|
70
|
+
|
|
71
|
+
## Public files
|
|
72
|
+
|
|
73
|
+
Files in `public/`, at the app root, are served as they are at `/`: `public/favicon.svg` is `/favicon.svg`. They are copied into the build and, on both targets, answered before the app runs, so a public file at a route's URL is an error from `space gen`. Put files there that need a fixed URL (icons, `robots.txt`, images linked from elsewhere); import the rest from `app/assets/`, so they get hashed names.
|
|
74
|
+
|
|
75
|
+
## CSS
|
|
76
|
+
|
|
77
|
+
Plain CSS works as it is: Vite bundles each stylesheet entry and its `@import`s.
|
|
78
|
+
|
|
79
|
+
**Lightning CSS.** Set it as Vite's CSS transformer in `configs/vite.ts` to write nesting, custom media and `light-dark()`, lowered for the browsers you target. See `examples/lightningcss`.
|
|
80
|
+
|
|
81
|
+
```ts [configs/vite.ts]
|
|
82
|
+
export default defineConfig({
|
|
83
|
+
css: {
|
|
84
|
+
transformer: "lightningcss",
|
|
85
|
+
lightningcss: {
|
|
86
|
+
targets: { chrome: 109 << 16, firefox: 115 << 16, safari: 15 << 16 },
|
|
87
|
+
drafts: { customMedia: true },
|
|
88
|
+
},
|
|
89
|
+
},
|
|
90
|
+
build: { cssMinify: "lightningcss" },
|
|
91
|
+
plugins: [space({ target: "bun" })],
|
|
92
|
+
});
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
**Tailwind.** Add its Vite plugin beside spacefn's, and import it from the stylesheet that holds your theme. Tailwind finds the classes in every file that isn't gitignored, so `app/`, `modules/` and `lib/` all count. Write class names out in full in components, so it sees them. See `examples/tailwind`.
|
|
96
|
+
|
|
97
|
+
```ts [configs/vite.ts]
|
|
98
|
+
import tailwindcss from "@tailwindcss/vite";
|
|
99
|
+
|
|
100
|
+
export default defineConfig({ plugins: [tailwindcss(), space({ target: "bun" })] });
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
```css [lib/ui/theme.css]
|
|
104
|
+
@import "tailwindcss";
|
|
105
|
+
|
|
106
|
+
@theme {
|
|
107
|
+
--color-brand-600: oklch(52% 0.2 265);
|
|
108
|
+
}
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
## Client components
|
|
112
|
+
|
|
113
|
+
A component from React, Vue, Solid or Svelte runs as an island: a page renders an element with the component's props, and the browser starts the component in it. The component isn't rendered on the server; the island starts empty and fills in once its script runs.
|
|
114
|
+
|
|
115
|
+
1. Add the framework's Vite plugin beside spacefn's in `configs/vite.ts`.
|
|
116
|
+
2. Name the component's file `<Name>.island.<ext>` and export the component as its default. The file's name is the island's:
|
|
117
|
+
|
|
118
|
+
```tsx [modules/shop/ui/Cart.island.tsx]
|
|
119
|
+
import type { Product } from "../products.ts";
|
|
120
|
+
|
|
121
|
+
export default function Cart({ products }: { readonly products: readonly Product[] }) {
|
|
122
|
+
// ...
|
|
123
|
+
}
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
3. Render it from the page's view with `island(name, props)` from `#space/islands.ts`. The names and the props are checked against the components:
|
|
127
|
+
|
|
128
|
+
```ts [modules/shop/views.ts]
|
|
129
|
+
import { island } from "#space/islands.ts";
|
|
130
|
+
|
|
131
|
+
export const shopPage = (products: readonly Product[]) =>
|
|
132
|
+
html`<main>${island("Cart", { products })}</main>`;
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Codegen writes what's in between, into `.space/`, where you can read it:
|
|
136
|
+
|
|
137
|
+
```txt
|
|
138
|
+
.space/
|
|
139
|
+
├── islands.ts island(name, props), with each component's props
|
|
140
|
+
└── islands/
|
|
141
|
+
└── Cart.ts the browser entry: starts Cart in its elements, and stops it when one is removed
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
`island` writes `<spacefn-island name="Cart">` with the props as JSON inside, then the island's `<script>` through [`once`](3-pages.md#html), so a page with three carts loads it once and pages without one don't load it. Nothing goes in `app/assets/` or `assets(...)`: each island is an entry of its own. In the browser, the entry starts the component in every element with its name, also in ones added later, as by a Datastar patch. The server only imports the components' types, so the framework never runs there.
|
|
145
|
+
|
|
146
|
+
The extension says which framework starts the component:
|
|
147
|
+
|
|
148
|
+
| File | Framework | Plugin | Example |
|
|
149
|
+
| --------------- | ---------------------------------------- | ------------------------------------------------------------------- | ----------------- |
|
|
150
|
+
| `.tsx` / `.jsx` | React, if `package.json` has `react-dom` | `react()` from `@vitejs/plugin-react` | `examples/react` |
|
|
151
|
+
| `.tsx` / `.jsx` | Solid, if `package.json` has `solid-js` | `solid()` from `vite-plugin-solid` | `examples/solid` |
|
|
152
|
+
| `.vue` | Vue | `vue()` from `@vitejs/plugin-vue` | `examples/vue` |
|
|
153
|
+
| `.svelte` | Svelte | `svelte({ configFile: false })` from `@sveltejs/vite-plugin-svelte` | `examples/svelte` |
|
|
154
|
+
| `.ts` / `.js` | yours: the default export starts it | | |
|
|
155
|
+
|
|
156
|
+
A `.ts` island starts the component itself, for what the others don't cover: a Vue plugin, React's root options, Preact or Lit, or plain DOM code. It exports `(element, props) => stop`:
|
|
157
|
+
|
|
158
|
+
```ts [modules/chat/ui/Chat.island.ts]
|
|
159
|
+
import { createPinia } from "pinia";
|
|
160
|
+
import { createApp } from "vue";
|
|
161
|
+
|
|
162
|
+
import Chat from "./Chat.vue";
|
|
163
|
+
|
|
164
|
+
export default (element: HTMLElement, props: { room: string }) => {
|
|
165
|
+
const app = createApp(Chat, props).use(createPinia());
|
|
166
|
+
app.mount(element);
|
|
167
|
+
return () => app.unmount();
|
|
168
|
+
};
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
Names are unique in the app, whatever their folders, and codegen says where two clash. A `.tsx` island in an app with both `react-dom` and `solid-js` is an error; write it as a `.ts` island. The props must survive JSON. Put what the server and the component share, such as types and formatting, in a file that imports nothing server-only (`modules/shop/products.ts`).
|
|
172
|
+
|
|
173
|
+
For `.tsx`, set `jsx` in `configs/tsconfig.json` (`react-jsx`, or `preserve` with `jsxImportSource: "solid-js"`). `tsc` doesn't read `.vue` or `.svelte` files: the examples declare them in `lib/types/`, so `tsc` takes any props for those islands, and `vue-tsc` or `svelte-check` checks them. With Solid, set Vitest's `environment: "node"` in `configs/vitest.ts`, since its plugin switches it to jsdom.
|
|
174
|
+
|
|
175
|
+
## Datastar
|
|
176
|
+
|
|
177
|
+
[Datastar](https://data-star.dev) adds behavior to server-rendered HTML with `data-*` attributes, and the server answers its requests by patching elements and signals (see [Pages](3-pages.md#live-updates-with-datastar)). These conventions keep the markup and the server in step; `examples/datastar` uses all of them.
|
|
178
|
+
|
|
179
|
+
**Components are functions from props to `html`**, in `modules/<feature>/views.ts`, or `lib/ui/` when every feature uses them. They take what they show and the URLs they call as props, not the page's `ctx`, so a live update can render them too:
|
|
180
|
+
|
|
181
|
+
```ts [modules/poll/views.ts]
|
|
182
|
+
export const results = (props: { readonly results: readonly Result[] }) =>
|
|
183
|
+
html`<ol id="${results.id}">
|
|
184
|
+
${props.results.map((result) => html`<li>${result.label}: ${result.percent}%</li>`)}
|
|
185
|
+
</ol>`;
|
|
186
|
+
results.id = "poll-results";
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
**An element Datastar patches has a fixed `id`, exported beside its component**, as `results.id` above. Datastar morphs elements in by id, so the page's first render and every update use the same one.
|
|
190
|
+
|
|
191
|
+
**Signals live under the feature's name.** Declare them once, on the feature's root element, and read them as `$poll.choice`. Two features on one page then can't overwrite each other's:
|
|
192
|
+
|
|
193
|
+
```ts
|
|
194
|
+
html`<main data-signals="{poll: {choice: '', voted: ''}}">...</main>`;
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
**Actions are the page's actions.** `@get` and `@post` send every signal: a `get` action receives them as its input, and so does a `post` one, from the JSON body. Decode them with a Schema shaped like the signals, and answer with what to patch:
|
|
198
|
+
|
|
199
|
+
```ts
|
|
200
|
+
vote: action({
|
|
201
|
+
input: Schema.Struct({ poll: Schema.Struct({ choice: Schema.Literals(["tabs", "spaces"]) }) }),
|
|
202
|
+
handler: ({ poll }) =>
|
|
203
|
+
Effect.andThen(
|
|
204
|
+
Poll.vote(poll.choice),
|
|
205
|
+
Datastar.sse([Datastar.patchSignals({ poll: { voted: poll.choice } })]),
|
|
206
|
+
),
|
|
207
|
+
}),
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
```ts
|
|
211
|
+
html`<button data-on:click="$poll.choice = 'tabs'; @post('${props.vote}')">Tabs</button>`;
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
Outside `render`, where there's no `ctx`, `actionUrl("vote")` gives the same URL as `ctx.actions.vote.url`.
|
|
215
|
+
|
|
216
|
+
**Web components with Rocket.** For a reusable element with its own state and styles, Datastar's [Rocket](https://data-star.dev/reference/rocket) defines custom elements whose templates use Datastar attributes. Put each in `modules/<feature>/client/<name>.ts`, name it after the feature (`poll-meter`), and register it from an entry. Rocket is in beta and comes in the `datastar-rocket.js` bundle, which includes Datastar, so load it in place of `datastar.js`; check its license before you ship it. TypeScript has no types for an import from a URL, so declare that module once for the whole app, in `lib/types/rocket.d.ts` (`examples/datastar` has one).
|
|
217
|
+
|
|
218
|
+
```ts [modules/poll/client/poll-meter.ts]
|
|
219
|
+
import { rocket } from "https://cdn.jsdelivr.net/gh/starfederation/datastar@v1.0.5/bundles/datastar-rocket.js";
|
|
220
|
+
|
|
221
|
+
export const definePollMeter = () =>
|
|
222
|
+
rocket("poll-meter", {
|
|
223
|
+
props: ({ number, string }) => ({
|
|
224
|
+
label: string.trim.default(""),
|
|
225
|
+
value: number.clamp(0, 100).default(0),
|
|
226
|
+
}),
|
|
227
|
+
render: ({ html, props: { label, value } }) =>
|
|
228
|
+
html`<span>${label}</span> <span>${value}%</span>`,
|
|
229
|
+
});
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
The server renders `<poll-meter label="Tabs" value="40">`, and when a live update morphs new attributes in, the element renders again.
|