Skip to content

Simplify documentation, remove extraneous content #850

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.

Sign up for GitHub

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

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
+36 −688
Open

Simplify documentation, remove extraneous content #850

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
9c66836
Simplify docs
irvinebroque Aug 4, 2024
09d5376
Simplify a few more things
irvinebroque Aug 4, 2024
87655a4
Add changeset
irvinebroque Aug 4, 2024
aa90cdb
Fix link
irvinebroque Aug 4, 2024
bcfc1bd
Prettier
irvinebroque Aug 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .changeset/cuddly-bulldogs-deny.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
'eslint-plugin-next-on-pages': patch
'@cloudflare/next-on-pages': patch
---

Simplify documentation
43 changes: 9 additions & 34 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,42 +1,17 @@
<p align="center">
<h1 align="center">⚡▲ <code>@cloudflare/next-on-pages</code> ▲⚡</h1>
# `@cloudflare/next-on-pages`

<p align="center">Build, develop, and deploy Next.js apps for Cloudflare Pages.</p>
</p>
`@cloudflare/next-on-pages` lets you build and deploy [Next.js](https://nextjs.org/) apps to [Cloudflare Pages](https://pages.cloudflare.com/).

`@cloudflare/next-on-pages` is a CLI tool that you can use to build and develop [Next.js](https://nextjs.org/) applications so that they can run on the [Cloudflare Pages](https://pages.cloudflare.com/) platform.
## Get started

Alongside the `@cloudflare/next-on-pages` there is an additional package `eslint-plugin-next-on-pages` implementing an Eslint plugin which aim is to aid developers at using the `@cloudflare/next-on-pages` more efficiently and improve their overall developer experience when working with it.
- [Getting Started Guide](https://developers.cloudflare.com/pages/framework-guides/nextjs/deploy-a-nextjs-site/)

You can see the packages contents (with their documentation) in their respective package directories:
## Components

- [`@cloudflare/next-on-pages`](https://github.com/cloudflare/next-on-pages/tree/main/packages/next-on-pages#cloudflarenext-on-pages)
- [`eslint-plugin-next-on-pages`](https://github.com/cloudflare/next-on-pages/tree/main/packages/eslint-plugin-next-on-pages#eslint-plugin-next-on-pages)

Additionally there is also the `next-dev` submodule which is implemented as a separate package in this repository but included as a submodule of the main `@cloudflare/next-on-pages` package, you can see the submodule's content here:

- [`@cloudflare/next-on-pages/next-dev`](https://github.com/cloudflare/next-on-pages/tree/main/internal-packages/next-dev)
- [`@cloudflare/next-on-pages`](https://github.com/cloudflare/next-on-pages/tree/main/packages/next-on-pages) — a CLI that runs `next build`, then transforms its output to run on Cloudflare Pages.
- [`@cloudflare/next-on-pages/next-dev`](https://github.com/cloudflare/next-on-pages/tree/main/internal-packages/next-dev) — lets you access [bindings](https://developers.cloudflare.com/workers/runtime-apis/bindings/) in local development of your Next.js app.
- [`eslint-plugin-next-on-pages`](https://github.com/cloudflare/next-on-pages/tree/main/packages/eslint-plugin-next-on-pages#eslint-plugin-next-on-pages) — lints your Next.js app to ensure it is configured to work on Cloudflare Pages.

## Contributing

If you want to contribute to this project (both to the main package and the eslint one) please refer to the [Contributing document](./docs/contributing.md).

## References

Extra references you might be interested in:

- [Blog post](https://blog.cloudflare.com/next-on-pages)

The original blog post introducing `@cloudflare/next-on-pages` (24/10/2022), it goes into details on the inspiration for this package and provides some details on how it works.

- [Cloudflare Next.js Guide](https://developers.cloudflare.com/pages/framework-guides/deploy-a-nextjs-site/)

Cloudflare guide on how to create and deploy a Next.js application. The application can be either static (and deployed as simple static assets) or dynamic using the edge runtime (using `@cloudflare/next-on-pages`).

- [Caching and Data Revalidation](./packages/next-on-pages/docs/caching.md)

Documentation on how the caching and data revalidation for applications built using `@cloudflare/next-on-pages` works.

- [Technical Documentation](./docs/technical)

Explanations and insights into how `@cloudflare/next-on-pages` works, design decisions behind different aspects, and how it handles different Next.js features.
We welcome external contributions — please refer to the [contribution guidelines](./docs/contributing.md).
18 changes: 0 additions & 18 deletions docs/contributing.md
View file
Original file line number Diff line number Diff line change
@@ -1,23 +1,5 @@
# Contributing

We're thrilled that you're considering contributing to the project! All contributions are greatly appreciated, regardless if they are simple issue reporting, bug fixes, documentation changes, etc...

No contribution is too small and all help moving the project forward!

## Submitting an bug report or feature request

If you find an bug or want to request a feature, open a [new issue](https://github.com/cloudflare/next-on-pages/issues/new) documenting it, please try to fill as much of the requested information as possible as that will help us dealing with the issue more effectively.

## Pull Requests

When opening a new PR make sure to set up an informative title for it and provide as much details as you can in the PR's description so that it is clear what its intentions are. This helps in simplifying and speeding up the reviewing process.

If your PR is addressing an existing issue make sure that it references the issue (as per the [Github PR Issues linking documentation](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue)) so that the two can be linked correctly (and the issue gets automatically closed on merge).

Smaller PRs are preferred since they are easier to review and merge quickly. If you're planning to make multiple unrelated (or loosely related) changes please consider splitting them in multiple PRs.

<!-- TODO: add section (or a link to a separate document) on how develop the packages locally -->

### Not sure what to contribute on?

If you're looking for something to help us with, what we believe would be most valuable to us is to either: try to implement Next.js functionality which we currently don't support (which you can see in the [Supported Versions and Features document](https://github.com/cloudflare/next-on-pages/blob/main/packages/next-on-pages/docs/supported.md)), or help us fix existing [issues](https://github.com/cloudflare/next-on-pages/issues).
88 changes: 9 additions & 79 deletions internal-packages/next-dev/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,82 +1,32 @@
# Next-on-pages Next-Dev
# `next-dev` (`setupDevPlatform`)

The `next-dev` submodule of the `@cloudflare/next-on-pages` package implements a utility that allows you to run the [standard Next.js development server](https://nextjs.org/docs/app/api-reference/next-cli#development) (with hot-code reloading, error reporting, HMR and everything it has to offer) with also local Cloudflare integration.

**IMPORTANT**: As mentioned above the module allows you to run the standard Next.js dev server as is and it only makes sure that a simulation of the Cloudflare specific data (retrievable using `getRequestContext`) is available. It does not generate a worker nor faithfully represent the final application that will be deployed to Cloudflare Pages, so please use this only as a development tool and make sure to properly test your application with `wrangler pages dev` before actually deploying it to Cloudflare.

## How to use the module

The module is part of the `@cloudflare/next-on-pages` package so it does not need installation, it exports the `setupDevPlatform` function which you need to import and call in your Next.js config file (`next.config.mjs` or `next.config.(c)js`). The utility will read your [`wrangler.toml`](https://developers.cloudflare.com/workers/wrangler/configuration/) gather information from it and use it to simulate the Cloudflare platform in the in the dev server.

After having created an appropriate `wrangler.toml` file and added the `setupDevPlatform` call to the Next.js config file you can simply run `next dev` and inside your edge routes you will be able to access your bindings via `getRequestContext` in the exact same way as you would in your production code.

`setupDevPlatform` uses wrangler's `getPlatformProxy` utility under the hood, it accepts the same exact arguments and supports bindings in the same exact manner, for more details please refer to the official [`getPlatformProxy` documentation](https://developers.cloudflare.com/workers/wrangler/api/#getplatformproxy).
`setupDevPlatform` lets you access [bindings](https://developers.cloudflare.com/workers/runtime-apis/bindings/) in local development of your Next.js app.

### Example

Let's see an example of how to use the utility, in a Next.js application built in TypeScript using the App router.

Firstly let's define a simple `wrangler.toml` file which only declares bindings:

```toml
[[kv_namespaces]]
binding = "MY_KV_1"
id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

[[kv_namespaces]]
binding = "MY_KV_2"
id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

[[durable_objects.bindings]]
name = "MY_DO"
script_name = "do-worker"
class_name = "DurableObjectClass"

[[r2_buckets]]
binding = "MY_R2"
bucket_name = "my-bucket"
```

Then we need update the `next.config.mjs` file:
[`next.config.mjs`](https://nextjs.org/docs/app/api-reference/next-config-js):

```js
// file: next.config.mjs

// we import the utility from the next-dev submodule
import { setupDevPlatform } from '@cloudflare/next-on-pages/next-dev';

/** @type {import('next').NextConfig} */
const nextConfig = {};

export default nextConfig;

// we only need to use the utility during development so we can check NODE_ENV
// (note: this check is recommended but completely optional)
if (process.env.NODE_ENV === 'development') {
// `await`ing the call is not necessary but it helps making sure that the setup has succeeded.
// If you cannot use top level awaits you could use the following to avoid an unhandled rejection:
// `setupDevPlatform().catch(e => console.error(e));`
await setupDevPlatform();
}
```

Next (optional but highly recommended) we create a [TypeScript declaration file](https://www.typescriptlang.org/docs/handbook/2/type-declarations.html) that defines/extends a `CloudflareEnv` interface (the same interface used by `getRequestContext`):
[`wrangler.toml`](https://developers.cloudflare.com/pages/functions/wrangler-configuration/):

```ts
// file: env.d.ts

interface CloudflareEnv {
MY_KV_1: KVNamespace;
MY_KV_2: KVNamespace;
MY_R2: R2Bucket;
MY_DO: DurableObjectNamespace;
}
```toml
[[kv_namespaces]]
binding = "MY_KV_1"
id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

> **Note**
> The binding types used in the above file come from `@cloudflare/workers-types`, in order to use them make sure that you've installed the package as a dev dependency and you've added it to your `tsconfig.js` file under `compilerOptions.types`.
Then we can simply use the platform and any of its bindings inside our Next.js application, for example in the following API route:
A route in your Next.js app:

```ts
export const runtime = 'edge';
@@ -90,23 +40,3 @@ export async function GET(request: NextRequest) {
return new Response(`The value of key-a in MY_KV is: ${valueA}`);
}
```

## Recommended development workflow

When developing a `next-on-pages` application, this is the development workflow that we recommend:

### Develop using the standard Next.js dev server

Develop your application using the [standard development server provided by Next.js](https://nextjs.org/docs/getting-started/installation#run-the-development-server). It is the best available option for a fast and polished development experience and the `next-dev` submodule makes it possible to use it while also being able to access a faithful simulation of the Cloudflare platform.

### Build and preview your application locally

In order to make sure that your application is being built in a manner that is fully compatible with Cloudflare Pages, before deploying it, or whenever you're comfortable checking the correctness of the application during your development process you'll want to build and preview it locally using Cloudflare's `workerd` JavaScript runtime.

To do so build your worker by using `@cloudflare/next-on-pages` and preview it locally via `wrangler pages dev .vercel/output/static --compatibility-flag nodejs_compat`.

By doing this, you can run your application locally to make sure everything is working as you expect it to.

### Deploy your app and iterate

Once you've previewed your application locally then you can deploy it to Cloudflare Pages (both via [direct uploads](https://developers.cloudflare.com/pages/get-started/direct-upload/) or [git integration](https://developers.cloudflare.com/pages/configuration/git-integration/)) and iterate over the process to make new changes.
17 changes: 7 additions & 10 deletions packages/eslint-plugin-next-on-pages/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,24 +1,18 @@
# `eslint-plugin-next-on-pages`

`eslint-plugin-next-on-pages` is an ESlint plugin intended to support developers developing Next.js application via `@cloudflare/next-on-pages`.
`eslint-plugin-next-on-pages` lints your Next.js app to ensure it is configured to work on Cloudflare Pages.

## Setup

To install the plugin run:

```sh
npm i --save-dev eslint-plugin-next-on-pages@V
npm i --save-dev eslint-plugin-next-on-pages
```

where `V` indicates the version of your `@cloudflare/next-on-pages` package.

> **Note**
> The `eslint-plugin-next-on-pages` package is versioned identically to `@cloudflare/next-on-pages`, this can be used to ensure that the two packages are in sync with each other. For best results make sure that the versions of the two packages are always the same.
Then simply register the plugin in your eslintrc file. As part of this we suggest to also extend the recommended configuration. After that you can also further tweak the available rules:
Add the plugin to your `.eslintrc.json`:

```diff
// .eslintrc.json
{
"plugins": [
+ "next-on-pages"
@@ -36,4 +30,7 @@ Then simply register the plugin in your eslintrc file. As part of this we sugges

## Rules

For more details check out the [rules documentation](https://github.com/cloudflare/next-on-pages/tree/main/packages/eslint-plugin-next-on-pages/docs/rules).
- [`next-on-pages/no-app-nodejs-dynamic-ssg`](https://github.com/cloudflare/next-on-pages/tree/main/packages/eslint-plugin-next-on-pages/docs/rules/no-app-nodejs-dynamic-ssg)
- [`next-on-pages/no-nodejs-runtime`](https://github.com/cloudflare/next-on-pages/tree/main/packages/eslint-plugin-next-on-pages/docs/rules/no-app-nodejs-runtime)
- [`next-on-pages/no-pages-nodejs-dynamic-ssg`](https://github.com/cloudflare/next-on-pages/tree/main/packages/eslint-plugin-next-on-pages/docs/rules/no-pages-nodejs-dynamic-ssg)
- [`next-on-pages/no-unsupported-configs`](https://github.com/cloudflare/next-on-pages/tree/main/packages/eslint-plugin-next-on-pages/docs/rules/no-unsupported-configs)
137 changes: 5 additions & 132 deletions packages/next-on-pages/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,137 +1,10 @@
# `@cloudflare/next-on-pages`

`@cloudflare/next-on-pages` is a CLI tool that you can use to build and develop [Next.js](https://nextjs.org/) applications so that they can run on the [Cloudflare Pages](https://pages.cloudflare.com/) platform (and integrate with Cloudflare's various other [product offerings](https://developers.cloudflare.com/pages/platform/functions/bindings/), such as KV, D1, R2, and Durable Objects).
## Get Started

This tool is a best-effort library implemented by the Cloudflare team and the community. As such, most, but not all, Next.js features are supported. See the [Supported Versions and Features document](https://github.com/cloudflare/next-on-pages/blob/main/packages/next-on-pages/docs/supported.md) for more details.
Follow [this guide](https://developers.cloudflare.com/pages/framework-guides/nextjs/deploy-a-nextjs-site/) to get started.

## Quick Start
## Components

This section describes how to bundle and deploy a (new or existing) Next.js application to [Cloudflare Pages](https://pages.cloudflare.com), using `@cloudflare/next-on-pages`.

### 1. Select your Next.js app

To start using `@cloudflare/next-on-pages`, you must have a Next.js project that you wish to deploy. If you already have one, change to its directory. Otherwise, you can use the `create-next-app` command to start a new one.

```sh
npx create-next-app@latest my-next-app
cd my-next-app
```

<details>
<summary>Note on the Next.js version</summary>

We have confirmed support for the current version of Next.js at the time of writing, `13.4.2`. Although we'll endeavor to keep support for newer versions, we cannot guarantee that we'll always be up-to-date with the latest version. If you experience any problems with `@cloudflare/next-on-pages`, you may wish to try pinning to `13.4.2` while we work on supporting any recent breaking changes.

</details>

### 2. Configure the application to use the Edge Runtime

For your application to run on Cloudflare Pages, it needs to opt in to use the Edge Runtime for routes containing server-side code (e.g. API Routes or pages that use `getServerSideProps`). To do this, export a `runtime` [route segment config](https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config#runtime) option from each file, specifying that it should use the Edge Runtime.

```typescript
export const runtime = 'edge';
```

&NewLine;

For more examples of this and for Next.js versions prior to v13.3.1, take a look at our [examples document](https://github.com/cloudflare/next-on-pages/blob/main/packages/next-on-pages/docs/examples.md). Additionally, ensure that your application is not using any unsupported [APIs](https://nextjs.org/docs/app/api-reference/edge#unsupported-apis) or [features](https://github.com/cloudflare/next-on-pages/blob/main/packages/next-on-pages/docs/supported.md).

### 3. Deploy your application to Cloudflare Pages

To deploy your application to Cloudflare Pages, you need to install the `@cloudflare/next-on-pages` package.

```sh
npm install -D @cloudflare/next-on-pages
```

Then you can deploy to Cloudflare Pages via the [automatic Git integration](https://developers.cloudflare.com/pages/platform/git-integration/). To do so, start by committing and pushing your application's code to a GitHub/GitLab repository.

Next, in the [Cloudflare Dashboard](https://dash.cloudflare.com/?to=/:account/pages), create a new Pages project:

- Navigate to the project creation pages (_Your account Home_ > _Workers & Pages_ > _Create application_ > _Pages_ > _Connect to Git_).
- Select the GitHub/GitLab repository you pushed your code to.
- Choose a project name and your production branch.
- Select _Next.js_ as the _Framework preset_ and provide the following options:
| Option | Value |
| ---------------------- | ---------------------------------- |
| Build command | `npx @cloudflare/next-on-pages@1` |
| Build output directory | `.vercel/output/static` |
- In the _Environment variables (advanced)_ section, add a new variable named `NODE_VERSION` set to `16` or greater.
- Click on _Save and Deploy_ to start the deployment (this first deployment won't be fully functional as the next step is also necessary).
- Go to the Pages project settings page (_Settings_ > _Functions_ > _Compatibility Flags_), **add the `nodejs_compat` flag** for both production and preview, and make sure that the **Compatibility Date** for both production and preview is set to at least `2022-11-30`.

> If you don't want to set up a Git repository, you can build your application (as indicated in [Local Development](#local-development)) and publish it manually via the [`wrangler pages publish` command](https://developers.cloudflare.com/workers/wrangler/commands/#publish-1) instead (you'll still need to set the **`nodejs_compat`** flag for your project in the Cloudflare dashboard).
> **Note**:
> When deploying via the Git integration, for better compatibility with tools such as `yarn` and `pnpm` we recommend using the Build system version 2 (that is the default so no action is required).
## Recommended development workflow

When developing a `next-on-pages` application, this is the development workflow that Cloudflare recommends:

### Develop using the standard Next.js dev server

The [standard development server provided by Next.js](https://nextjs.org/docs/getting-started/installation#run-the-development-server) is the best available option for a fast and polished development experience. The `next-dev` submodule makes it possible to use Next.js' standard development server while still having access to your Cloudflare bindings.

### Build and preview your application locally

To ensure that your application is being built in a manner that is fully compatible with Cloudflare Pages, before deploying it, or whenever you are comfortable checking the correctness of the application during your development process, you will want to build and preview it locally using Cloudflare's `workerd` JavaScript runtime.

Do this by running:

```sh
npx @cloudflare/next-on-pages
```

And preview your project by running:

```sh
npx wrangler pages dev .vercel/output/static
```

> [!NOTE]
> The [`wrangler pages dev`](/workers/wrangler/commands/#dev-1) command needs to run the application using the [`nodejs_compat`](/workers/configuration/compatibility-dates/#nodejs-compatibility-flag) compatibility flag. The `nodejs_compat` flag can be specified in either your project's `wrangler.toml` file or provided to the command as an inline argument: `--compatibility-flag=nodejs_compat`.
### Deploy your application and iterate

After you have previewed your application locally, you can deploy it to Cloudflare Pages (both via [Direct Uploads](/pages/get-started/direct-upload/) or [Git integration](/pages/configuration/git-integration/)) and iterate over the process to make new changes.

## Cloudflare Platform Integration

Next.js applications built using `@cloudflare/next-on-pages` get access to resources and information only available or relevant on the Cloudflare platform, such are:

- [Bindings (`env`)](https://developers.cloudflare.com/pages/platform/functions/bindings/), which allows you to take advantage of Cloudflare specific resources.
- [Cloudflare properties (`cf`)](https://developers.cloudflare.com/workers/runtime-apis/request/#incomingrequestcfproperties), object containing information about the request provided by Cloudflare’s global network.
- [Lifecycle methods (`ctx`)](https://developers.cloudflare.com/workers/runtime-apis/handlers/fetch/#lifecycle-methods), methods to augment or control how the request is handled.

Such can be accessed by calling the `getRequestContext` function in server only code.

For example:

```ts
import { getRequestContext } from '@cloudflare/next-on-pages';

// ...

const { env, cf, ctx } = getRequestContext();
```

> **Warning**: The function cannot be called in code from components using the Pages router.
> **Note**: In order to make the function work in development mode (using the standard Next.js dev server) use the [`@cloudflare/next-on-pages/next-dev`](https://github.com/cloudflare/next-on-pages/tree/main/internal-packages/next-dev) submodule.
> **TypeScript Env Type**: the `env` object returned by `getRequestContext` implements the `CloudflareEnv` interface, add your binding types to such interface in order for get a correctly typed `env` object.
> **Note**: `getRequestContext` throws an error if invoked when the request context is not available, if you prefer to receive `undefined` in such cases use `getOptionalRequestContext` instead, the latter is identical to `getRequestContext` except from the fact that it returns `undefined` when the context is not available.
## Examples

To see some examples on how to use Next.js features with `@cloudflare/next-on-pages`, see the [Examples document](https://github.com/cloudflare/next-on-pages/blob/main/packages/next-on-pages/docs/examples.md).

## Troubleshooting

If you find yourself hitting some issues with `@cloudflare/next-on-pages` please check out our [official troubleshooting documentation](https://developers.cloudflare.com/pages/framework-guides/nextjs/deploy-a-nextjs-site/#troubleshooting).

## More Information

For more information on the project please check out the [README](https://github.com/cloudflare/next-on-pages/blob/main/README.md) in the next-on-pages github repository.
- `npx @cloudflare/next-on-pages` — a CLI that runs `next build`, then transforms its output to run on Cloudflare Pages.
- [`setupDevPlatform`](https://github.com/cloudflare/next-on-pages/tree/main/internal-packages/next-dev) — lets you access [bindings](https://developers.cloudflare.com/workers/runtime-apis/bindings/) in local development of your Next.js app.
34 changes: 0 additions & 34 deletions packages/next-on-pages/docs/advanced-usage.md
View file

This file was deleted.

31 changes: 0 additions & 31 deletions packages/next-on-pages/docs/caching.md
View file

This file was deleted.

155 changes: 0 additions & 155 deletions packages/next-on-pages/docs/examples.md
View file

This file was deleted.

18 changes: 0 additions & 18 deletions packages/next-on-pages/docs/static-assets-routing.md
View file

This file was deleted.

177 changes: 0 additions & 177 deletions packages/next-on-pages/docs/supported.md
View file

This file was deleted.