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.

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

Simplify documentation, remove extraneous content #850

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Simplify documentation, remove extraneous content #850

Show file tree
Hide file tree
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
Open in desktop
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
Open in desktop
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
Open in desktop
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).
Expand Down
88 changes: 9 additions & 79 deletions internal-packages/next-dev/README.md
View file
Open in desktop
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';
Expand All @@ -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
Open in desktop
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"
Expand All @@ -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)
Loading
Loading