cloudflare-docs icon indicating copy to clipboard operation
cloudflare-docs copied to clipboard

Published 20 hours ago • verified publisher icon cloudflare

Various Node version issues (e.g. mismatches)

Open mrienstra opened this issue 1 year ago • 0 comments

Which Cloudflare product(s) does this pertain to?

Pages, Workers

Existing documentation URL(s)

  • https://developers.cloudflare.com/pages/framework-guides/astro
  • https://developers.cloudflare.com/pages/framework-guides/deploy-a-qwik-site
  • https://developers.cloudflare.com/pages/framework-guides/deploy-a-svelte-site
  • https://developers.cloudflare.com/pages/framework-guides/remix
  • https://developers.cloudflare.com/pages/how-to/use-direct-upload-with-continuous-integration

Overview of Node requirements (as far as I can gather)

Wrangler: v16.13.0 https://developers.cloudflare.com/workers/wrangler/get-started/ (also: [email protected]: >=16.13.0: https://github.com/cloudflare/wrangler2)

Miniflare: v16.13.0 https://miniflare.dev/get-started/cli#installation

Cloudflare Workers Types: ^16.6.1 https://github.com/cloudflare/workers-types (should probably be ^16.13.0)

Cloudflare Pages: defaults to v12.18.0, supports "Any version up to 17.x": https://developers.cloudflare.com/pages/platform/build-configuration/#language-support-and-tools

Issues with docs

pages/framework-guides/astro (github, website)

L109:

NODE_VERSION: 14

L117:

NODE_VERSION variable with a value of 16.13

Reading over docs and https://github.com/cloudflare/cloudflare-docs/pull/5730, seems like line 109 should say "NODE_VERSION: 16.13." Or if there are actually two NODE_VERSION environment variables, and the first one mentioned is fine being <16, it should at least be "NODE_VERSION: 14.18", as that is the lowest version supported by Astro.

pages/framework-guides/deploy-a-qwik-site (github, website)

L61:

requires a newer node version >14.0.0 [...] add NODE_VERSION = v16.7.0

  1. "requires a newer node version >14.0.0" needs a small grammar tweak, like "requires a newer Node version (>14.0.0)" or "requires Node >14.0.0".
  2. Jumps from saying it requires >14 to saying to use v16.7.0 with no explanation. Guessing it should say "NODE_VERSION = 14", but if it needs v16 to support Workers, then it should say "NODE_VERSION = 16.13," 16.7 is too old for Workers.

pages/framework-guides/deploy-a-svelte-site (github, website)

L65:

NODE_VERSION: 17

L73:

requires Node.js >=16.9 or later [...] add a NODE_VERSION variable with a value of 17 or greater.

L171:

NODE_VERSION: 17

  1. ">=16.9 or later" is redundant.
  2. Jumps from saying it requires >=16.9 to saying to use 17 with no explanation. Should probably say "16.9" on lines 65, 73 & 171.
  3. Scratch that, SvelteKit now requires 16.14 (PR).
  4. Might as well also change line 15 "is still in beta" & "beta phase" to... "is in release candidate phase for 1.0" & "release candidate phase".

pages/framework-guides/remix (github, website)

L62:

requires a newer node version >14.0.0 [...] add NODE_VERSION = v16.7.0

  1. "requires a newer node version >14.0.0" needs a small grammar tweak, like "requires a newer Node version (>14.0.0)" or "requires Node >14.0.0".
  2. Jumps from saying it requires >14.0.0 to saying to use v16.7.0 with no explanation. Should probably say "NODE_VERSION = 14", but if it needs v16 to support Workers, then it should say "NODE_VERSION = 16.13", 16.7 is too old for Workers.

pages/how-to/use-direct-upload-with-continuous-integration (github, website)

L131:

cimg/node:18.7.0

L146:

docker image cimg/node:18

Line 146 should say "cimg/node:18.7.0" to match line 131 (or vice versa).

L150:

Node version less than 16 [...] upgrade your Node version as Wrangler requires at least Node.js v16.7.0

  1. Nitpick, but "less than 16" should be "less than 16.13".
  2. Wrangler requires 16.13.0 or later, v16.7.0 is too old.

L176:

"18.0.0"

L192:

listed the value as 16.7.0 because Wrangler 2 depends on this Node version or higher.

  1. On line 176, ""18.0.0"" --> ""16.13.0"", as Wrangler requires 16.13.0 or later.
  2. Line 192, "16.7.0" --> "16.13.0", so the two versions match, and so they both meet current Wrangler requirements.

To find many of the above (in VS Code), I used: \bnode(\d[\d\.]*|[^s\d][^\d]*?(v?\d[\d\.]*)) files to include: *.md

Could be helpful to draw a clearer distinction between:

  1. Static site built with Pages: >= v12.18, < v18.
  2. SSR rendering or Functions (Workers): >= v16.13.

And maybe just recommend using >= v16.13 whenever possible, to avoid having to be aware of this "boundary".

Might be useful to review when Node versions are prefixed with "v" (and when they are not) in documentation & in code samples, and make sure it's consistent, and maybe explain when to use which, and when they are interchangeable. Not that I expect these docs to cover all the different places that are touched on, but at least make sure it's clear for the places that are somewhat Cloudflare-specific (like setting the NODE_VERSION environment variable using your UI).

Node.js doesn't use "v" when talking about versions: https://github.com/nodejs/release#release-schedule ... But does when tagging releases: https://github.com/nodejs/node/tags

Feel free to edit this to include a task list.

PS: Sorry for breaking out of the issue template!

mrienstra avatar Sep 21 '22 09:09 mrienstra