@astrojs/ cloudflare
Это содержимое пока не доступно на вашем языке.
This adapter allows Astro to deploy your hybrid
or server
rendered site to Cloudflare.
If you’re using Astro as a static site builder, you don’t need an adapter.
Learn how to deploy your Astro site in our Cloudflare Pages deployment guide.
Why Astro Cloudflare
Section titled Why Astro CloudflareCloudflare provides CDNs, web security, and other services. This adapter enhances the Astro build process to prepare your project for deployment through Cloudflare.
Installation
Section titled InstallationAstro includes an astro add
command to automate the setup of official integrations. If you prefer, you can install integrations manually instead.
Add the Cloudflare adapter to enable SSR in your Astro project with the astro add
command. This will install @astrojs/cloudflare
and make the appropriate changes to your astro.config.mjs
file in one step.
Manual Install
Section titled Manual InstallFirst, add the @astrojs/cloudflare
adapter to your project’s dependencies using your preferred package manager.
Then, add the adapter and your desired on-demand rendering mode to your astro.config.mjs
file:
Options
Section titled OptionsType: '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.
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.
This adapter doesn’t support the edgeMiddleware
option.
routes.strategy
Section titled routes.strategyType: '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
: -
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
:
routes.include
Section titled routes.includeType: 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
Section titled routes.excludeType: 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.
imageService
Section titled imageServiceType: 'passthrough' | 'cloudflare' | 'compile'
Default: 'passthrough'
Determines which image service is used by the adapter. The adapter will default to passthrough
mode when an incompatible image service is configured. Otherwise, it will use the globally configured image service:
cloudflare
: Uses the Cloudflare Image Resizing service.passthrough
: Uses the existingnoop
service.compile
: Uses Astro’s default service (sharp), but only on pre-rendered routes at build time. During SSR for pages rendered on-demand, allastro:assets
features are disabled.
wasmModuleImports
Section titled wasmModuleImportsType: true | false
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 about using Wasm modules.
runtime
Section titled runtimeType:
(CF_BINDING type reference)
Default: { mode: 'off', persistTo: '' }
Determines whether and how the Cloudflare Runtime is added to astro dev
.
Read more about the Cloudflare Runtime.
The type
property defines where your Astro project is deployed to:
pages
: Deployed to Cloudflare Pagesworkers
: Deployed to Cloudflare Workers
The mode
property defines what you want the runtime to support in astro dev
:
off
: no access to the runtime usingastro dev
. You can choose 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 aseval
, bindings with no local support choose Preview with Wrangler
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
Section titled Cloudflare runtimeThe Cloudflare runtime gives you access to environment variables and Cloudflare bindings. You can find more information in Cloudflare’s Workers and Pages docs. Depending on your deployment type (pages
or workers
), you need to configure the bindings differently.
Currently supported bindings:
- Environment Variables
- Cloudflare Workers KV
- Cloudflare D1
- Cloudflare R2
- Cloudflare Durable Objects
Config
Section titled ConfigCloudflare Pages
Section titled Cloudflare PagesCloudflare Pages does not support a configuration file.
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.
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:
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 for further details.
Cloudflare Workers
Section titled Cloudflare WorkersTo 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.
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:
Usage
Section titled UsageYou can access the runtime from Astro components through Astro.locals
inside any .astro
file.
You can access the runtime from API endpoints through context.locals
:
Typing
Section titled TypingIf you have configured mode: advanced
, you can type the runtime
object using AdvancedRuntime
:
If you have configured mode: directory
, you can type the runtime
object using DirectoryRuntime
:
Platform
Section titled PlatformHeaders
Section titled HeadersYou 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
Section titled RedirectsYou 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
Section titled RoutesYou 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
Section titled Custom _routes.jsonBy 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
Section titled Use Wasm modulesThe following is an example of importing a Wasm module that then responds to requests by adding the request’s number parameters together.
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
Section titled Node.js compatibilityAstro’s Cloudflare adapter allows you to use any Node.js runtime API supported by Cloudflare:
- assert
- AsyncLocalStorage
- Buffer
- Crypto
- 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.
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.
Cloudflare module support
Section titled Cloudflare module supportAll Cloudflare namespaced packages (e.g. cloudflare:sockets
) are allowlisted for use. Note that the package cloudflare:sockets
does not work locally without using Wrangler dev mode.
Preview with Wrangler
Section titled Preview with WranglerTo use wrangler
to run your application locally, update the preview script:
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
Section titled Meaningful error messagesCurrently, 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
.