2d33b9362d
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> |
||
---|---|---|
.. | ||
src | ||
test | ||
.gitignore | ||
CHANGELOG.md | ||
package.json | ||
README.md | ||
tsconfig.json |
@astrojs/cloudflare
An SSR adapter for use with Cloudflare Pages Functions targets. Write your code in Astro/Javascript and deploy to Cloudflare Pages.
Install
Add the Cloudflare adapter to enable SSR in your Astro project with the following astro add
command. This will install the adapter and make the appropriate changes to your astro.config.mjs
file in one step.
# Using NPM
npx astro add cloudflare
# Using Yarn
yarn astro add cloudflare
# Using PNPM
pnpm astro add cloudflare
If you prefer to install the adapter manually instead, complete the following two steps:
- Add the Cloudflare adapter to your project's dependencies using your preferred package manager. If you’re using npm or aren’t sure, run this in the terminal:
npm install @astrojs/cloudflare
- Add the following to your
astro.config.mjs
file:
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import cloudflare from '@astrojs/cloudflare';
export default defineConfig({
+ output: 'server',
+ adapter: cloudflare(),
});
Options
mode
mode: "advanced" | "directory"
default "advanced"
This configuration option defines how your Astro project is deployed to Cloudflare Pages.
advanced
mode picks up the_worker.js
file in thedist
folderdirectory
mode picks up the files in thefunctions
folder, by default only one[[path]].js
file is generated
Switching to directory mode allows you to add additional files manually such as Cloudflare Pages Plugins, Cloudflare Pages Middleware or custom functions using Cloudflare Pages Functions Routing.
// astro.config.mjs
export default defineConfig({
adapter: cloudflare({ mode: 'directory' }),
});
To compile a separate bundle for each page, set the functionPerRoute
option in your Cloudflare adapter config. This option requires some manual maintenance of the functions
folder. Files emitted by Astro will overwrite existing files with identical names in the functions
folder, so you must choose unique file names for each file you manually add. Additionally, the adapter will never empty the functions
folder of outdated files, so you must clean up the folder manually when you remove pages.
// astro.config.mjs
import {defineConfig} from "astro/config";
import cloudflare from '@astrojs/cloudflare';
export default defineConfig({
adapter: cloudflare({
mode: 'directory',
+ functionPerRoute: true
})
})
This adapter doesn't support the edgeMiddleware
option.
routes.strategy
routes.strategy: "auto" | "include" | "exclude"
default "auto"
Determines how routes.json
will be generated if no custom _routes.json
is provided.
There are three options available:
-
"auto"
(default): Will automatically select the strategy that generates the fewest entries. This should almost always be sufficient, so choose this option unless you have a specific reason not to. -
include
: Pages and endpoints that are not pre-rendered are listed asinclude
entries, telling Cloudflare to invoke these routes as functions.exclude
entries are only used to resolve conflicts. Usually the best strategy when your website has mostly static pages and only a few dynamic pages or endpoints.Example: For
src/pages/index.astro
(static),src/pages/company.astro
(static),src/pages/users/faq.astro
(static) and/src/pages/users/[id].astro
(SSR) this will produce the following_routes.json
:{ "version": 1, "include": [ "/_image", // Astro's image endpoint "/users/*" // Dynamic route ], "exclude": [ // Static routes that needs to be exempted from the dynamic wildcard route above "/users/faq/", "/users/faq/index.html" ] }
-
exclude
: Pre-rendered pages are listed asexclude
entries (telling Cloudflare to handle these routes as static assets). Usually the best strategy when your website has mostly dynamic pages or endpoints and only a few static pages.Example: For the same pages as in the previous example this will produce the following
_routes.json
:{ "version": 1, "include": [ "/*" // Handle everything as function except the routes below ], "exclude": [ // All static assets "/", "/company/", "/index.html", "/users/faq/", "/favicon.png", "/company/index.html", "/users/faq/index.html" ] }
routes.include
routes.include: string[]
default []
If you want to use the automatic _routes.json
generation, but want to include additional routes (e.g. when having custom functions in the functions
folder), you can use the routes.include
option to add additional routes to the include
array.
routes.exclude
routes.exclude: string[]
default []
If you want to use the automatic _routes.json
generation, but want to exclude additional routes, you can use the routes.exclude
option to add additional routes to the exclude
array.
The following example automatically generates _routes.json
while including and excluding additional routes. Note that that is only necessary if you have custom functions in the functions
folder that are not handled by Astro.
// astro.config.mjs
export default defineConfig({
adapter: cloudflare({
mode: 'directory',
+ routes: {
+ strategy: 'include',
+ include: ['/users/*'], // handled by custom function: functions/users/[id].js
+ exclude: ['/users/faq'], // handled by static page: pages/users/faq.astro
+ },
}),
});
wasmModuleImports
wasmModuleImports: boolean
default: false
Whether or not to import .wasm
files directly as ES modules using the .wasm?module
import syntax.
Add wasmModuleImports: true
to astro.config.mjs
to enable this functionality in both the Cloudflare build and the Astro dev server. Read more
// astro.config.mjs
import {defineConfig} from "astro/config";
import cloudflare from '@astrojs/cloudflare';
export default defineConfig({
adapter: cloudflare({
+ wasmModuleImports: true
}),
output: 'server'
})
runtime
runtime: "off" | "local" | "remote"
default "off"
Determines whether and how the Cloudflare Runtime is added to astro dev
.
The Cloudflare Runtime includes Cloudflare bindings, environment variables, and the cf object. Read more about accessing the Cloudflare Runtime.
local
: uses bindings mocking and locally static placeholdesremote
: uses remote bindings and a live fetched cf objectoff
: no access to the Cloudflare runtime usingastro dev
. You can alternatively use Preview with Wrangler
// astro.config.mjs
import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';
export default defineConfig({
output: 'server',
adapter: cloudflare({
+ runtime: 'local',
}),
});
Cloudflare runtime
Gives you access to environment variables.
You can access the runtime from Astro components through Astro.locals
inside any .astro` file.
---
// src/pages/index.astro
const runtime = Astro.locals.runtime;
---
<pre>{JSON.stringify(runtime.env)}</pre>
You can access the runtime from API endpoints through context.locals
:
// src/pages/api/someFile.js
export function GET(context) {
const runtime = context.locals.runtime;
return new Response('Some body');
}
Typing
If you have configured mode: advanced
, you can type the runtime
object using AdvancedRuntime
:
// src/env.d.ts
/// <reference types="astro/client" />
type KVNamespace = import('@cloudflare/workers-types/experimental').KVNamespace;
type ENV = {
SERVER_URL: string;
KV_BINDING: KVNamespace;
};
type Runtime = import('@astrojs/cloudflare').AdvancedRuntime<ENV>;
declare namespace App {
interface Locals extends Runtime {
user: {
name: string;
surname: string;
};
}
}
If you have configured mode: directory
, you can type the runtime
object using DirectoryRuntime
:
// src/env.d.ts
/// <reference types="astro/client" />
type KVNamespace = import('@cloudflare/workers-types/experimental').KVNamespace;
type ENV = {
SERVER_URL: string;
KV_BINDING: KVNamespace;
};
type Runtime = import('@astrojs/cloudflare').DirectoryRuntime<ENV>;
declare namespace App {
interface Locals extends Runtime {
user: {
name: string;
surname: string;
};
}
}
Platform
Headers
You can attach custom headers to your responses by adding a _headers
file in your Astro project's public/
folder. This file will be copied to your build output directory.
Redirects
You can declare custom redirects using Cloudflare Pages. This allows you to redirect requests to a different URL. You can add a _redirects
file in your Astro project's public/
folder. This file will be copied to your build output directory.
Routes
You can define which routes are invoking functions and which are static assets, using Cloudflare routing via a _routes.json
file. This file is automatically generated by Astro.
Custom _routes.json
By default, @astrojs/cloudflare
will generate a _routes.json
file with include
and exclude
rules based on your applications's dynamic and static routes.
This will enable Cloudflare to serve files and process static redirects without a function invocation. Creating a custom _routes.json
will override this automatic optimization. See Cloudflare's documentation on creating a custom routes.json
for more details.
Use Wasm modules
The following is an example of importing a Wasm module that then responds to requests by adding the request's number parameters together.
// pages/add/[a]/[b].js
import mod from '../util/add.wasm?module';
// instantiate ahead of time to share module
const addModule: any = new WebAssembly.Instance(mod);
export async function GET(context) {
const a = Number.parseInt(context.params.a);
const b = Number.parseInt(context.params.b);
return new Response(`${addModule.exports.add(a, b)}`);
}
While this example is trivial, Wasm can be used to accelerate computationally intensive operations which do not involve significant I/O such as embedding an image processing library.
Node.js compatibility
Astro's Cloudflare adapter allows you to use any Node.js runtime API supported by Cloudflare:
- assert
- AsyncLocalStorage
- Buffer
- Diagnostics Channel
- EventEmitter
- path
- process
- Streams
- StringDecoder
- util
To use these APIs, your page or endpoint must be server-side rendered (not pre-rendered) and must use the the import {} from 'node:*'
import syntax.
// pages/api/endpoint.js
export const prerender = false;
import { Buffer } from 'node:buffer';
Additionally, you'll need to enable the Compatibility Flag in Cloudflare. The configuration for this flag may vary based on where you deploy your Astro site. For detailed guidance, please refer to the Cloudflare documentation on enabling Node.js compatibility.
Preview with Wrangler
To use wrangler
to run your application locally, update the preview script:
//package.json
"preview": "wrangler pages dev ./dist"
wrangler
gives you access to Cloudflare bindings, environment variables, and the cf object. Getting hot reloading or the astro dev server to work with Wrangler might require custom setup. See community examples.
Meaningful error messages
Currently, errors during running your application in Wrangler are not very useful, due to the minification of your code. For better debugging, you can add vite.build.minify = false
setting to your astro.config.mjs
.
// astro.config.mjs
export default defineConfig({
adapter: cloudflare(),
output: 'server',
+ vite: {
+ build: {
+ minify: false,
+ },
+ },
});
Troubleshooting
For help, check out the #support
channel on Discord. Our friendly Support Squad members are here to help!
You can also check our Astro Integration Documentation for more on integrations.
Contributing
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!