@astrojs/cloudflare 7.7.1 → 8.0.0

package/README.md

@@ -195,24 +195,46 @@ export default defineConfig({
 
 ### `runtime`
 
-`runtime: { mode: "off" | "local", persistTo: string }`
+See Cloudflare's repository for more type information about [CF_BINDING](https://github.com/cloudflare/workers-sdk/blob/eaa16db25103d26ef31499634a31b86caccdf7aa/packages/wrangler/src/api/startDevWorker/types.ts#L190-L219)
+
+`runtime: { mode: 'off' } | { mode: 'local'; type: 'pages'; persistTo?: string; bindings?: Record<string, CF_BINDING> } | { mode: 'local'; type: 'workers'; persistTo?: string; };`
 
 default `{ mode: 'off', persistTo: '' }`
 
 Determines whether and how the Cloudflare Runtime is added to `astro dev`.
+Read more about [the Cloudflare Runtime](#cloudflare-runtime).
+
+The `type` property defines where your Astro project is deployed to:
+
+- `pages`: Deployed to [Cloudflare Pages](https://pages.cloudflare.com/)
+- `workers`: Deployed to [Cloudflare Workers](https://workers.cloudflare.com/)
+
+The `mode` property defines what you want the runtime to support in `astro dev`:
+
+- `off`: no access to the runtime using `astro dev`. You can choose [Preview with Wrangler](#preview-with-wrangler) when you need access to the runtime, to simulate the production environment locally.
+- `local`: uses a local runtime powered by miniflare and workerd, which supports Cloudflare's Bindings. Only if you want to use unsupported features, such as `eval`, bindings with no local support choose [Preview with Wrangler](#preview-with-wrangler)
 
-The Cloudflare Runtime includes [Cloudflare bindings](https://developers.cloudflare.com/pages/platform/functions/bindings), [environment variables](https://developers.cloudflare.com/pages/platform/functions/bindings/#environment-variables), and the [cf object](https://developers.cloudflare.com/workers/runtime-apis/request/#incomingrequestcfproperties). Read more about [accessing the Cloudflare Runtime](#cloudflare-runtime).
+In `mode: local`, you have access to the `persistTo` property which defines where the local bindings state is saved. This avoids fresh bindings on every restart of the dev server. This value is a directory relative to your `astro dev` execution path. By default it is set to `.wrangler/state/v3` to allow usage of `wrangler` cli commands (e.g. for migrations). Add this path to your `.gitignore`.
+
+## Cloudflare runtime
+
+The Cloudflare runtime gives you access to environment variables and Cloudflare bindings. You can find more information in Cloudflare's [Workers](https://developers.cloudflare.com/workers/configuration/bindings/) and [Pages](https://developers.cloudflare.com/pages/platform/functions/bindings/) docs. Depending on your deployment type (`pages` or `workers`), you need to configure the bindings differently.
+
+Currently supported bindings:
 
-The `mode` property defines how the runtime is added to `astro dev`:
+- Environment Variables
+- [Cloudflare Workers KV](https://developers.cloudflare.com/kv/)
+- [Cloudflare D1](https://developers.cloudflare.com/d1/)
+- [Cloudflare R2](https://developers.cloudflare.com/r2/)
+- [Cloudflare Durable Objects](https://developers.cloudflare.com/durable-objects/)
 
-- `local`: uses bindings mocking and locally static placeholders
-- `off`: no access to the Cloudflare runtime using `astro dev`. You can alternatively use [Preview with Wrangler](#preview-with-wrangler)
+### Config
 
-The `persistTo` property defines where the local runtime is persisted to when using `mode: local`. This value is a directory relative to your `astro dev` execution path.
+#### Cloudflare Pages
 
-The default value is set to `.wrangler/state/v3` to match the default path Wrangler uses. This means both tools are able to access and use the local state.
+Cloudflare Pages does not support a configuration file.
 
-Whichever directory is set in `persistTo`, `.wrangler` or your custom value, must be added to `.gitignore`.
+To deploy your pages project to production, you need to configure the bindings using Cloudflare's Dashboard. To be able to access bindings locally, you need to configure them using the adpater's `runtime` option.
 
 ```diff lang="js"
 // astro.config.mjs
@@ -222,21 +244,103 @@ import cloudflare from '@astrojs/cloudflare';
 export default defineConfig({
   output: 'server',
   adapter: cloudflare({
-+   runtime: { mode: 'local' },
++   runtime: {
++     mode: 'local',
++     type: 'pages',
++     bindings: {
+        // example of a var binding (environment variable)
++       "URL": {
++         type: "var",
++         value: "https://example.com",
++       },
+        // example of a KV binding
++       "KV": {
++         type: "kv",
++       },
+        // example of a D1 binding
++       "D1": {
++         type: "d1",
++       },
+        // example of a R2 binding
++       "R2": {
++         type: "r2",
++       },
+        // example of a Durable Object binding
++       "DO": {
++         type: "durable-object",
++         className: "DO",
++       },
++     },
++   },
   }),
 });
 ```
 
-## Cloudflare runtime
+If you also need to define `secrets` in addition to enviroment variables, you need to add a `.dev.vars` file to the root of the Astro project:
 
-Gives you access to [environment variables](https://developers.cloudflare.com/pages/platform/functions/bindings/#environment-variables), and [Cloudflare bindings](https://developers.cloudflare.com/pages/platform/functions/bindings).
+```
+# .dev.vars
+DB_PASSWORD=myPassword
+```
 
-Currently supported bindings:
+If you want to use `wrangler` for cli commands, e.g. D1 migrations, you also need to add a `wrangler.toml` to the root of the Astro project with the correct content. Consult [Cloudflare's documentation](https://developers.cloudflare.com/) for further details.
 
-- [Cloudflare D1](https://developers.cloudflare.com/d1/)
-- [Cloudflare R2](https://developers.cloudflare.com/r2/)
-- [Cloudflare Workers KV](https://developers.cloudflare.com/kv/)
-- [Cloudflare Durable Objects](https://developers.cloudflare.com/durable-objects/)
+```toml
+# wrangler.toml
+name = "example"
+compatibility_date = "2023-06-14"
+
+# example for D1 Binding
+[[d1_databases]]
+binding = "D1"
+database_name = "D1"
+database_id = "D1"
+preview_database_id = "D1"
+```
+
+#### Cloudflare Workers
+
+To deploy your workers project to production, you need to configure the bindings using a `wrangler.toml` config file in the root directory of your Astro project. To be able to access bindings locally, the `@astrojs/cloudflare` adapter will also read the `wrangler.toml` file.
+
+```toml
+# wrangler.toml
+name = "example"
+
+# example of a KV Binding
+kv_namespaces = [
+    { binding = "KV", id = "KV", preview_id = "KV" },
+]
+
+# example of a var binding (environment variables)
+[vars]
+URL = "example.com"
+
+# example of a D1 Binding
+[[d1_databases]]
+binding = "D1"
+database_name = "D1"
+database_id = "D1"
+preview_database_id = "D1"
+
+# example of a R2 Binding
+[[r2_buckets]]
+binding = 'R2'
+bucket_name = 'R2'
+
+# example of a Durable Object Binding
+[[durable_objects.bindings]]
+name = "DO"
+class_name = "DO"
+```
+
+If you also need to define `secrets` in addition to enviroment variables, you need to add a `.dev.vars` file to the root of the Astro project:
+
+```
+# .dev.vars
+DB_PASSWORD=myPassword
+```
+
+### Usage
 
 You can access the runtime from Astro components through `Astro.locals` inside any `.astro` file.
 

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import type { AstroIntegration } from 'astro';
+import type { RUNTIME } from './utils/local-runtime.js';
 export type { AdvancedRuntime } from './entrypoints/server.advanced.js';
 export type { DirectoryRuntime } from './entrypoints/server.directory.js';
-type Options = {
+export type Options = {
     mode?: 'directory' | 'advanced';
     functionPerRoute?: boolean;
     imageService?: 'passthrough' | 'cloudflare';
@@ -19,18 +20,34 @@ type Options = {
         exclude?: string[];
     };
     /**
-     * Going forward only the object API should be used. The modes work as known before:
-     * 'off': current behaviour (wrangler is needed)
-     * 'local': use a static req.cf object, and env vars defined in wrangler.toml & .dev.vars (astro dev is enough)
-     * 'remote': use a dynamic real-live req.cf object, and env vars defined in wrangler.toml & .dev.vars (astro dev is enough)
+     * { mode: 'off' }: current behaviour (wrangler is needed)
+     * { mode: 'local', ... }: adds cf request object, locals bindings, env vars/secrets which are defined by the user to `astro.dev` with `Astro.locals.runtime` / `context.locals.runtime`
      */
-    runtime?: 'off' | 'local' | 'remote' | {
+    runtime?: {
         mode: 'off';
     } | {
-        mode: 'remote';
+        mode: Extract<RUNTIME, {
+            type: 'pages';
+        }>['mode'];
+        type: Extract<RUNTIME, {
+            type: 'pages';
+        }>['type'];
+        persistTo?: Extract<RUNTIME, {
+            type: 'pages';
+        }>['persistTo'];
+        bindings?: Extract<RUNTIME, {
+            type: 'pages';
+        }>['bindings'];
     } | {
-        mode: 'local';
-        persistTo?: string;
+        mode: Extract<RUNTIME, {
+            type: 'workers';
+        }>['mode'];
+        type: Extract<RUNTIME, {
+            type: 'workers';
+        }>['type'];
+        persistTo?: Extract<RUNTIME, {
+            type: 'workers';
+        }>['persistTo'];
     };
     wasmModuleImports?: boolean;
 };

package/dist/index.js

@@ -1,50 +1,27 @@
-import { createRedirectsFromAstroRoutes } from '@astrojs/underscore-redirects';
-import { AstroError } from 'astro/errors';
-import esbuild from 'esbuild';
-import { Miniflare } from 'miniflare';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import { dirname, relative, sep } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createRedirectsFromAstroRoutes } from '@astrojs/underscore-redirects';
+import { AstroError } from 'astro/errors';
+import esbuild from 'esbuild';
 import glob from 'tiny-glob';
 import { getAdapter } from './getAdapter.js';
 import { deduplicatePatterns } from './utils/deduplicatePatterns.js';
-import { getCFObject } from './utils/getCFObject.js';
 import { prepareImageConfig } from './utils/image-config.js';
-import { getD1Bindings, getDOBindings, getEnvVars, getKVBindings, getR2Bindings, } from './utils/parser.js';
+import { getLocalRuntime, getRuntimeConfig } from './utils/local-runtime.js';
 import { prependForwardSlash } from './utils/prependForwardSlash.js';
 import { rewriteWasmImportPath } from './utils/rewriteWasmImportPath.js';
 import { wasmModuleLoader } from './utils/wasm-module-loader.js';
-const RUNTIME_WARNING = `You are using a deprecated string format for the \`runtime\` API. Please update to the current format for better support. 
-
-Example:
-Old Format: 'local'
-Current Format: { mode: 'local', persistTo: '.wrangler/state/v3' }
-
-Please refer to our runtime documentation for more details on the format. https://docs.astro.build/en/guides/integrations-guide/cloudflare/#runtime`;
 export default function createIntegration(args) {
     let _config;
     let _buildConfig;
-    let _mf;
+    let _localRuntime;
     let _entryPoints = new Map();
     const SERVER_BUILD_FOLDER = '/$server_build/';
     const isModeDirectory = args?.mode === 'directory';
     const functionPerRoute = args?.functionPerRoute ?? false;
-    let runtimeMode = { mode: 'off' };
-    if (args?.runtime === 'remote') {
-        runtimeMode = { mode: 'remote' };
-    }
-    else if (args?.runtime === 'local') {
-        runtimeMode = { mode: 'local', persistTo: '.wrangler/state/v3' };
-    }
-    else if (typeof args?.runtime === 'object' &&
-        args?.runtime.mode === 'local' &&
-        args.runtime.persistTo === undefined) {
-        runtimeMode = { mode: 'local', persistTo: '.wrangler/state/v3' };
-    }
-    else if (args?.runtime) {
-        runtimeMode = args?.runtime;
-    }
+    const runtimeMode = getRuntimeConfig(args?.runtime);
     return {
         name: '@astrojs/cloudflare',
         hooks: {
@@ -68,7 +45,7 @@ export default function createIntegration(args) {
                     image: prepareImageConfig(args?.imageService ?? 'DEFAULT', config.image, command, logger),
                 });
             },
-            'astro:config:done': ({ setAdapter, config, logger }) => {
+            'astro:config:done': ({ setAdapter, config }) => {
                 setAdapter(getAdapter({ isModeDirectory, functionPerRoute }));
                 _config = config;
                 _buildConfig = config.build;
@@ -78,97 +55,38 @@ export default function createIntegration(args) {
                 if (_config.base === SERVER_BUILD_FOLDER) {
                     throw new AstroError('[@astrojs/cloudflare] `base: "${SERVER_BUILD_FOLDER}"` is not allowed. Please change your `base` config to something else.');
                 }
-                if (typeof args?.runtime === 'string') {
-                    logger.warn(RUNTIME_WARNING);
-                }
             },
-            'astro:server:setup': ({ server }) => {
+            'astro:server:setup': ({ server, logger }) => {
                 if (runtimeMode.mode === 'local') {
-                    const typedRuntimeMode = runtimeMode;
                     server.middlewares.use(async function middleware(req, res, next) {
-                        try {
-                            const cf = await getCFObject(typedRuntimeMode.mode);
-                            const vars = await getEnvVars();
-                            const D1Bindings = await getD1Bindings();
-                            const R2Bindings = await getR2Bindings();
-                            const KVBindings = await getKVBindings();
-                            const DOBindings = await getDOBindings();
-                            let bindingsEnv = new Object({});
-                            // fix for the error "kj/filesystem-disk-unix.c++:1709: warning: PWD environment variable doesn't match current directory."
-                            // note: This mismatch might be primarily due to the test runner.
-                            const originalPWD = process.env.PWD;
-                            process.env.PWD = process.cwd();
-                            _mf = new Miniflare({
-                                modules: true,
-                                script: '',
-                                cache: true,
-                                cachePersist: `${typedRuntimeMode.persistTo}/cache`,
-                                cacheWarnUsage: true,
-                                d1Databases: D1Bindings,
-                                d1Persist: `${typedRuntimeMode.persistTo}/d1`,
-                                r2Buckets: R2Bindings,
-                                r2Persist: `${typedRuntimeMode.persistTo}/r2`,
-                                kvNamespaces: KVBindings,
-                                kvPersist: `${typedRuntimeMode.persistTo}/kv`,
-                                durableObjects: DOBindings,
-                                durableObjectsPersist: `${typedRuntimeMode.persistTo}/do`,
-                            });
-                            await _mf.ready;
-                            for (const D1Binding of D1Bindings) {
-                                const db = await _mf.getD1Database(D1Binding);
-                                Reflect.set(bindingsEnv, D1Binding, db);
-                            }
-                            for (const R2Binding of R2Bindings) {
-                                const bucket = await _mf.getR2Bucket(R2Binding);
-                                Reflect.set(bindingsEnv, R2Binding, bucket);
-                            }
-                            for (const KVBinding of KVBindings) {
-                                const namespace = await _mf.getKVNamespace(KVBinding);
-                                Reflect.set(bindingsEnv, KVBinding, namespace);
-                            }
-                            for (const key in DOBindings) {
-                                if (Object.prototype.hasOwnProperty.call(DOBindings, key)) {
-                                    const DO = await _mf.getDurableObjectNamespace(key);
-                                    Reflect.set(bindingsEnv, key, DO);
-                                }
-                            }
-                            const mfCache = await _mf.getCaches();
-                            process.env.PWD = originalPWD;
-                            const clientLocalsSymbol = Symbol.for('astro.locals');
-                            Reflect.set(req, clientLocalsSymbol, {
-                                runtime: {
-                                    env: {
-                                        // default binding for static assets will be dynamic once we support mocking of bindings
-                                        ASSETS: {},
-                                        // this is just a VAR for CF to change build behavior, on dev it should be 0
-                                        CF_PAGES: '0',
-                                        // will be fetched from git dynamically once we support mocking of bindings
-                                        CF_PAGES_BRANCH: 'TBA',
-                                        // will be fetched from git dynamically once we support mocking of bindings
-                                        CF_PAGES_COMMIT_SHA: 'TBA',
-                                        CF_PAGES_URL: `http://${req.headers.host}`,
-                                        ...bindingsEnv,
-                                        ...vars,
-                                    },
-                                    cf: cf,
-                                    waitUntil: (_promise) => {
-                                        return;
-                                    },
-                                    caches: mfCache,
+                        _localRuntime = getLocalRuntime(_config, runtimeMode, logger);
+                        const bindings = await _localRuntime.getBindings();
+                        const secrets = await _localRuntime.getSecrets();
+                        const caches = await _localRuntime.getCaches();
+                        const cf = await _localRuntime.getCF();
+                        const clientLocalsSymbol = Symbol.for('astro.locals');
+                        Reflect.set(req, clientLocalsSymbol, {
+                            runtime: {
+                                env: {
+                                    CF_PAGES_URL: `http://${req.headers.host}`,
+                                    ...bindings,
+                                    ...secrets,
                                 },
-                            });
-                            next();
-                        }
-                        catch {
-                            next();
-                        }
+                                cf: cf,
+                                caches: caches,
+                                waitUntil: (_promise) => {
+                                    return;
+                                },
+                            },
+                        });
+                        next();
                     });
                 }
             },
             'astro:server:done': async ({ logger }) => {
-                if (_mf) {
-                    logger.info('Cleaning up the Miniflare instance, and shutting down the workerd server.');
-                    await _mf.dispose();
+                if (_localRuntime) {
+                    logger.info('Cleaning up the local Cloudflare runtime.');
+                    await _localRuntime.dispose();
                 }
             },
             'astro:build:setup': ({ vite, target }) => {
@@ -209,8 +127,7 @@ export default function createIntegration(args) {
                 if (isModeDirectory) {
                     await fs.promises.mkdir(functionsUrl, { recursive: true });
                 }
-                // TODO: remove _buildConfig.split in Astro 4.0
-                if (isModeDirectory && (_buildConfig.split || functionPerRoute)) {
+                if (isModeDirectory && functionPerRoute) {
                     const entryPointsURL = [..._entryPoints.values()];
                     const entryPaths = entryPointsURL.map((entry) => fileURLToPath(entry));
                     const outputUrl = new URL('$astro', _buildConfig.server);