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,57 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: configs/
|
|
3
|
+
icon: settings
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# configs/
|
|
7
|
+
|
|
8
|
+
The tools' settings, kept out of the app root. Each file is the tool's own format, so what you know about Vite, Vitest and TypeScript applies as is.
|
|
9
|
+
|
|
10
|
+
```txt
|
|
11
|
+
configs/
|
|
12
|
+
├── env.ts the variables the app reads, checked at start
|
|
13
|
+
├── vite.ts Vite, with spacefn's plugin and the target
|
|
14
|
+
├── vitest.ts Vitest, merging vite.ts
|
|
15
|
+
├── tsconfig.json TypeScript; the root tsconfig.json extends it
|
|
16
|
+
├── infra.ts what a deploy creates: a plain Alchemy stack
|
|
17
|
+
├── Dockerfile the image a Bun deploy builds (Bun only)
|
|
18
|
+
└── Dockerfile.dockerignore what stays out of that image
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## `vite.ts`
|
|
22
|
+
|
|
23
|
+
spacefn is a plugin here, and `target` says where the app runs. Add other plugins beside it:
|
|
24
|
+
|
|
25
|
+
```ts [configs/vite.ts]
|
|
26
|
+
import tailwindcss from "@tailwindcss/vite";
|
|
27
|
+
import { space } from "spacefn/vite";
|
|
28
|
+
import { defineConfig } from "vite";
|
|
29
|
+
|
|
30
|
+
export default defineConfig({ plugins: [tailwindcss(), space({ target: "cloudflare" })] });
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## `env.ts`
|
|
34
|
+
|
|
35
|
+
The variables the app reads, each with its type. A missing or invalid one stops the app at start, naming it:
|
|
36
|
+
|
|
37
|
+
```ts [configs/env.ts]
|
|
38
|
+
import { defineEnv, Env } from "spacefn";
|
|
39
|
+
|
|
40
|
+
export default defineEnv({
|
|
41
|
+
SITE_URL: Env.url(),
|
|
42
|
+
STRIPE_KEY: Env.secret(),
|
|
43
|
+
MAX_TODOS: Env.int({ default: 100 }),
|
|
44
|
+
});
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Read it in code with `const env = yield* Env` (imported from `#configs/env.ts`). Deploys import this file to know what to pass on, so import only `spacefn` and `effect` in it.
|
|
48
|
+
|
|
49
|
+
## `infra.ts`
|
|
50
|
+
|
|
51
|
+
The app's infrastructure as a plain [Alchemy](https://alchemy.run) stack: what `space deploy` creates and, on Cloudflare, what `space dev` runs locally. It loops over what `app/` asks for, from `#space/infra.ts`, and is yours to change: add a domain, remove the R2 bucket you don't use.
|
|
52
|
+
|
|
53
|
+
## `tsconfig.json` and `vitest.ts`
|
|
54
|
+
|
|
55
|
+
`include` lists `app/`, `lib/`, `modules/` and `configs/`; add a folder there if you make another. `vitest.ts` merges `vite.ts`, so tests run with the same plugins, and finds `*.test.ts` in `app/`, `modules/` and `lib/`.
|
|
56
|
+
|
|
57
|
+
Read more in [Configuration](../7-reference/1-config.md).
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: .space/
|
|
3
|
+
icon: wand
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# .space/
|
|
7
|
+
|
|
8
|
+
What spacefn generates from `app/`: plain TypeScript you can read, but never edit. `space gen` writes it, `npm install` runs that, and `space dev` rewrites it on every change. It's in `.gitignore`.
|
|
9
|
+
|
|
10
|
+
```txt
|
|
11
|
+
.space/
|
|
12
|
+
├── manifest.ts the routes, middleware, queues, crons and databases, as data
|
|
13
|
+
├── db/
|
|
14
|
+
│ └── main.ts MainDb: the typed queries of app/db/main/
|
|
15
|
+
├── assets.d.ts the names assets(...) accepts, from app/assets/
|
|
16
|
+
├── islands.ts island(name, props), from the *.island.* files
|
|
17
|
+
├── islands/
|
|
18
|
+
│ └── Cart.ts an island's browser entry, starting its component
|
|
19
|
+
├── entry.ts the target's entry, running app/entry.ts
|
|
20
|
+
├── infra.ts what configs/infra.ts creates, as plain data
|
|
21
|
+
├── vite.config.ts points Vite at configs/vite.ts
|
|
22
|
+
└── data/ local databases and blobs under space dev (Bun)
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
You import four of them:
|
|
26
|
+
|
|
27
|
+
| Import | What it gives |
|
|
28
|
+
| --------------------- | --------------------------------------------- |
|
|
29
|
+
| `#space/manifest.ts` | `manifest`, for `app(...)` and `testApp(...)` |
|
|
30
|
+
| `#space/db/<name>.ts` | the database class, such as `MainDb` |
|
|
31
|
+
| `#space/islands.ts` | `island(name, props)`, for client components |
|
|
32
|
+
| `#space/infra.ts` | `app`, for `configs/infra.ts` |
|
|
33
|
+
|
|
34
|
+
If something in it looks wrong, the cause is in `app/` or `configs/`: fix it there and run `space gen`, which reports errors with the file and a hint. `space clean` deletes it, keeping the local data.
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: .env
|
|
3
|
+
icon: key
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# .env
|
|
7
|
+
|
|
8
|
+
Values for the variables in [`configs/env.ts`](6-configs.md#envts), one file per place the app runs:
|
|
9
|
+
|
|
10
|
+
```txt
|
|
11
|
+
my-app/
|
|
12
|
+
├── .env.example committed: every variable, with safe example values
|
|
13
|
+
├── .env your machine: space dev and space db
|
|
14
|
+
├── .env.staging space deploy --stage staging
|
|
15
|
+
└── .env.prod space deploy (the default stage, prod)
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
```sh [.env]
|
|
19
|
+
SITE_URL=http://localhost:3000
|
|
20
|
+
STRIPE_KEY=sk_test_...
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
A deploy reads only `.env.<stage>`, never `.env`, so local values can't reach production. Variables already set in the environment, as CI sets them, are passed on too, so CI needs no file.
|
|
24
|
+
|
|
25
|
+
Commit `.env.example` only: the scaffolded `.gitignore` keeps every other `.env` file out of git. A new teammate copies it to `.env`.
|
|
26
|
+
|
|
27
|
+
Besides your own, spacefn reads a few:
|
|
28
|
+
|
|
29
|
+
| Variable | What it's for |
|
|
30
|
+
| ---------------------------------------------- | ----------------------------------------------------------------------------------- |
|
|
31
|
+
| `DB_<NAME>_URL`, `DB_<NAME>_AUTH_TOKEN` | a libSQL database: Turso, `sqld`, or a `file:` |
|
|
32
|
+
| `SPACE_STATE_URL`, `SPACE_STATE_AUTH_TOKEN` | the state database on Bun |
|
|
33
|
+
| `OTEL_EXPORTER_OTLP_ENDPOINT`, `_HEADERS` | where traces, logs and metrics go |
|
|
34
|
+
| `PORT`, `HOST`, `SPACE_DATA_DIR`, `SPACE_ROLE` | the Bun server; see [Bun](../5-deployment/2-bun.md) |
|
|
35
|
+
| `SPACE_DEV_PORT` | `space dev --port` on Cloudflare; see [Cloudflare](../5-deployment/1-cloudflare.md) |
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: package.json
|
|
3
|
+
icon: package
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# package.json
|
|
7
|
+
|
|
8
|
+
The app's name, scripts, dependencies, and the `#` imports that every tool reads.
|
|
9
|
+
|
|
10
|
+
```json [package.json]
|
|
11
|
+
{
|
|
12
|
+
"name": "my-app",
|
|
13
|
+
"private": true,
|
|
14
|
+
"type": "module",
|
|
15
|
+
"imports": {
|
|
16
|
+
"#configs/*": "./configs/*",
|
|
17
|
+
"#lib/*": "./lib/*",
|
|
18
|
+
"#modules/*": "./modules/*",
|
|
19
|
+
"#space/*": "./.space/*"
|
|
20
|
+
},
|
|
21
|
+
"scripts": {
|
|
22
|
+
"postinstall": "space gen",
|
|
23
|
+
"dev": "space dev",
|
|
24
|
+
"build": "space build",
|
|
25
|
+
"deploy": "space deploy",
|
|
26
|
+
"docs": "space docs",
|
|
27
|
+
"test": "vitest run --config configs/vitest.ts",
|
|
28
|
+
"typecheck": "tsc --noEmit"
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
- **`name`** names the Worker, the container and the deploy's resources.
|
|
34
|
+
- **`imports`** are Node's [subpath imports](https://nodejs.org/api/packages.html#subpath-imports): Node, TypeScript, Vite, Vitest and Bun all read them, so nothing else needs configuring. Add one for a folder of your own, such as `"#ui/*": "./src/ui/*"`.
|
|
35
|
+
- **`postinstall`** runs `space gen`, so `.space/` exists after `npm install`, in CI too.
|
|
36
|
+
|
|
37
|
+
The dependencies are `spacefn` and `effect`; the dev dependencies Vite, Vitest, TypeScript, Alchemy and its provider for the target, and `spacefn-docs`, which holds these docs and the examples, for you and your agents to read in `node_modules/spacefn-docs/`. [`space upgrade`](../7-reference/2-cli.md#upgrading) updates spacefn, the docs, Alchemy and what they need newer together.
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
---
|
|
2
|
+
icon: folders
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# Folders
|
|
6
|
+
|
|
7
|
+
A spacefn app is a folder, and where a file sits says what it is. This section has a page for each folder and file of an app: what goes in it, how its files are named, and an example. Browse it like a map of the app.
|
|
8
|
+
|
|
9
|
+
```txt
|
|
10
|
+
my-app/
|
|
11
|
+
├── app/ what spacefn reads: wiring only
|
|
12
|
+
│ ├── entry.ts the services, what wraps every request, onError
|
|
13
|
+
│ ├── routes/ pages and HTTP endpoints, by URL
|
|
14
|
+
│ ├── db/ one folder per database: SQL migrations and queries
|
|
15
|
+
│ ├── queues/ one consumer per queue
|
|
16
|
+
│ ├── crons/ one scheduled job per file
|
|
17
|
+
│ ├── assets/ browser entries, bundled by Vite
|
|
18
|
+
│ ├── durable-objects/ Durable Object classes (Cloudflare)
|
|
19
|
+
│ └── workflows/ Workflow classes (Cloudflare)
|
|
20
|
+
├── modules/ one folder per feature: logic, views, client code, tests
|
|
21
|
+
├── lib/ what features share: UI kit, helpers, services
|
|
22
|
+
├── public/ files served as they are at /
|
|
23
|
+
├── docs/ notes on this app, in the docs reader
|
|
24
|
+
├── configs/ Vite, Vitest, TypeScript, env and infra settings
|
|
25
|
+
├── .space/ generated from app/; never edited
|
|
26
|
+
├── .env local variables; .env.<stage> for deploys
|
|
27
|
+
└── package.json scripts, dependencies and #imports
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
| Folder or file | What it is |
|
|
31
|
+
| ---------------------------------------------------- | ------------------------------------------------ |
|
|
32
|
+
| [`app/`](1-app/index.md) | What spacefn reads, and nothing else |
|
|
33
|
+
| [`app/entry.ts`](1-app/1-entry.md) | The app: services, `before`, `routes`, `onError` |
|
|
34
|
+
| [`app/routes/`](1-app/2-routes.md) | A file per URL: pages, routes, `_middleware.ts` |
|
|
35
|
+
| [`app/db/`](1-app/3-db.md) | Databases: config, migrations and typed queries |
|
|
36
|
+
| [`app/queues/`](1-app/4-queues.md) | Queue consumers |
|
|
37
|
+
| [`app/crons/`](1-app/5-crons.md) | Scheduled jobs |
|
|
38
|
+
| [`app/assets/`](1-app/6-assets.md) | Scripts and stylesheets for the browser |
|
|
39
|
+
| [`app/durable-objects/`](1-app/7-durable-objects.md) | Durable Objects, on Cloudflare |
|
|
40
|
+
| [`app/workflows/`](1-app/8-workflows.md) | Workflows, on Cloudflare |
|
|
41
|
+
| [`modules/`](2-modules.md) | The app's features |
|
|
42
|
+
| [`lib/`](3-lib.md) | Code the features share |
|
|
43
|
+
| [`public/`](4-public.md) | Static files at fixed URLs |
|
|
44
|
+
| [`docs/`](5-docs.md) | The app's own docs |
|
|
45
|
+
| [`configs/`](6-configs.md) | Tool settings, env and infra |
|
|
46
|
+
| [`.space/`](7-space.md) | Generated code |
|
|
47
|
+
| [`.env`](8-env.md) | Variables for dev and for each deploy stage |
|
|
48
|
+
| [`package.json`](9-package-json.md) | Scripts, dependencies, `#` imports |
|
|
49
|
+
|
|
50
|
+
Only `app/` has rules spacefn checks. `modules/` and `lib/` are the layout the docs, the new app and the examples use, so every kind of code has one place to look; see [Best practices](../3-best-practices.md).
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
---
|
|
2
|
+
icon: brand-cloudflare
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# Cloudflare
|
|
6
|
+
|
|
7
|
+
On Cloudflare, one Worker serves the pages and routes, consumes the queues and runs the crons. The client build is served as static assets in front of it.
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
space deploy
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
The first deploy asks you to sign in to Cloudflare in the browser. In CI, set `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` instead; see [CI/CD](4-ci-cd.md). To deploy on push from the Cloudflare dashboard, see [Cloudflare dashboard](4-ci-cd.md#cloudflare-dashboard).
|
|
14
|
+
|
|
15
|
+
## What it creates
|
|
16
|
+
|
|
17
|
+
The scaffolded `configs/infra.ts` creates, for each stage:
|
|
18
|
+
|
|
19
|
+
| From | Resource |
|
|
20
|
+
| ------------------------------ | -------------------------------------------------------------------- |
|
|
21
|
+
| the app | a Worker, with the client build as its assets |
|
|
22
|
+
| `app/db/<name>/` with `d1` | a D1 database, migrated when the Worker starts |
|
|
23
|
+
| `app/db/<name>/` with `libsql` | nothing: it reads `DB_<NAME>_URL` and `DB_<NAME>_AUTH_TOKEN` |
|
|
24
|
+
| `app/queues/<name>.ts` | a queue named `<app>-<stage>-<name>`, and the Worker as its consumer |
|
|
25
|
+
| `app/crons/` | a Cron Trigger per schedule |
|
|
26
|
+
| `app/durable-objects/` | a Durable Object binding per class |
|
|
27
|
+
| `app/workflows/` | a Workflow per class |
|
|
28
|
+
| `Kv`, `Blob` | a KV namespace and an R2 bucket |
|
|
29
|
+
| `Bus`, `RateLimiter` | the Durable Objects behind them |
|
|
30
|
+
| `configs/env.ts` | vars, and Worker secrets for `Env.secret()` fields |
|
|
31
|
+
|
|
32
|
+
Queue names are unique per account, so they carry the app and the stage. Remove what the app doesn't use, such as the R2 bucket, and add what it needs beside the rest.
|
|
33
|
+
|
|
34
|
+
## A domain
|
|
35
|
+
|
|
36
|
+
Give the Worker a domain in `configs/infra.ts`; the zone must be in the same account:
|
|
37
|
+
|
|
38
|
+
```ts [configs/infra.ts]
|
|
39
|
+
const worker =
|
|
40
|
+
yield *
|
|
41
|
+
Cloudflare.Website.Vite("Worker", {
|
|
42
|
+
// ...
|
|
43
|
+
domain: stage === "prod" ? "todo.example.com" : `${stage}.todo.example.com`,
|
|
44
|
+
});
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Locally
|
|
48
|
+
|
|
49
|
+
`space dev` runs the same stack with `alchemy dev`: the Worker in workerd, with local D1, KV, R2, queues, Durable Objects and workflows. No account is needed, and the local state stays on your machine.
|
|
50
|
+
|
|
51
|
+
It serves on port 1337, or the next free one. `space dev --port 3000` sets `SPACE_DEV_PORT`, which `configs/infra.ts` gives to the Worker; that port must be free:
|
|
52
|
+
|
|
53
|
+
```ts [configs/infra.ts]
|
|
54
|
+
const devPort = process.env.SPACE_DEV_PORT;
|
|
55
|
+
const worker =
|
|
56
|
+
yield *
|
|
57
|
+
Cloudflare.Website.Vite("Worker", {
|
|
58
|
+
// ...
|
|
59
|
+
dev: devPort ? { port: Number(devPort), strictPort: true } : undefined,
|
|
60
|
+
});
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
An app made with spacefn 0.11.0 or earlier doesn't have these lines yet. Add them to use `--port`; until then `space dev --port` says they're missing.
|
|
64
|
+
|
|
65
|
+
## Things to know
|
|
66
|
+
|
|
67
|
+
- **D1 has no transactions.** spacefn runs a migration, or other atomic work, as one batch.
|
|
68
|
+
- **KV is eventually consistent**, and keeps a value for at least 60 seconds; shorter TTLs are raised to 60.
|
|
69
|
+
- **State.** Alchemy keeps what each stage deployed in your Cloudflare account (`Cloudflare.state()`), so a deploy from CI and one from your machine see the same thing.
|
|
70
|
+
- **Bindings spacefn doesn't wrap**, such as Workers AI, are added in `configs/infra.ts` and read with `CloudflareEnv` from `spacefn/cloudflare`. `space doctor` names a binding that `app/` needs and the stack doesn't give.
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
---
|
|
2
|
+
icon: brand-docker
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# Bun
|
|
6
|
+
|
|
7
|
+
On Bun, the app is a Docker image built from its source, run as a container with a volume for its data. The scaffolded `configs/infra.ts` builds and runs it in your local Docker; point it at a server to deploy there.
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
space deploy
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## The processes
|
|
14
|
+
|
|
15
|
+
The app runs as three kinds of process: the **web** server, the **queue** consumers and the **crons**. By default the web process starts the other two as children and restarts one that crashes, so a slow or failing job never blocks or takes down a request. `SIGTERM` stops all three, and a queue process stopped mid-batch hands its messages back.
|
|
16
|
+
|
|
17
|
+
```mermaid
|
|
18
|
+
flowchart LR
|
|
19
|
+
web["web: pages and routes"] --> queues["queues: app/queues/"]
|
|
20
|
+
web --> crons["crons: app/crons/"]
|
|
21
|
+
web --- state[("state database")]
|
|
22
|
+
queues --- state
|
|
23
|
+
crons --- state
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
They share a libSQL **state database** behind `Kv`, `Queue`, `Bus` and `RateLimiter`: a file in the data folder by default.
|
|
27
|
+
|
|
28
|
+
## The image
|
|
29
|
+
|
|
30
|
+
`configs/Dockerfile` installs the dependencies, runs `vite build` and keeps only `dist/`. Bun's downloads go in a [cache mount](https://docs.docker.com/build/cache/optimize/#use-cache-mounts), so a rebuild only downloads what changed, and the image doesn't carry them; that needs BuildKit, Docker's default builder since 23. `configs/Dockerfile.dockerignore` keeps local files, such as `.env` and `.space/data`, out of it. The container gets a volume on `/data`, for file databases, the state database and blobs, and restarts unless stopped.
|
|
31
|
+
|
|
32
|
+
## Variables
|
|
33
|
+
|
|
34
|
+
| Variable | Default | What it does |
|
|
35
|
+
| ----------------- | ------------------------------------ | ----------------------------------------------------------------- |
|
|
36
|
+
| `PORT`, `HOST` | `3000`, all | Where the web server listens |
|
|
37
|
+
| `SPACE_DATA_DIR` | `.space/data` (`/data` in the image) | Local databases, the state database, blobs |
|
|
38
|
+
| `SPACE_STATE_URL` | a file in the data dir | The state database behind Kv, Queue, Bus and RateLimiter (libSQL) |
|
|
39
|
+
| `DB_<NAME>_URL` | a file in the data dir | A libSQL database: `libsql://`, `https://` or `file:` |
|
|
40
|
+
| `SPACE_ROLE` | unset: web, starting the others | `web`, `queues` or `crons`: run one part per process |
|
|
41
|
+
|
|
42
|
+
## On a server
|
|
43
|
+
|
|
44
|
+
Give the image, the volume and the container a Docker context that reaches the server over SSH:
|
|
45
|
+
|
|
46
|
+
```ts [configs/infra.ts]
|
|
47
|
+
const context = yield * Docker.Context("Host", { docker: "host=ssh://deploy@server.example.com" });
|
|
48
|
+
const image = yield * Docker.Image("Image", { context /* ... */ });
|
|
49
|
+
const data = yield * Docker.Volume("Data", { context });
|
|
50
|
+
yield * Docker.Container("App", { context /* ... */ });
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Put a reverse proxy, such as Caddy, in front of it for HTTPS.
|
|
54
|
+
|
|
55
|
+
The stack keeps its deploy state in `.alchemy/`, on the machine that deployed. To deploy from CI or from more than one machine, keep it in a shared store instead, such as `Cloudflare.state()` from `@alchemy.run/cloudflare`.
|
|
56
|
+
|
|
57
|
+
## More than one machine
|
|
58
|
+
|
|
59
|
+
Point `SPACE_STATE_URL` and the databases at a shared libSQL server (Turso or `sqld`), then run several `SPACE_ROLE=web` and `SPACE_ROLE=queues` processes, and exactly one `SPACE_ROLE=crons`. `Blob` is a local folder for now, so it needs a shared volume.
|
|
60
|
+
|
|
61
|
+
## Without Docker
|
|
62
|
+
|
|
63
|
+
```sh
|
|
64
|
+
space build
|
|
65
|
+
bun dist/server/index.js
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
runs the same thing, with the data in `.space/data` unless `SPACE_DATA_DIR` says otherwise.
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
---
|
|
2
|
+
icon: building-factory-2
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# Infrastructure
|
|
6
|
+
|
|
7
|
+
`configs/infra.ts` is what a deploy creates: a plain [Alchemy](https://alchemy.run) stack, scaffolded with the app and yours to change. It's exactly what `alchemy deploy` would run, so Alchemy's docs cover everything in it. spacefn adds two things.
|
|
8
|
+
|
|
9
|
+
## `#space/infra.ts`
|
|
10
|
+
|
|
11
|
+
Generated from `app/` like the manifest, it holds what the file conventions ask for, as plain data:
|
|
12
|
+
|
|
13
|
+
| Field | From |
|
|
14
|
+
| -------------------- | ------------------------------------------ |
|
|
15
|
+
| `app.name` | `package.json`'s `name` |
|
|
16
|
+
| `app.databases` | `app/db/*/`, with their driver and binding |
|
|
17
|
+
| `app.queues` | `app/queues/*.ts` |
|
|
18
|
+
| `app.crons` | the schedules in `app/crons/*.ts` |
|
|
19
|
+
| `app.durableObjects` | `app/durable-objects/*.ts` |
|
|
20
|
+
| `app.workflows` | `app/workflows/*.ts` |
|
|
21
|
+
| `app.folders` | the app's code folders, for rebuilds |
|
|
22
|
+
|
|
23
|
+
The stack loops over these lists, so a new database folder or queue file gets its resource on the next deploy. It imports no app code.
|
|
24
|
+
|
|
25
|
+
## `variables(...)`
|
|
26
|
+
|
|
27
|
+
From `spacefn/infra`, it reads values from the environment for the deploy to pass on:
|
|
28
|
+
|
|
29
|
+
```ts [configs/infra.ts]
|
|
30
|
+
import { variables } from "spacefn/infra";
|
|
31
|
+
|
|
32
|
+
import env from "#configs/env.ts";
|
|
33
|
+
|
|
34
|
+
const bindings = {
|
|
35
|
+
...variables(env), // configs/env.ts's fields; Env.secret() ones as secrets
|
|
36
|
+
...variables({ OTEL_EXPORTER_OTLP_ENDPOINT: "plain", OTEL_EXPORTER_OTLP_HEADERS: "secret" }),
|
|
37
|
+
};
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Secrets become Worker secrets on Cloudflare. A variable that isn't set is left out.
|
|
41
|
+
|
|
42
|
+
## Changing it
|
|
43
|
+
|
|
44
|
+
Everything else is written out: the KV namespace, the R2 bucket, the Durable Objects behind `Bus` and `RateLimiter`, the Worker or the container. Remove what you don't use and add what you need beside it, such as a domain or Workers AI:
|
|
45
|
+
|
|
46
|
+
```ts [configs/infra.ts]
|
|
47
|
+
const worker =
|
|
48
|
+
yield *
|
|
49
|
+
Cloudflare.Website.Vite("Worker", {
|
|
50
|
+
// ...
|
|
51
|
+
domain: "todo.example.com",
|
|
52
|
+
env: { ...bindings, AI: yield * Cloudflare.Ai("AI") },
|
|
53
|
+
});
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
`space doctor` names any binding the conventions need that `configs/infra.ts` doesn't give, and a Worker missing one says which when it's used.
|
|
57
|
+
|
|
58
|
+
## State
|
|
59
|
+
|
|
60
|
+
Alchemy records what each stage deployed, so the next deploy changes only what changed.
|
|
61
|
+
|
|
62
|
+
| Target | Where the state is |
|
|
63
|
+
| ---------- | ----------------------------------------------------------------------------------- |
|
|
64
|
+
| Cloudflare | in your account, with `Cloudflare.state()`; `space dev` uses `Alchemy.localState()` |
|
|
65
|
+
| Bun | `Alchemy.localState()`, in `.alchemy/` at the app root |
|
|
66
|
+
|
|
67
|
+
`.alchemy/` is in `.gitignore`. Deploy a Bun stage from one machine, or move its state to a shared store.
|
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: CI/CD
|
|
3
|
+
icon: cloud-upload
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# CI/CD
|
|
7
|
+
|
|
8
|
+
A deploy from CI is the same command as from your machine, without the questions:
|
|
9
|
+
|
|
10
|
+
```sh
|
|
11
|
+
npm ci # also runs space gen
|
|
12
|
+
npm test
|
|
13
|
+
npx space deploy --stage prod --yes
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
`--yes` approves Alchemy's plan without asking. The app's variables come from the CI's environment, so no `.env.<stage>` file is needed: set each field of `configs/env.ts` as a CI variable, its secrets as CI secrets.
|
|
17
|
+
|
|
18
|
+
## Cloudflare credentials
|
|
19
|
+
|
|
20
|
+
On your machine, the first deploy signs you in through the browser. CI can't, so give it an API token:
|
|
21
|
+
|
|
22
|
+
1. In the Cloudflare dashboard, **My Profile → API Tokens → Create Token**, start from the **Edit Cloudflare Workers** template.
|
|
23
|
+
2. Keep what the template has, and add:
|
|
24
|
+
|
|
25
|
+
| Permission | For |
|
|
26
|
+
| --------------------------------- | ------------------------------------------------------ |
|
|
27
|
+
| Account → **Secrets Store: Edit** | every app: the key to Alchemy's deploy state |
|
|
28
|
+
| Account → **D1: Edit** | D1 databases, as the scaffolded app has |
|
|
29
|
+
| Account → **Queues: Edit** | `app/queues/` |
|
|
30
|
+
| Zone → **Zone: Read** | a [domain](1-cloudflare.md#a-domain), to find its zone |
|
|
31
|
+
|
|
32
|
+
Secrets Store needs **Edit** even to read the key: Alchemy reads it through a temporary Worker bound to it.
|
|
33
|
+
|
|
34
|
+
3. Under **Account Resources** pick the account, and under **Zone Resources** its zones.
|
|
35
|
+
4. Store the token as `CLOUDFLARE_API_TOKEN` in the CI's secrets, and your account's ID (on the **Workers & Pages** overview) as `CLOUDFLARE_ACCOUNT_ID`.
|
|
36
|
+
|
|
37
|
+
Alchemy keeps the deploy state in the account too, so CI and your machine see the same deploys and either can deploy next.
|
|
38
|
+
|
|
39
|
+
## Cloudflare dashboard
|
|
40
|
+
|
|
41
|
+
[Workers Builds](https://developers.cloudflare.com/workers/ci-cd/builds/) deploys on every push to a branch, from a repository you link in the dashboard. The app needs no Wrangler file: you replace the default `npx wrangler deploy` with `space deploy`.
|
|
42
|
+
|
|
43
|
+
1. Deploy once from your machine, with the production values in `.env.prod`, so the Worker exists:
|
|
44
|
+
|
|
45
|
+
```sh
|
|
46
|
+
npx space deploy --stage prod
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
2. In **Workers & Pages**, open that Worker, named like `<app>-worker-prod-<id>`, then **Settings → Builds → Connect**, and pick the repository. Don't use **Create application**: Alchemy names the Worker itself, so you'd get a second, unused one.
|
|
50
|
+
|
|
51
|
+
3. Set the build:
|
|
52
|
+
|
|
53
|
+
| Setting | Value |
|
|
54
|
+
| ------------------ | -------------------------------------------------------------------------------------------------------------- |
|
|
55
|
+
| **Git branch** | `main` |
|
|
56
|
+
| **Build command** | `npm test`, or empty: the deploy builds the app |
|
|
57
|
+
| **Deploy command** | `npx space deploy --stage prod --yes` |
|
|
58
|
+
| **Preview builds** | off: their default, `wrangler preview`, needs a Wrangler file |
|
|
59
|
+
| **Root directory** | the app's folder, if it isn't the repository's root |
|
|
60
|
+
| **API token** | the token from [Cloudflare credentials](#cloudflare-credentials), not a generated one, which lacks permissions |
|
|
61
|
+
|
|
62
|
+
4. Under **Build variables and secrets**, add:
|
|
63
|
+
|
|
64
|
+
- `CLOUDFLARE_ACCOUNT_ID`, and `CLOUDFLARE_API_TOKEN` as a secret, with the same token;
|
|
65
|
+
- what `.env.prod` has, as it isn't committed: the fields of `configs/env.ts`, and any `DB_<NAME>_*` and `OTEL_*` variables, with secrets as secrets.
|
|
66
|
+
|
|
67
|
+
5. Push to `main`. The build installs the dependencies, which runs `space gen`, then runs the two commands.
|
|
68
|
+
|
|
69
|
+
> [!WARNING]
|
|
70
|
+
> Change the app's variables in **Build variables and secrets**, then deploy again. A deploy doesn't read the Worker's own **Variables and Secrets**, and replaces the plain variables set there.
|
|
71
|
+
|
|
72
|
+
For another stage, such as `staging`, do the same with that stage's Worker, its branch and `--stage staging`. For a stage per pull request, use [GitHub Actions](#a-stage-per-pull-request): Workers Builds has no step to destroy a stage when the pull request closes.
|
|
73
|
+
|
|
74
|
+
Workers Builds has its own default versions of Node and the package managers. If installing fails there but works on your machine, pin yours with `packageManager` in `package.json` and a `.node-version` file.
|
|
75
|
+
|
|
76
|
+
## GitHub
|
|
77
|
+
|
|
78
|
+
Deploy `main` to `prod` after the tests pass:
|
|
79
|
+
|
|
80
|
+
```yaml [.github/workflows/deploy.yml]
|
|
81
|
+
name: Deploy
|
|
82
|
+
|
|
83
|
+
on:
|
|
84
|
+
push:
|
|
85
|
+
branches: [main]
|
|
86
|
+
|
|
87
|
+
concurrency: deploy-prod
|
|
88
|
+
|
|
89
|
+
jobs:
|
|
90
|
+
deploy:
|
|
91
|
+
runs-on: ubuntu-latest
|
|
92
|
+
steps:
|
|
93
|
+
- uses: actions/checkout@v4
|
|
94
|
+
- uses: actions/setup-node@v4
|
|
95
|
+
with:
|
|
96
|
+
node-version: 22
|
|
97
|
+
cache: npm
|
|
98
|
+
- run: npm ci
|
|
99
|
+
- run: npm test
|
|
100
|
+
- run: npx space deploy --stage prod --yes
|
|
101
|
+
env:
|
|
102
|
+
CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
|
|
103
|
+
CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
|
|
104
|
+
# configs/env.ts's fields:
|
|
105
|
+
SITE_URL: ${{ vars.SITE_URL }}
|
|
106
|
+
STRIPE_KEY: ${{ secrets.STRIPE_KEY }}
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
`concurrency` keeps two deploys of the same stage from running at once.
|
|
110
|
+
|
|
111
|
+
### A stage per pull request
|
|
112
|
+
|
|
113
|
+
Each pull request gets its own copy of the app, and loses it when it closes:
|
|
114
|
+
|
|
115
|
+
```yaml [.github/workflows/preview.yml]
|
|
116
|
+
name: Preview
|
|
117
|
+
|
|
118
|
+
on:
|
|
119
|
+
pull_request:
|
|
120
|
+
types: [opened, synchronize, reopened, closed]
|
|
121
|
+
|
|
122
|
+
concurrency: preview-${{ github.event.number }}
|
|
123
|
+
|
|
124
|
+
jobs:
|
|
125
|
+
preview:
|
|
126
|
+
runs-on: ubuntu-latest
|
|
127
|
+
env:
|
|
128
|
+
CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
|
|
129
|
+
CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
|
|
130
|
+
SITE_URL: https://pr-${{ github.event.number }}.example.com
|
|
131
|
+
steps:
|
|
132
|
+
- uses: actions/checkout@v4
|
|
133
|
+
- uses: actions/setup-node@v4
|
|
134
|
+
with:
|
|
135
|
+
node-version: 22
|
|
136
|
+
cache: npm
|
|
137
|
+
- run: npm ci
|
|
138
|
+
- if: github.event.action != 'closed'
|
|
139
|
+
run: npx space deploy --stage pr-${{ github.event.number }} --yes
|
|
140
|
+
- if: github.event.action == 'closed'
|
|
141
|
+
run: npx space destroy --stage pr-${{ github.event.number }} --yes
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
## GitLab
|
|
145
|
+
|
|
146
|
+
```yaml [.gitlab-ci.yml]
|
|
147
|
+
default:
|
|
148
|
+
image: node:22
|
|
149
|
+
cache:
|
|
150
|
+
paths: [.npm/]
|
|
151
|
+
before_script:
|
|
152
|
+
- npm ci --cache .npm --prefer-offline
|
|
153
|
+
|
|
154
|
+
stages: [test, deploy]
|
|
155
|
+
|
|
156
|
+
test:
|
|
157
|
+
stage: test
|
|
158
|
+
script:
|
|
159
|
+
- npm test
|
|
160
|
+
|
|
161
|
+
deploy:
|
|
162
|
+
stage: deploy
|
|
163
|
+
resource_group: prod
|
|
164
|
+
script:
|
|
165
|
+
- npx space deploy --stage prod --yes
|
|
166
|
+
rules:
|
|
167
|
+
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
Set `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID` and the app's variables in **Settings → CI/CD → Variables**, masked and protected for the secrets. `resource_group` keeps two deploys of the stage from running at once.
|
|
171
|
+
|
|
172
|
+
## A Bun app from CI
|
|
173
|
+
|
|
174
|
+
A Bun deploy builds a Docker image and runs it, so CI needs Docker and a way to reach the server:
|
|
175
|
+
|
|
176
|
+
- Give the stack a Docker context over SSH to the server, as in [Bun](2-bun.md#on-a-server), and give CI the SSH key.
|
|
177
|
+
- Move the deploy state off the runner, which is thrown away after each job: use a shared store such as `Cloudflare.state()` in place of `Alchemy.localState()` in `configs/infra.ts`.
|
|
178
|
+
|
|
179
|
+
Then the same `npx space deploy --stage prod --yes` runs from the job.
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
---
|
|
2
|
+
icon: rocket
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# Deployment
|
|
6
|
+
|
|
7
|
+
One command deploys the app, to the target in `configs/vite.ts`:
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
space deploy # stage prod
|
|
11
|
+
space deploy --stage staging # another copy, with its own resources
|
|
12
|
+
space destroy --stage staging # delete that copy, its data included
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
`space deploy` generates `.space/` for production and runs `alchemy deploy configs/infra.ts --stage <stage>`. [Alchemy](https://alchemy.run) creates or updates what the stack declares and shows you the plan to approve; `--yes` skips the question, for CI.
|
|
16
|
+
|
|
17
|
+
```mermaid
|
|
18
|
+
flowchart LR
|
|
19
|
+
app["app/"] -->|space gen --prod| space[".space/"]
|
|
20
|
+
space --> infra["configs/infra.ts"]
|
|
21
|
+
env[".env.stage"] --> infra
|
|
22
|
+
infra -->|alchemy deploy| target["Worker, or container"]
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## Stages
|
|
26
|
+
|
|
27
|
+
A stage is a separate copy of the app: its own Worker or container, databases, queues and state. `prod` is the default. Use one per environment (`staging`, `prod`) or per pull request (`pr-42`), and `space destroy` the ones you're done with.
|
|
28
|
+
|
|
29
|
+
Each stage reads its variables from `.env.<stage>` and from the environment, never from `.env`. See [`.env`](../4-folders/8-env.md).
|
|
30
|
+
|
|
31
|
+
## Where it runs
|
|
32
|
+
|
|
33
|
+
| Target | What a deploy creates |
|
|
34
|
+
| ----------------------------- | ------------------------------------------------------------------------------------ |
|
|
35
|
+
| [Cloudflare](1-cloudflare.md) | A Worker with D1, KV, R2, Queues, Durable Objects and Cron Triggers, in your account |
|
|
36
|
+
| [Bun](2-bun.md) | A Docker image of the app, and a container running it with a volume for its data |
|
|
37
|
+
|
|
38
|
+
What the stack creates, and how to change it, is in [Infrastructure](3-infrastructure.md). Deploying from GitHub, GitLab or Cloudflare's own builds is in [CI/CD](4-ci-cd.md).
|
|
39
|
+
|
|
40
|
+
## Telemetry
|
|
41
|
+
|
|
42
|
+
Traces, logs and metrics go over OTLP when `OTEL_EXPORTER_OTLP_ENDPOINT` is set (with `OTEL_EXPORTER_OTLP_HEADERS` for the key), to any OpenTelemetry backend. Requests and queries are traced already; add spans with `Effect.withSpan`. The service name is the app's name unless `OTEL_SERVICE_NAME` says otherwise. `telemetry(manifest.name)` in `app/entry.ts` turns it on.
|
|
43
|
+
|
|
44
|
+
## Before the first deploy
|
|
45
|
+
|
|
46
|
+
- `space doctor` checks the tools the target needs, the config, and that `configs/infra.ts` gives every binding `app/` asks for.
|
|
47
|
+
- Create `.env.prod` with the production values, or set them in CI.
|
|
48
|
+
- On Cloudflare, enable R2 on the account, or remove the bucket from `configs/infra.ts`.
|