|
1 | | -This is a [Next.js](https://nextjs.org/) project bootstrapped with [`c3`](https://developers.cloudflare.com/pages/get-started/c3). |
| 1 | +## Cloudflare Pages |
2 | 2 |
|
3 | | -## Getting Started |
| 3 | +Cloudflare's [wrangler](https://github.com/cloudflare/wrangler) CLI can be used to preview a production build locally. To start a local server, run: |
4 | 4 |
|
5 | | -First, run the development server: |
6 | | - |
7 | | -```bash |
8 | | -npm run dev |
9 | | -# or |
10 | | -yarn dev |
11 | | -# or |
12 | | -pnpm dev |
13 | | -# or |
14 | | -bun dev |
| 5 | +``` |
| 6 | +pnpm serve |
15 | 7 | ``` |
16 | 8 |
|
17 | | -Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. |
18 | | - |
19 | | -## Cloudflare integration |
20 | | - |
21 | | -Besides the `dev` script mentioned above `c3` has added a few extra scripts that allow you to integrate the application with the [Cloudflare Pages](https://pages.cloudflare.com/) environment, these are: |
22 | | - - `pages:build` to build the application for Pages using the [`@cloudflare/next-on-pages`](https://github.com/cloudflare/next-on-pages) CLI |
23 | | - - `preview` to locally preview your Pages application using the [Wrangler](https://developers.cloudflare.com/workers/wrangler/) CLI |
24 | | - - `deploy` to deploy your Pages application using the [Wrangler](https://developers.cloudflare.com/workers/wrangler/) CLI |
25 | | - |
26 | | -> __Note:__ while the `dev` script is optimal for local development you should preview your Pages application as well (periodically or before deployments) in order to make sure that it can properly work in the Pages environment (for more details see the [`@cloudflare/next-on-pages` recommended workflow](https://github.com/cloudflare/next-on-pages/blob/05b6256/internal-packages/next-dev/README.md#recommended-workflow)) |
27 | | -
|
28 | | -### Bindings |
| 9 | +Then visit [http://localhost:8787/](http://localhost:8787/) |
29 | 10 |
|
30 | | -Cloudflare [Bindings](https://developers.cloudflare.com/pages/functions/bindings/) are what allows you to interact with resources available in the Cloudflare Platform. |
| 11 | +### Deployments |
31 | 12 |
|
32 | | -You can use bindings during development, when previewing locally your application and of course in the deployed application: |
| 13 | +[Cloudflare Pages](https://pages.cloudflare.com/) are deployable through their [Git provider integrations](https://developers.cloudflare.com/pages/platform/git-integration/). |
33 | 14 |
|
34 | | -- To use bindings in dev mode you need to define them in the `next.config.js` file under `setupDevBindings`, this mode uses the `next-dev` `@cloudflare/next-on-pages` submodule. For more details see its [documentation](https://github.com/cloudflare/next-on-pages/blob/05b6256/internal-packages/next-dev/README.md). |
| 15 | +If you don't already have an account, then [create a Cloudflare account here](https://dash.cloudflare.com/sign-up/pages). Next go to your dashboard and follow the [Cloudflare Pages deployment guide](https://developers.cloudflare.com/pages/framework-guides/deploy-anything/). |
35 | 16 |
|
36 | | -- To use bindings in the preview mode you need to add them to the `pages:preview` script accordingly to the `wrangler pages dev` command. For more details see its [documentation](https://developers.cloudflare.com/workers/wrangler/commands/#dev-1) or the [Pages Bindings documentation](https://developers.cloudflare.com/pages/functions/bindings/). |
| 17 | +Within the projects "Settings" for "Build and deployments", the "Build command" should be `pnpm build`, and the "Build output directory" should be set to `dist`. |
37 | 18 |
|
38 | | -- To use bindings in the deployed application you will need to configure them in the Cloudflare [dashboard](https://dash.cloudflare.com/). For more details see the [Pages Bindings documentation](https://developers.cloudflare.com/pages/functions/bindings/). |
| 19 | +### Function Invocation Routes |
39 | 20 |
|
40 | | -#### KV Example |
| 21 | +Cloudflare Page's [function-invocation-routes config](https://developers.cloudflare.com/pages/platform/functions/routing/#functions-invocation-routes) can be used to include, or exclude, certain paths to be used by the worker functions. Having a `_routes.json` file gives developers more granular control over when your Function is invoked. |
| 22 | +This is useful to determine if a page response should be Server-Side Rendered (SSR) or if the response should use a static-site generated (SSG) `index.html` file. |
41 | 23 |
|
42 | | -`c3` has added for you an example showing how you can use a KV binding. |
| 24 | +By default, the Cloudflare pages adaptor _does not_ include a `public/_routes.json` config, but rather it is auto-generated from the build by the Cloudflare adaptor. An example of an auto-generate `dist/_routes.json` would be: |
43 | 25 |
|
44 | | -In order to enable the example: |
45 | | -- Search for javascript/typescript lines containing the following comment: |
46 | | - ```ts |
47 | | - // KV Example: |
48 | | - ``` |
49 | | - and uncomment the commented lines below it. |
50 | | -- Do the same in the `wrangler.toml` file, where |
51 | | - the comment is: |
52 | | - ``` |
53 | | - # KV Example: |
54 | | - ``` |
55 | | -- If you're using TypeScript run the `cf-typegen` script to update the `env.d.ts` file: |
56 | | - ```bash |
57 | | - npm run cf-typegen |
58 | | - # or |
59 | | - yarn cf-typegen |
60 | | - # or |
61 | | - pnpm cf-typegen |
62 | | - # or |
63 | | - bun cf-typegen |
64 | | - ``` |
| 26 | +``` |
| 27 | +{ |
| 28 | + "include": [ |
| 29 | + "/*" |
| 30 | + ], |
| 31 | + "exclude": [ |
| 32 | + "/_headers", |
| 33 | + "/_redirects", |
| 34 | + "/build/*", |
| 35 | + "/favicon.ico", |
| 36 | + "/manifest.json", |
| 37 | + "/service-worker.js", |
| 38 | + "/about" |
| 39 | + ], |
| 40 | + "version": 1 |
| 41 | +} |
| 42 | +``` |
65 | 43 |
|
66 | | -After doing this you can run the `dev` or `preview` script and visit the `/api/hello` route to see the example in action. |
| 44 | +In the above example, it's saying _all_ pages should be SSR'd. However, the root static files such as `/favicon.ico` and any static assets in `/build/*` should be excluded from the Functions, and instead treated as a static file. |
67 | 45 |
|
68 | | -Finally, if you also want to see the example work in the deployed application make sure to add a `MY_KV_NAMESPACE` binding to your Pages application in its [dashboard kv bindings settings section](https://dash.cloudflare.com/?to=/:account/pages/view/:pages-project/settings/functions#kv_namespace_bindings_section). After having configured it make sure to re-deploy your application. |
| 46 | +In most cases the generated `dist/_routes.json` file is ideal. However, if you need more granular control over each path, you can instead provide you're own `public/_routes.json` file. When the project provides its own `public/_routes.json` file, then the Cloudflare adaptor will not auto-generate the routes config and instead use the committed one within the `public` directory. |
0 commit comments