Documentation: Mention expected workflow for local builds and dev mode.

[janpio]

https://developers.cloudflare.com/pages/framework-guides/deploy-a-nextjs-site/, the main documentation for this approach, does not mention how to locally use build, dev, pages:build, and pages:dev to develop. I think it would be very nice to add that.

Related question in Discord #next-on-pages: https://discord.com/channels/595317990191398933/1135899572141568050/1186764035497140335

[dario-piotrowicz]

Hi @janpio thanks a lot for the issue 🙂

For now I've documented the recommended workflow here: https://github.com/cloudflare/next-on-pages/tree/main/internal-packages/next-dev#recommended-workflow (yeah not super discoverable, is it? 😓)

The next-dev submodule is however still experimental (we just need to finalize its API see #527), as soon as it is finalized I'll make sure to update the Cloudflare docs accordingly 🙂👍

[antsorin]

Thank you for the info, it helped me a lot.

Maybe it helps others who read this: while the next-dev submodule is still experimental, getting the setupDevBidnings can be made with:

const { setupDevBindings } = require('@cloudflare/next-on-pages/__experimental__next-dev');

instead of:

const { setupDevBindings } = require('@cloudflare/next-on-pages/next-dev');

[antsorin]

Also it's worth mentioning that setupDevBindings supports additional options, e.g.:

textBindings: {
    ENVIRONMENT: "development"
},
d1Databases: ['MY_D1'],
persist: "tmp/state/v3"

Full list of options is available here.

Note that if you change the persist path and want to have both npm run dev and pages:dev to point to the same data, the paths need to be slightly different when specifying them in next.config.js vs package.json (one needs the v3 suffix):

// next.config.js
persist: "tmp/state/v3"

vs

// package.json
"pages:dev": "npx wrangler pages dev .vercel/output/static --compatibility-date=2023-12-18 --compatibility-flag=nodejs_compat --persist-to=tmp/state"

[dario-piotrowicz]

I'm closing this issue since setupDevBindings has been documented in our docs: https://developers.cloudflare.com/pages/framework-guides/nextjs/deploy-a-nextjs-site/

(it is also getting updated with the newer setupDevPlatform function (which replaces setupDevBindings): cloudflare/cloudflare-docs#13001)

Hopefully this is enough, @janpio and @antsorin please let me know if you think it isn't

(@antsorin in our docs we didn't include options to try not to be too verbose there... I hope that typescript and IDE intellisense/autocompletion should get people discover all the various options if need be, please let me know if you disagree 🙂)

[antsorin]

(@antsorin in our docs we didn't include options to try not to be too verbose there... I hope that typescript and IDE intellisense/autocompletion should get people discover all the various options if need be, please let me know if you disagree 🙂)

I agree. 🙂

My comment also pointed out a small inconsistency related to the persist option, which needs to include the v3 dir in next.config.js, but it is implied with the --persist-to CLI option.

// next.config.js
persist: "tmp/state/v3"

// CLI - will actually be persisted in tmp/state/v3
--persist-to=tmp/state"

It's not super important, I just wrote about it in case someone finds it helpful.

[dario-piotrowicz]

Thanks @antsorin 😄

Yeah I feel like that small inconsistency can trip someone over 😓, thanks for the reminder...

It might be worth pointing out

I've opened this PR in our docs repo: cloudflare/cloudflare-docs#13070

Please let me know what you think 🙂

---

PS: Note that this is in the generic Cloudflare docs and not in this repo's docs because in the setupDevPlatform we do refer to the getPlatformProxy docs instead of re-listing all the various options:

next-on-pages/internal-packages/next-dev/README.md

Line 13 in 90e140c

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

[antsorin]

Please let me know what you think 🙂

Looks great to me, thanks for adding the note!