Skip to content

Astro

Astro is a modern static site builder focused on shipping minimal JavaScript to the browser. Choose this component when you are delivering content-heavy marketing sites, blogs, or documentation that benefit from fast page loads. Diploi handles the SSR build pipeline and pushes assets where they need to run.

Paste this entry into the components list in diploi.yaml to add Astro to your project.

components:
- name: Astro
identifier: astro
package: https://github.com/diploi/component-astro#v7.3.5

Launch a trial, no account needed https://diploi.com/component/astro

Uses the official node Docker image.

Has the @astrojs/node adapter preconfigured in standalone mode. The project uses output: 'server', so pages are rendered on demand, unless a page opts into prerendering with export const prerender = true.

  1. In the Dashboard, click Create Project +

  2. Under Pick Components, choose Astro

    You can add other frameworks from this page if you want to build a monorepo application, eg, Astro for the frontend and Hono for the backend.

  3. In Pick Add-ons, select any databases or extra tools you need.

  4. Choose Create Repository so Diploi generates a new GitHub repo for your project.

  5. Click Launch Stack

Prefer the full guide? Check https://diploi.com/blog/hosting_astro_apps

Supports Bun, Yarn, npm, and pnpm. The package manager is auto-detected from your lockfile (bun.lock, yarn.lock, package-lock.json, or pnpm-lock.yaml). The install and build steps always use the detected package manager.

When the component is first initialized, dependencies are installed using the detected package manager. The development server is then started with:

Terminal window
npm run dev -- --host

This can be changed with the containerCommands.developmentStart field in diploi.yaml.

Builds a production-ready image. Image runs npm install & npm run build when being created, using the detected package manager. astro build writes the server to dist/server/ and the files it serves to dist/client/.

Once the image runs, npm start is called, which starts the standalone server:

Terminal window
node ./dist/server/entry.mjs

This can be changed with the containerCommands.productionStart field in diploi.yaml.

Astro reads environment variables at two different times:

  1. When the app is built. import.meta.env values, and astro:env variables with access: "public", are replaced during the build step. Only variables with the PUBLIC_ prefix, or context: "client" in astro:env, reach code that runs in the browser, and everything they contain is visible there.
  2. When the server runs. Server code, such as pages, endpoints and middleware, can read process.env and astro:env variables with access: "secret" while the server runs. Use these for secrets.

We provide two ways to manage the values that are replaced during the build step in production builds:

  1. For values that are not deployment-dependent, define them in diploi.yaml using the static import syntax. The values are exposed to the Dockerfile as ARG variables.
  2. For values that depend on a specific deployment (such as variables imported from other components in diploi.yaml, or configured in the Environment tab), enable the runtime build option.

To use a variable from another component in your code, import it in diploi.yaml. For example, to call a backend with the api identifier from server code:

- name: Astro
identifier: astro
package: https://github.com/diploi/component-astro#v7.3.5
env:
include:
- api.APP_INTERNAL_ENDPOINT:API_URL

Server code can use the <HOST>_INTERNAL_ENDPOINT address of a component, which stays inside the deployment. Code that runs in the browser needs the public <HOST>_ENDPOINT address, imported under a name with the PUBLIC_ prefix.

When runtime build is enabled (which it is by default), npm run build is executed again when the container starts. This ensures that environment variables from the running deployment are correctly applied, and that any data loaded from other components by prerendered pages can use the internal network.

If your code only reads deployment-dependent values while the server runs, you can disable runtime build by setting __VITE_RUNTIME_BUILD to false in diploi.yaml:

- name: Astro
identifier: astro
package: https://github.com/diploi/component-astro#v7.3.5
env:
include:
- name: __VITE_RUNTIME_BUILD
value: false

The component serves on port 4321 in both development and production. If you change it, update all of these so they stay in sync:

  • hosts[].port in diploi.yaml
  • EXPOSE and ENV PORT in Dockerfile and Dockerfile.dev. The production server reads PORT
  • server.port in astro.config.mjs, which the development server uses. It is not set, because 4321 is the Astro default