Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Pages] Update Nuxt framework guide and improve bindings coverage #12953

Merged
merged 17 commits into from
Feb 23, 2024
Merged
98 changes: 80 additions & 18 deletions content/pages/framework-guides/deploy-a-nuxt-site.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,40 +11,85 @@ In this guide, you will create a new Nuxt application and deploy it using Cloudf

## Create a new project

Use the [`create-cloudflare`](https://www.npmjs.com/package/create-cloudflare) CLI (C3) to set up a new project. C3 will create a new project directory, initiate Nuxt's official setup tool, and provide the option to deploy instantly.

To use `create-cloudflare` to create a new Nuxt project, run the following command:
The easiest way to get started is by using the [`create-cloudflare`](https://www.npmjs.com/package/create-cloudflare) CLI (also known as C3). To do so, open a terminal and run:

```sh
$ npm create cloudflare@latest my-nuxt-app -- --framework=nuxt
```

`create-cloudflare` will then install dependencies, including the [Wrangler](/workers/wrangler/install-and-update/#check-your-wrangler-version) CLI, and ask you setup questions.
C3 will create a new project with `nuxi` (The official Nuxt cli) and install the necessary adapters along with the [Wrangler CLI](/workers/wrangler/install-and-update/#check-your-wrangler-version).

## Migrating an existing Nuxt application
jculvey marked this conversation as resolved.
Show resolved Hide resolved

After you have installed your project dependencies, start your application:
Add `wrangler` to your project:

```sh
$ npm run dev
$ npm install --save-dev wrangler@latest
```

Update the deploy script in `package.json`:

```json
---
filename: package.json
---
{
// ...
"scripts": {
// ...
"deploy": "npm run build && wrangler pages deploy ./dist"
}
}
```

{{<render file="_tutorials-before-you-start.md">}}
## Deploy your project

{{<render file="_create-github-repository.md">}}
After creating your new project, C3 will give you the option of deploying an initial version of your application via [Direct Upload](/pages/how-to/use-direct-upload-with-continuous-integration/). You can re-deploy your application at any time by running following command inside your project directory:

## Deploy with Cloudflare Pages
```sh
$ npm run deploy
```

{{<render file="_deploy-via-c3.md" withParameters="Nuxt">}}
You can instead [connect a GitHub or Gitlab repository](/pages/configuration/git-integration) to your Pages project so that new versions of your project are built and deployed when changes to your git repository are detected. To do so, choose “No” when C3 asks if you’d like to deploy and refer to the guide below.
dario-piotrowicz marked this conversation as resolved.
Show resolved Hide resolved
dario-piotrowicz marked this conversation as resolved.
Show resolved Hide resolved
dario-piotrowicz marked this conversation as resolved.
Show resolved Hide resolved
jculvey marked this conversation as resolved.
Show resolved Hide resolved

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

This requires a basic understanding of [Git](https://git-scm.com/). If you are new to Git, refer to this [summarized Git handbook](https://guides.github.com/introduction/git-handbook/) on how to set up Git on your local machine.

{{</Aside>}}

### Create a new GitHub repository

Create a new GitHub repository by visiting [repo.new](https://repo.new). Next, prepare and push your local application to GitHub by running the following commands in your terminal:

```sh
# Skip the following 3 commands if you've built your application
# using C3 or already committed your changes
$ git init
$ git add .
$ git commit -m "Initial commit"

$ git branch -M main
$ git remote add origin https://github.com/<your-gh-username>/<repository-name>
$ git push -u origin main
```

### Deploy via the Cloudflare dashboard
### Create a Pages project

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account.
2. In Account Home, select **Workers & Pages** > **Create application** > **Pages** > **Connect to Git**.
2. Navigate to [Workers & Pages > Create application > Pages > Connect to Git](https://dash.cloudflare.com/?to=/:account/pages/new/provider/github) and create a new pages project.

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

Note that git integration cannot currently be added to existing Pages applications, so if you've already deployed your application via Direct Upload (using C3 for example), you will still need to create a new Pages application in order to proceed.

{{</Aside>}}

You will be asked to authorize access to your GitHub account if you have not already done so. Cloudflare needs this so that it can monitor and deploy your projects from the source. You may narrow access to specific repositories if you prefer; however, you will have to manually update this list [within your GitHub settings](https://github.com/settings/installations) when you want to add more repositories to Cloudflare Pages.

Select the new GitHub repository that you created and, in the **Set up builds and deployments** section, provide the following information:

{{<pages-build-preset framework="nuxt-js">}}
{{<pages-build-preset framework="nuxt">}}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this change is correct:
Screenshot 2024-02-13 at 18 41 10

If you want to rename the preset you'll also have to rename it here I think:

But I'd be careful about the above since I think this file is also used to generate the dashboard presets... so before updating it I double check that it is ok to do so


Optionally, you can customize the **Project name** field. It defaults to the GitHub repository's name, but it does not need to match. The **Project name** value is assigned as your `*.pages.dev` subdomain.

Expand All @@ -56,15 +101,32 @@ Cloudflare Pages will automatically rebuild your project and deploy it on every

Additionally, you will have access to [preview deployments](/pages/configuration/preview-deployments/), which repeat the build-and-deploy process for pull requests. With these, you can preview changes to your project with a real URL before deploying them to production.

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

A [binding](/pages/functions/bindings/) allows your application to interact with Cloudflare developer products, such as [KV](/kv/reference/how-kv-works/), [Durable Object](/durable-objects/), [R2](/r2/), and [D1](https://blog.cloudflare.com/introducing-d1/).

If you intend to use bindings in your project, you must first set them up for local and remote development.

For the complete guide to deploying your first site to Cloudflare Pages, refer to the [Get started guide](/pages/get-started/).
Projects created via C3 come with `nitro-cloudflare-dev`, a `nitro` module that simplifies the process of working with bindings during development:

```typescript
---
filename: nuxt.config.ts
deadlypants1973 marked this conversation as resolved.
Show resolved Hide resolved
---
export default defineNuxtConfig({
modules: ["nitro-cloudflare-dev"],
});
```

This module is powered by the `getBindingsProxy` [helper function](/workers/wrangler/api#getbindingsproxy) which will automatically detect any bindings defined in the `wrangler.toml` file and emulate them in local development. See [Wrangler configuration](workers/wrangler/configuration/#bindings) for more information on how to configure bindings in `wrangler.toml`.
dario-piotrowicz marked this conversation as resolved.
Show resolved Hide resolved
deadlypants1973 marked this conversation as resolved.
Show resolved Hide resolved

{{<Aside type="note">}}
`wrangler.toml` is currently **only** used for local development. Bindings specified in it are not available remotely.
{{</Aside>}}

## Use bindings in your Nuxt application
In order to access bindings in a deployed application, you will need to [configure them](/pages/functions/bindings/) in the Cloudflare dashboard on your project's settings page.

A [binding](/pages/functions/bindings/) allows your application to interact with Cloudflare developer products, such as [KV](/kv/reference/how-kv-works/), [Durable Object](/durable-objects/), [R2](/r2/), and [D1](https://blog.cloudflare.com/introducing-d1/).
### Accessing bound resources in your Nuxt application
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

calling "bindings" "bound resources" make things more confusing in my opinion 😅


In Nuxt, add server-side code via [Server Routes and Middleware](https://nuxt.com/docs/guide/directory-structure/server#server-directory). The `defineEventHandler()` method is used to define your API endpoints in which you can access Cloudflare's context via the provided `context` field. The `context` field allows you to access any bindings set for your application.

Expand All @@ -85,4 +147,4 @@ export default defineEventHandler(({ context }) => {
});
```

{{<render file="_learn-more.md" withParameters="Nuxt">}}
{{<render file="_learn-more.md" withParameters="Nuxt">}}
Loading