From da6a7a8f87f2800d1345faef35237ace8dd6e9f4 Mon Sep 17 00:00:00 2001 From: dario-piotrowicz Date: Thu, 23 Feb 2023 14:19:05 +0000 Subject: [PATCH] Improve Astro pages guide Improve the Astro guide by updating some slightly outdated statements, clarify some information, reordering sections to make the flow of the guide better (for example, by going into details on functions only after the basic pages deployment) and also by mentioning how to access bindings (as per #7438) --- content/pages/framework-guides/astro.md | 119 ++++++++++++++---------- 1 file changed, 71 insertions(+), 48 deletions(-) diff --git a/content/pages/framework-guides/astro.md b/content/pages/framework-guides/astro.md index 9af164e039ad039..0cdee5b17b9bd76 100644 --- a/content/pages/framework-guides/astro.md +++ b/content/pages/framework-guides/astro.md @@ -17,16 +17,27 @@ Create a new project directory and then initiate Astro's official setup tool by ```sh $ npm create astro@latest -# cd into created project $ cd ``` -Astro will ask you which project type you would like to set up. Your answers will not affect the rest of this tutorial. Select an answer ideal for your project. +Astro will ask: -{{}} +1. Which project type you would like to set up. Your answers will not affect the rest of this tutorial. Select an answer ideal for your project. + +2. If you want to install dependencies. Select `Yes`. If you select `No`, you must run `npm install` before running or building your application for the first time. + +3. If you want to set initialize a Git repository. We recommend you to select `No` and follow this guide's [Git instructions](/pages/framework-guides/astro/#creating-a-github-repository) below. If you select `Yes`, do not follow the below Git instructions precisely but adjust them to your needs. + + +### Astro configuration + +You can deploy an Astro Server-side Rendered (SSR) site to Cloudflare Pages using the [`@astrojs/cloudflare` adapter](https://github.com/withastro/astro/tree/main/packages/integrations/cloudflare#readme). SSR sites render on Pages Functions and allow for dynamic functionality and customizations. + +To enable an SSR site and deploy to Cloudflare Pages, add the [`@astrojs/cloudflare` adapter](https://github.com/withastro/astro/tree/main/packages/integrations/cloudflare#readme) to your project's `package.json` by running: +```sh +$ npm run astro add cloudflare +``` {{}} @@ -48,49 +59,6 @@ $ git commit -m "initial commit" $ git push -u origin main ``` -## Using Pages Functions - -[Pages Functions](/pages/platform/functions/) enable you to run server-side code to add dynamic functionality without running a dedicated server. - -To get started, create a `functions` directory at the root of your project. Writing your Functions files in this directory automatically generates a Worker with custom functionality at the predesignated routes. To learn more, refer to [Pages Functions](/pages/platform/functions/). - -### Astro Configuration - -You can deploy an Astro Server-side Rendered (SSR) site to Cloudflare Pages using the [`@astrojs/cloudflare` adapter](https://github.com/withastro/astro/tree/main/packages/integrations/cloudflare#readme). SSR sites render on Pages Functions and allow for dynamic functionality and customizations. - -To enable an SSR site and deploy to Cloudflare Pages, add the [`@astrojs/cloudflare` adapter](https://github.com/withastro/astro/tree/main/packages/integrations/cloudflare#readme) to your project's `package.json` by running: - -```sh -$ npm run astro add cloudflare -``` - -### Modes - -There are currently two modes supported when using Pages Functions with the [`@astrojs/cloudflare`](https://github.com/withastro/astro/tree/main/packages/integrations/cloudflare#readme) adapter. - -1. **Advanced** mode: This mode is used when you want to run your Function in `advanced` mode. This mode picks up the `_worker.js` in `dist`, or a directory mode where Pages will compile the Worker out of a Functions folder in the project root. - -{{}} - -2. **Directory** mode: This mode is used when you want to run your Function in `directory` mode. In this mode, the adapter will compile the client-side part of your application the same way, but it will move the Worker into a `functions` folder in the project root. The adapter will allow you to access your Pages Functions from your `functions` folder, allowing you to add [Pages Plugins](/pages/platform/functions/plugins/) and [Middleware](/pages/platform/functions/#adding-middleware) which can be checked into version control. - -To use Directory mode, modify your `astro.config.mjs` file to add `mode: "directory"` to the adapter configuration: - -```js ---- -filename: astro.config.mjs -highlight: [2] ---- -export default defineConfig({ - output: 'server', - adapter: cloudflare({ mode: "directory" }), -}); -``` - ## Deploying with Cloudflare Pages Deploy your site to Pages by logging in to the [Cloudflare dashboard](https://dash.cloudflare.com/) > **Account Home** > **Pages** and selecting **Create a project**. @@ -104,6 +72,7 @@ Select the new GitHub repository that you created and, in the **Set up builds an | Configuration option | Value | | --------------------- | ----------------------- | | Production branch | `main` | +| Framework preset | `Astro` | | Build command | `npm run build` | | Build directory | `dist` | | Environment Variables | `NODE_VERSION: 16.12.0` | @@ -132,6 +101,60 @@ For the complete guide to deploying your first site to Cloudflare Pages, refer t {{}} +### Modes + +There are currently two modes supported when using Pages Functions with the [`@astrojs/cloudflare`](https://github.com/withastro/astro/tree/main/packages/integrations/cloudflare#readme) adapter. + +1. [**Advanced**](/pages/platform/functions/advanced-mode/) mode: This mode is used when you want to run your Function in `advanced` mode. This mode picks up the `_worker.js` in `dist`, or a directory mode where Pages will compile the Worker out of a Functions folder in the project root. + +{{}} + +2. **Directory** mode: This mode is used when you want to run your Pages Function in `directory` mode. In this mode, the adapter will compile the client-side part of your application the same way, but it will move the Worker into a `functions` folder in the project root. The adapter will allow you to access your Pages Functions from your `functions` folder. This allows you to add [Pages Plugins](/pages/platform/functions/plugins/) and [Middleware](/pages/platform/functions/#adding-middleware) which can be checked into version control. + +To use `directory` mode, modify your `astro.config.mjs` file to add `mode: "directory"` to the adapter configuration: + +```js +--- +filename: astro.config.mjs +highlight: [2] +--- +export default defineConfig({ + output: 'server', + adapter: cloudflare({ mode: "directory" }), +}); +``` + +## Use bindings in your Astro application + +A [binding](/pages/platform/functions/bindings/) allows your application to interact with Cloudflare developer products, such as [KV](https://developers.cloudflare.com/workers/learning/how-kv-works/), [Durable Object](/workers/learning/using-durable-objects/), [R2](/r2/), and [D1](https://blog.cloudflare.com/introducing-d1/). + +In Astro you can add server-side code via [endpoints](https://docs.astro.build/en/core-concepts/endpoints/), in such endpoints you can then use the `getRuntime()` method to access Cloudflare's environment and consecutively any bindings set for your application. + +The following code block shows an example of accessing a KV namespace in Astro. + +```typescript +--- +filename: src/my-endpoint.ts +highlight: [2, 5, 6] +--- +import type { APIContext } from "astro"; +import { getRuntime } from "@astrojs/cloudflare/runtime"; + +export async function get({request}: APIContext) => { + const runtime = getRuntime(request); + // the type KVNamespace comes from the @cloudflare/workers-types package + const { MY_KV } = (runtime.env as { MY_KV: KVNamespace })); + + return { + // ... + }; +}; +``` + ## Learn more By completing this guide, you have successfully deployed your Astro site to Cloudflare Pages. To get started with other frameworks, [refer to the list of Framework guides](/pages/framework-guides/).