chore: flesh out cloudflare bindings docs

[Rich-Harris]

stumbled on this while working on #11730

[changeset-bot[bot]]

⚠️ No Changeset found

Latest commit: b4dfa2fd6822f33c9c7abde4dd60263a8ed1669e

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[Rich-Harris]

huh, doesn't seem to be working for me. am i doing something wrong?

[ghostdevv]

huh, doesn't seem to be working for me. am i doing something wrong?

Doesn't seem to be working for me either :thinking: @benmccann any ideas? You mentioned this to me last time

[benmccann]

I'm really not the person to ask about TypeScript intricacies. Certainly if the types were available just from installing the adapter that would be nicer than if the user had to manually set things up. I do see they're listed in the dependencies for those packages. Perhaps @dummdidumm could provide some advice on why that might not be working

[teemingc]

Additionally, the types are missing for the other properties declared by the adapter. platform.cf should be typed IncomingRequestCfProperties

I can get it working if I reference at least @cloudflare/workers-types and @sveltejs/adapter-cloudflare. We could reference the workers types in the adapter, then reference the adapter types when running svelte-kit sync, although I'm not sure if this is the way to include it.

adapter-cloudflare/ambient.d.ts

- import { Cache, CacheStorage, IncomingRequestCfProperties } from '@cloudflare/workers-types';
+ /// <reference types="@cloudflare/workers-types" />

declare global {
	namespace App {
		export interface Platform {
			context?: {
+				/**
+				 * Extends the lifetime of the fetch event. It accepts a Promise-based task which the Workers runtime will execute before the handler terminates but without blocking the response. For example, this is ideal for caching responses or handling logging.
+				 * @param promise
+				 */
				waitUntil(promise: Promise<any>): void;
			};
+			/**
+			 * The [Cache](https://developer.mozilla.org/en-US/docs/Web/API/Cache) API
+			 * allows fine grained control of reading and writing from the [Cloudflare global network](https://www.cloudflare.com/network/) cache.
+			 */
			caches?: CacheStorage & { default: Cache };
+			/**
+			 * Contains information about the [request](https://developers.cloudflare.com/workers/runtime-apis/request/#incomingrequestcfproperties)
+			 * provided by Cloudflare’s global network.
+			 */
			cf?: IncomingRequestCfProperties;
+			/**
+			 * Contains your project's [bindings](https://developers.cloudflare.com/pages/functions/bindings),
+			 * which consist of KV namespaces and other storage objects.
+			 */
+			env?: {
+				[key: string]: D1Database | DurableObjectNamespace | KVNamespace | R2Bucket;
+			};
		}
	}
}
+
+ export {}

.svelte-kit/ambient.d.ts

// this file is generated — do not edit it

/// <reference types="@sveltejs/kit" />
// maybe only include the reference if the adapter is found in package.json?
+ /// <reference types="@sveltejs/adapter-cloudflare" />

...

Now we can reference the types without importing

[benmccann]

@Rich-Harris this will need a rebase since I merged https://github.com/sveltejs/kit/pull/11732

[teemingc]

Recently, I used TypeScript nightly in VSCode and this wasn't an issue anymore. Maybe I'll need to check again if it was just a fluke or if it also works without TypeScript nightly.

[teemingc]

Alright. So apparently I was importing something from drizzle/d1 in a typescript file and they've included /// <reference types="@cloudflare/workers-types" /> in their type declaration file so the workers types became available globally. We can do the same thing but it doesn't work when we import our adapter in svelte.config.js. Since it's a JS file, the workers types are only available locally in that file.

So the minimum someone would need to do is add a reference to the adapter package in their app.d.ts and the workers types become global without having to install the workers types package again.

+ /// <reference types="@sveltejs/adapter-cloudflare" />

// See https://kit.svelte.dev/docs/types#app
// for information about these interfaces
declare global {
	namespace App {
		// interface Error {}
		// interface Locals {}
		// interface PageData {}
		// interface PageState {}
		interface Platform {
			env: {
				example: D1Database; // we get our types!
			}
		}
	}
}

export {};

But it'd be even nicer if we could get rid of this step and just have the types available by including a reference to them in the generated sveltekit ambient declaration file.

[teemingc]

Adding a note here from https://github.com/sveltejs/kit/pull/12088#issuecomment-2156091419

It was suggested to not automatically include the cloudflare types globally because they pollute the ambient types namespace.

[Rich-Harris]

preview: https://svelte-dev-git-preview-kit-11731-svelte.vercel.app/

this is an automated message