Astro
Astro is a modern open-source Web framework with extensive influence in the Web development community and a popular choice for building content-driven websites and applications.
Note:
Note: Currently Pages supports Astro version 4+. The earliest version is 4. Astro 5 is recommended.
When deploying and running an Astro project, the runtime environment of the Pages platform is Node.js 22+. We recommend using a more recent Node.js version.
Core Features
Astro provides the following core features:
Islands Architecture: Astro implements islands architecture design, treating interactive components on the page as independent "islands" that hydrate on the client side only when needed, keeping the rest static.
Server-Side Rendering (SSR): Astro's server-side rendering can render dynamic data without requiring client-side JavaScript, while not slowing down pages that don't need the feature.
Static Site Generation (SSG): Supports pre-rendering webpages and generates static HTML during build.
Multi-Framework Support: When using Astro, you can still use other frameworks (Vue, React, Svelte). It supports mixed use of multiple framework components in the project.
Content Collection: Use type-safe front matter to organize Markdown and MDX content.
API Routing: Server API endpoints for dynamic data processing.
Quick Start
Deploy an Astro project on EdgeOne Pages quickly in the following ways:
Import an Astro project via Git repository
Select an Astro template from the Pages template library to deploy
To learn about Astro's performance on Pages deployment, you can click the Astro example template for Pages below:
Astro Feature Support on Pages
The following table lists the key characteristics of Astro currently supported by Pages as follows:
Astro Features | Support Status |
Archipelago Architecture Rendering | ✅ |
Server-side rendering (SSR) | ✅ |
Static Site Generation (SSG) | ✅ |
Multi-framework support | ✅ |
Content collection (MD, MDX) | ✅ |
API routing | ✅ |
Route Actions | ✅ |
Middleware | Support Astro built-in middleware |
Image component | Not supported. |
Platform ISR | Not supported. |
Unsupported Astro features are currently in planning on the Pages platform. It is advisable to follow version updates of the @edgeone/astro adapter for timely acquisition of the latest features and improvements.
Deploying an Astro Project on Pages
1. Installing the Astro Adapter for Pages
The Astro adapter for pages, named @edgeone/Astro, is an adapter that automatically adapts the build results of an Astro application to the pages platform, similar to @astrojs/vercel. It can work in conjunction with the pages scaffolding tool to package and deploy a local Astro project to the pages platform. Below is the command to install the adapter:
npm install @edgeone/astro
2. Configuring Astro.Config.Mjs
According to the API of Astro's configuration file, users need to configure the Pages platform adapter in the project's
astro.config.mjs. Example configuration:import { defineConfig } from "astro/config";import edgeoneAdapter from "@edgeone/astro";export default defineConfig({adapter: edgeoneAdapter(),});
3. Deploying a Project
Connecting Git for Deployment
After seamless integration with the adapter, you can submit the project to platforms like GitHub or GitLab, and use our Git Connection Deployment.
CLI Deployment
You can also install the Pages scaffolding tool. For detailed installation and usage, refer to EdgeOne CLI. Once configured, use the `edgeone pages deploy` command to deploy the project. During deployment, the CLI will first auto-build the project, then upload and publish the build artifacts.
Note:
EdgeOne CLI version requirement ≥ 1.2.0. Please first check the version before deployment to avoid deployment failure.
Configuring the Astro Pages Adapter
The adapter supports the following configuration options:
outDir (optional): Specifies the build output directory, defaults to .edgeone. Example: outDir: ".edgeone".includeFiles (optional): A mandatory inclusion file list used to underwrite specific files are packaged into server-side rendering code. Supports glob pattern matching. Example: includeFiles: ["src/locales/**", "public/config.json"].excludeFiles (optional): A file list for exclusion, used to exclude files that do not need to be packaged into server-side rendering code. Mainly used to exclude specific files in node_modules. Supports glob pattern matching. Example: excludeFiles: ["node_modules/.cache/**"].
Configuration Example:
import { defineConfig } from "astro/config";import edgeoneAdapter from "@edgeone/astro";export default defineConfig({output: "server",adapter: edgeoneAdapter({outDir: ".edgeone",includeFiles: ["src/locales/**"],excludeFiles: ["node_modules/.cache/**"],}),});
Static Site Generation (SSG)
You can use Astro to generate completely static sites. Configured as static export mode, modify astro.config.mjs as in the following example:
export default defineConfig({output: 'static' // Enable static export});
Please note: In Astro's SSG (Static Site Generation) mode, all webpages are pre-rendered as static HTML during build time, with no server runtime environment. Therefore, server-side functionality cannot be used, including API routes (src/pages/api/*), middleware (src/middleware.ts), and any other features that require server-side execution.
Server-Side Rendering (SSR)
The Pages adapter also supports Astro's server-side rendering feature. Set the following configuration in
astro.config.mjs to enable SSR mode:export default defineConfig({output: 'server' // Enable server-side rendering});
SSR mode allows you to dynamically generate HTML content on the server side, offering better SEO support, faster initial page load speed, and real-time rendering capability for dynamic content.
In addition to pure SSR mode, Pages also support Astro's hybrid mode. In hybrid mode, you can flexibly control the rendering method of each page.
Static page: Set
export const prerender = true on the page. This page will be pre-rendered as a static HTML file during build.Dynamic page: Pages with
prerender not set to true will use SSR dynamic rendering.