diff --git a/www/astro.config.mjs b/www/astro.config.mjs index 270bde6823..c62167a226 100644 --- a/www/astro.config.mjs +++ b/www/astro.config.mjs @@ -60,6 +60,9 @@ const sidebar = [ label: "How to", collapsed: true, items: [ + { label: "Cloudflare", slug: "docs/cloudflare" }, + { label: "PlanetScale", slug: "docs/planetscale" }, + { label: "Policy Packs", slug: "docs/policy-packs" }, { label: "AWS Accounts", slug: "docs/aws-accounts" }, { label: "IAM Credentials", slug: "docs/iam-credentials" }, { label: "Migrate From v2", slug: "docs/migrate-from-v2" }, @@ -71,8 +74,6 @@ const sidebar = [ { label: "Share Across Stages", slug: "docs/share-across-stages" }, { label: "Reference Resources", slug: "docs/reference-resources" }, { label: "Environment Variables", slug: "docs/environment-variables" }, - { label: "Policy Packs", slug: "docs/policy-packs" }, - { label: "PlanetScale", slug: "docs/planetscale" }, { label: "Upgrade AWS Databases", slug: "docs/upgrade-aws-databases" }, ], }, diff --git a/www/src/content/docs/docs/cloudflare.mdx b/www/src/content/docs/docs/cloudflare.mdx new file mode 100644 index 0000000000..4f3bfd9751 --- /dev/null +++ b/www/src/content/docs/docs/cloudflare.mdx @@ -0,0 +1,149 @@ +--- +title: Cloudflare +description: Learn how to use SST with Cloudflare +--- + +[Cloudflare](https://cloudflare.com) lets you deploy apps with Workers and connect services like D1, R2, and DNS. This guide covers how to set it up with SST. + +--- + +## Install + +Add the Cloudflare provider to your SST app. Learn more about [providers](/docs/providers). + +```bash +sst add cloudflare +``` + +This adds the provider to your `sst.config.ts`. + +```ts title="sst.config.ts" {3} +{ + providers: { + cloudflare: "5.37.1", + }, +} +``` + +If Cloudflare should store your app state, set [`home`](/docs/reference/config/#home) to `"cloudflare"`. This is useful in setups where you plan to use Cloudflare as you main cloud provider. + +--- + +## Credentials + +You can create an account token in the Cloudflare dashboard under [Manage Account > API Tokens](https://dash.cloudflare.com/profile/api-tokens). + +Start with the **Edit Cloudflare Workers** template and add these permissions: + +- *Account - D1 - Edit* +- *Zone - DNS - Edit* + +:::tip +If your app uses other Cloudflare products, add the permissions those features need. +::: + +Give the token access to the account your application will be deploying to. If you are using Cloudflare DNS with SST, include the zones that SST should update. + +Set `CLOUDFLARE_DEFAULT_ACCOUNT_ID` to the Cloudflare account ID that SST should use. If you leave it unset, SST falls back to the first account that Cloudflare returns for that token. + +Then set these variables in your shell, `.env`, or CI environment before you deploy: + +```bash +export CLOUDFLARE_API_TOKEN=aaaaaaaa_aaaaaaaaaaaa_aaaaaaaa +export CLOUDFLARE_DEFAULT_ACCOUNT_ID=aaaaaaaa_aaaaaaaaaaaa_aaaaaaaa +``` + +--- + +## Components + +SST includes Cloudflare components for Workers, storage, queues, cron jobs, AI bindings, and more. + +### Worker + +Create a Cloudflare Worker and enable a URL so it can handle HTTP requests. + +```ts title="sst.config.ts" +const worker = new sst.cloudflare.Worker("MyWorker", { + handler: "index.ts", + url: true, +}); + +return { + url: worker.url, +}; +``` + +Use the [`Worker`](/docs/component/cloudflare/worker/) component to build APIs and edge handlers on Cloudflare. + + +### Storage + +Create Cloudflare storage resources and link them to your Worker. For example, here's a D1 database. + +```ts title="sst.config.ts" +const db = new sst.cloudflare.D1("MyDatabase"); + +new sst.cloudflare.Worker("MyWorker", { + handler: "index.ts", + link: [db], + url: true, +}); +``` + +Then access it in your handler through `Resource`. + +```ts title="index.ts" +import { Resource } from "sst"; + +export default { + async fetch() { + const row = await Resource.MyDatabase.prepare( + "SELECT id FROM todo ORDER BY id DESC LIMIT 1", + ).first(); + + return Response.json(row); + }, +}; +``` + +The same pattern works with [`Bucket`](/docs/component/cloudflare/bucket/) for R2 and [`Kv`](/docs/component/cloudflare/kv/) for KV namespaces. + + +### Queue + +Use [`Queue`](/docs/component/cloudflare/queue/) for async work. + +```ts title="sst.config.ts" +const queue = new sst.cloudflare.Queue("MyQueue"); + +queue.subscribe("consumer.ts"); + +const producer = new sst.cloudflare.Worker("Producer", { + handler: "producer.ts", + link: [queue], + url: true, +}); +``` + +For scheduled work, use [`Cron`](/docs/component/cloudflare/cron/) to run a worker on a cron expression. + +### More components + +Browse the component docs for [`Worker`](/docs/component/cloudflare/worker/), [`Bucket`](/docs/component/cloudflare/bucket/), [`D1`](/docs/component/cloudflare/d1/), [`Kv`](/docs/component/cloudflare/kv/), [`Queue`](/docs/component/cloudflare/queue/), [`Cron`](/docs/component/cloudflare/cron/), and [`Ai`](/docs/component/cloudflare/ai/). + +If you are using Cloudflare DNS with SST, use [`sst.cloudflare.dns`](/docs/component/cloudflare/dns/) with [custom domains](/docs/custom-domains/). + +--- + +## Examples + +Check out the full examples: + +- [Cloudflare Workers with SST](/docs/start/cloudflare/worker/) +- [Hono on Cloudflare with SST](/docs/start/cloudflare/hono/) +- [tRPC on Cloudflare with SST](/docs/start/cloudflare/trpc/) +- [Cloudflare D1](https://github.com/sst/sst/tree/dev/examples/cloudflare-d1) +- [Cloudflare KV](https://github.com/sst/sst/tree/dev/examples/cloudflare-kv) +- [Cloudflare Queue](https://github.com/sst/sst/tree/dev/examples/cloudflare-queue) +- [Cloudflare Cron](https://github.com/sst/sst/tree/dev/examples/cloudflare-cron) diff --git a/www/src/content/docs/docs/providers.mdx b/www/src/content/docs/docs/providers.mdx index 3394bdd230..9a371d1fd9 100644 --- a/www/src/content/docs/docs/providers.mdx +++ b/www/src/content/docs/docs/providers.mdx @@ -114,8 +114,11 @@ Most providers will read your credentials from the environment. For example, for ```bash export CLOUDFLARE_API_TOKEN=aaaaaaaa_aaaaaaaaaaaa_aaaaaaaa +export CLOUDFLARE_DEFAULT_ACCOUNT_ID=aaaaaaaa_aaaaaaaaaaaa_aaaaaaaa ``` +Follow the [Cloudflare guide](/docs/cloudflare/) for the recommended setup. + However, some providers also allow you to pass in the credentials through the config. ```ts title="sst.config.ts" diff --git a/www/src/content/docs/docs/start/cloudflare/hono.mdx b/www/src/content/docs/docs/start/cloudflare/hono.mdx index 5b67cfb87b..ac07fdd382 100644 --- a/www/src/content/docs/docs/start/cloudflare/hono.mdx +++ b/www/src/content/docs/docs/start/cloudflare/hono.mdx @@ -9,7 +9,7 @@ We are going to build an API with Hono, add an R2 bucket for file uploads, and d You can [view the source](https://github.com/sst/sst/tree/dev/examples/cloudflare-hono) of this example in our repo. ::: -Before you get started, make sure to [Create your Cloudflare API token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/). +Before you get started, [create your Cloudflare API token](/docs/cloudflare/#credentials). --- @@ -37,9 +37,9 @@ Select the defaults and pick **Cloudflare**. This'll create a `sst.config.ts` fi --- -#### Set the Cloudflare API token +#### Set the Cloudflare credentials -You can save your Cloudflare API token in a `.env` file or just set it directly. +Set the token and account ID in your shell or `.env` file. ```bash export CLOUDFLARE_API_TOKEN=aaaaaaaa_aaaaaaaaaaaa_aaaaaaaa @@ -193,4 +193,3 @@ npx sst deploy --stage production ``` You can use any stage name here but it's good to create a new stage for production. - diff --git a/www/src/content/docs/docs/start/cloudflare/trpc.mdx b/www/src/content/docs/docs/start/cloudflare/trpc.mdx index 4b5aad431a..08bf0f893c 100644 --- a/www/src/content/docs/docs/start/cloudflare/trpc.mdx +++ b/www/src/content/docs/docs/start/cloudflare/trpc.mdx @@ -9,7 +9,7 @@ We are going to build a [tRPC](https://trpc.io) API, a simple client, and deploy You can [view the source](https://github.com/sst/sst/tree/dev/examples/cloudflare-trpc) of this example in our repo. ::: -Before you get started, make sure to [Create your Cloudflare API token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/). +Before you get started, [create your Cloudflare API token](/docs/cloudflare/#credentials). --- @@ -37,7 +37,7 @@ Select the defaults and pick **Cloudflare**. This'll create a `sst.config.ts` fi --- -#### Set the Cloudflare API token +#### Set the Cloudflare credentials You can save your Cloudflare API token in a `.env` file or just set it directly. @@ -208,4 +208,3 @@ npx sst deploy --stage production ``` You can use any stage name here but it's good to create a new stage for production. - diff --git a/www/src/content/docs/docs/start/cloudflare/worker.mdx b/www/src/content/docs/docs/start/cloudflare/worker.mdx index 6a08c6e7c4..d05450a2a5 100644 --- a/www/src/content/docs/docs/start/cloudflare/worker.mdx +++ b/www/src/content/docs/docs/start/cloudflare/worker.mdx @@ -9,7 +9,7 @@ We are going to build an API with a Cloudflare Worker, add an R2 bucket for file You can [view the source](https://github.com/sst/sst/tree/dev/examples/cloudflare-worker) of this example in our repo. ::: -Before you get started, make sure to [Create your Cloudflare API token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/). +Before you get started, [create your Cloudflare API token](/docs/cloudflare/#credentials). --- @@ -37,9 +37,9 @@ Select the defaults and pick **Cloudflare**. This'll create a `sst.config.ts` fi --- -#### Set the Cloudflare API token +#### Set the Cloudflare credentials -You can save your Cloudflare API token in a `.env` file or just set it directly. +Set the token and account ID in your shell or `.env` file. ```bash export CLOUDFLARE_API_TOKEN=aaaaaaaa_aaaaaaaaaaaa_aaaaaaaa @@ -188,4 +188,3 @@ npx sst deploy --stage production ``` You can use any stage name here but it's good to create a new stage for production. -