npm create cloudflare onboarding experience is very rough

[Cherry]

Which Cloudflare product(s) does this pertain to?

C3

What version(s) of the tool(s) are you using?

2.1.0

What version of Node are you using?

18.17.1

What operating system are you using?

Windows

Describe the Bug

I just spun up a brand new project using create cloudflare and ran into a pretty rough onboarding experience with DX.

• npm create cloudflare@latest - use all defaults
• wrangler.toml compat date is set to 2023-08-12 (the current date)
• @cloudflare/workers-types version in my package.json is ^4.20230419.0 - 3 months old
• tsconfig.json types includes @cloudflare/workers-types default with no compat date (so sometime in 2021)
• typescript is set to ^5.0.4 despite wrangler (via esbuild) not supporting most (any?) TypeScript 5 features

Now if you try do something like this in your worker, it'll work at runtime because your compat date is modern, but your types are old so you get errors when treating things as a File in dev:

const body = await request.formData();
const file = body.get('file'); // string | null, not possible to be a `File` according to current types
if(file instanceof File){
   // stuff
}

And you also get warnings like this (related: cloudflare/miniflare#666):

[mf:wrn] The latest compatibility date supported by the installed Cloudflare Workers Runtime is "2023-08-07",
but you've requested "2023-08-12". Falling back to "2023-08-07"...

So then, to get my environment in a working state without type errors, and warnings, I had to go figure out the latest "supported" compat date, and workers types version I could actually use.

This seems to be 2022-11-30 for types, so I have to update my tsconfg.json to include @cloudflare/workers-types/2022-11-30 instead. I knew exactly where to look to find this, understanding the compat date/flag concepts, but the same is unlikely to be said for new users - this being a different date to my compat date is very weird.

And then for workerd it seems to be 2023-08-07 so now I have to update my wrangler.toml too so this removes the miniflare warning.

It ALSO sets my typescript version to 5.x which implies I'm able to use newer TypeScript syntax like this (not real world, but simple example using const type paramaters):

type HasNames = { names: readonly string[] };
function getNamesExactly<const T extends HasNames>(arg: T): T["names"] {
  return arg.names;
}

This passes all type checking and is valid with TypeScript 5.x, so my editor is fine with it. But when I try and run, I get weird syntax errors due to the old esbuild version wrangler is using. Related: #2980

So now, as a user to get my development environment into a completely functional state, I have to specifically change my types to match a compat date, change my compat date to a "supported" one, and then also make sure I'm not writing any actual code that's TypeScript 5 syntax, or downgrade to TypeScript 4, assuming I have a deep enough understanding of everything to come to those conclusions. Once ALL of that is done, I can finally get to actually writing my worker without errors and warnings.

---

All of these things in isolation seem reasonable, but as an ecosystem this doesn't feel very coherent right now unfortunately.

[Cherry]

Update: I retried this today and it looks like my compat date was set to 2023-08-07 this time, removing that step. I must have hit a previously cached version before or something. That does remove one painful step in the onboarding, though is still very weird behaviour in my opinion (but more discussion of that here: cloudflare/miniflare#666).

[Cherry]

A user running into similar issues and confusion:

https://community.cloudflare.com/t/workers-compatibility-date-issue/548087?u=cherryjimbo

[geekodour]

I am not sure if this is related but I just ran npm create cloudflare@latest and then npm start which runs wrangler dev and I get the following:

 ⛅️ wrangler 3.5.1
------------------
wrangler dev now uses local mode by default, powered by 🔥 Miniflare and 👷 workerd.
To run an edge preview session for your Worker, use wrangler dev --remote
⎔ Starting local server...
╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ [b] open a browser, [d] open Devtools, [l] turn off local mode, [c] clear console, [x] to exit                                                                                                                                                                                          │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
/home/PROJECT_PATH/node_modules/wrangler/wrangler-dist/cli.js:30632
            throw a;
            ^

Error: spawn /home/PROJECT_PATH/node_modules/@cloudflare/workerd-linux-64/bin/workerd ENOENT
    at ChildProcess._handle.onexit (node:internal/child_process:283:19)
    at onErrorNT (node:internal/child_process:476:16)
    at process.processTicksAndRejections (node:internal/process/task_queues:82:21)
Emitted 'error' event on ChildProcess instance at:
    at ChildProcess._handle.onexit (node:internal/child_process:289:12)
    at onErrorNT (node:internal/child_process:476:16)
    at process.processTicksAndRejections (node:internal/process/task_queues:82:21) {
  errno: -2,
  code: 'ENOENT',
  syscall: 'spawn /home/PROJECT_PATH/node_modules/@cloudflare/workerd-linux-64/bin/workerd',
  path: '/home/PROJECT_PATH/node_modules/@cloudflare/workerd-linux-64/bin/workerd',
  spawnargs: [
    'serve',
    '--binary',
    '--experimental',
    '--socket-addr=entry=0.0.0.0:8787',
    '--external-addr=loopback=localhost:35593',
    '--control-fd=3',
    '-',
    '--inspector-addr=127.0.0.1:35805'
  ]
}

Node.js v18.16.1

currently working around with --remote till i get a chance into the original issue

[Cherry]

Hit this rough onboarding experience again today when spinning up a new worker.

I created a new TypeScript worker using C3, with gave me a fresh worker with a 2023-11-21 compat date, cool. I then started writing code like this:

if (navigator.userAgent === 'Cloudflare-Workers') {

but was immediately hit with a typescript error:

Cannot find name 'navigator'.ts(2304)

I eventually realised this was due to my tsconfig.json including @cloudflare/workers-types as my types, years old, instead of a more appropriate date for my worker, which in this case seems to be @cloudflare/workers-types/2023-07-01 when reviewing https://www.npmjs.com/package/@cloudflare/workers-types.

I had to stop and think for quite some time when I hit https://www.npmjs.com/package/@cloudflare/workers-types too. My compat date is 2023-11-21 but there's no workers-types date that corresponds with that... so I guess I'll just use the latest available.

[dario-piotrowicz]

@Cherry I've created a separate issue for the workers-types problem, that we'll look into addressing soon 🙂

Please have a look and let me know there if you think that will help 🙏

My compat date is 2023-11-21 but there's no workers-types date that corresponds with that... so I guess I'll just use the latest available.

Yes, my understanding is that that's how things currently work, I agree that it is quite confusing 😓, the team is aware of it and hopefully will look into improving the situation at some point soon-ish.

[geelen]

Not sure if this is also related, but I just tried making a new hello world TS project with C3 and got no typescript installed at all:

❯ npm create cloudflare@latest

using create-cloudflare version 2.8.2

╭ Create an application with Cloudflare Step 1 of 3
│
├ In which directory do you want to create your application?
│ dir ./worker-b
│
├ What type of application do you want to create?
│ type "Hello World" Worker
│
├ Do you want to use TypeScript?
│ yes typescript
│
├ Copying files from "hello-world" template
│
├ Retrieving current workerd compatibility date
│ compatibility date 2023-12-06
│
├ Do you want to use git for version control?
│ yes git
│
╰ Application created

╭ Installing dependencies Step 2 of 3
│
├ Installing dependencies
│ installed via `npm install`
│
├ Committing new files
│ git commit
│
╰ Dependencies Installed

╭ Deploy with Cloudflare Step 3 of 3
│
├ Do you want to deploy your application?
│ no deploy via `npm run deploy`
│
├  APPLICATION CREATED  Deploy your application with npm run deploy
│
│ N a
│ c d
│ Run the development server npm run start
│ Deploy your application npm run deploy
│ Read the documentation https://developers.cloudflare.com/workers
│ Stuck? Join us at https://discord.gg/cloudflaredev
│
╰ See you again soon!

Shouldn't this be a .ts file that shows how to use Env, among other things, like it used to?

[Cherry]

I think we just hit the same bug @geelen. Filed at #4599 for reference.

[Cherry]

In the meantime if folks are struggling with C3, I'd recommend cloudspark. It's much simpler and more focused on what I think most people want when initialising a worker.

npx cloudspark init -y for a great TypeScript starter and no prompts. Or just npx cloudspark init for a few more interactive prompts.

[jculvey]

Cleaning up the backlog, I think the issues in the original bug report have been resolved. If not, please feel free to file a follow up issue.