Skip to content

Commit

Permalink
Improve Astro pages guide
Browse files Browse the repository at this point in the history 
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 cloudflare#7438)
  • Loading branch information
@dario-piotrowicz
dario-piotrowicz committed Mar 3, 2023
1 parent 178466a commit da6a7a8
Showing 1 changed file with 71 additions and 48 deletions.
119 changes: 71 additions & 48 deletions content/pages/framework-guides/astro.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <project-name>
```

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:

{{<Aside type="note">}}
Refer to Astro's available templates at [astro.new](https://astro.new).
{{</Aside>}}
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
```

{{<render file="_tutorials-before-you-start.md">}}

Expand All @@ -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.

{{<Aside type="note">}}

If no mode is set, the default is `"advanced"`

{{</Aside>}}

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**.
Expand All @@ -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` |
Expand Down Expand Up @@ -132,6 +101,60 @@ For the complete guide to deploying your first site to Cloudflare Pages, refer t

{{</Aside>}}

### 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.

{{<Aside type="note">}}

If no mode is set, the default is `"advanced"`.

{{</Aside>}}

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

0 comments on commit da6a7a8

Please sign in to comment.