081b2402cf
* esbuild respects `vite.build.minify` option * Docs update --------- Co-authored-by: AirBorne04 <> Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> |
||
---|---|---|
.. | ||
src | ||
test | ||
CHANGELOG.md | ||
package.json | ||
README.md | ||
runtime.d.ts | ||
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"
Cloudflare Pages has 2 different modes for deploying functions, advanced
mode which picks up the _worker.js
in dist
, or a directory mode where pages will compile the worker out of a functions folder in the project root.
For most projects the adapter default of advanced
will be sufficient; the dist
folder will contain your compiled project. Switching to directory mode allows you to use pages plugins such as Sentry or write custom code to enable logging.
In directory mode the adapter will compile the client side part of your app the same way, but moves the worker script into a functions
folder in the project root. The adapter will only ever place a [[path]].js
in that folder, allowing you to add additional plugins and pages middleware which can be checked into version control. Cloudflare documentation contains more information about writing custom functions.
// directory mode
export default defineConfig({
adapter: cloudflare({ mode: "directory" }),
});
Enabling Preview
In order for preview to work you must install wrangler
$ pnpm install wrangler --save-dev
It's then possible to update the preview script in your package.json
to "preview": "wrangler pages dev ./dist"
. This will allow you to run your entire application locally with Wrangler, which supports secrets, environment variables, KV namespaces, Durable Objects and all other supported Cloudflare bindings.
Access to the Cloudflare runtime
You can access all the Cloudflare bindings and environment variables from Astro components and API routes through the adapter API.
import { getRuntime } from "@astrojs/cloudflare/runtime";
getRuntime(Astro.request);
Depending on your adapter mode (advanced = worker, directory = pages), the runtime object will look a little different due to differences in the Cloudflare API.
Environment Variables
See Cloudflare's documentation for working with environment variables.
// pages/[id].json.js
export function get({ params }) {
// Access environment variables per request inside a function
const serverUrl = import.meta.env.SERVER_URL;
const result = await fetch(serverUrl + "/user/" + params.id);
return {
body: await result.text(),
};
}
Headers, Redirects and function invocation routes
Cloudflare has support for adding custom headers, configuring static redirects and defining which routes should invoke functions. Cloudflare looks for _headers
, _redirects
, and _routes.json
files in your build output directory to configure these features. This means they should be placed in your Astro project’s public/
directory.
Custom _routes.json
By default, @astrojs/cloudflare
will generate a _routes.json
file that lists all files from your dist/
folder and redirects from the _redirects
file in the exclude
array. 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 and, if not configured manually, cause function invocations that will count against the request limits of your Cloudflare plan.
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.
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.js
export default defineConfig({
adapter: cloudflare(),
output: 'server',
vite: {
build: {
minify: false
}
}
});
Contributing
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!