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/).