# Deploy an Astro Site on FlyWP Through Git

> Deploy Astro on FlyWP with static output or the standalone Node adapter and Server runtime.

Source: https://flywp.com/docs/site/nodejs-sites/astro/

Deploy an Astro repository using FlyWP's JavaScript site wizard. Use Static runtime for generated pages, or configure Astro's Node adapter and use Server runtime for request-time rendering.

For Git provider access, DNS, and release management, see the [shared Git deployment guide](https://flywp.com/docs/site/nodejs-sites/).

## Before you begin

You need an active FlyWP-managed server, a connected Git provider, and an Astro app with `package.json` at the repository root. The current wizard excludes monorepos. Commit source, `astro.config` and other necessary configuration, dependencies, and the lockfile.

Choose a Node major satisfying your installed Astro version and integrations. If they support Node.js 22, declare `"engines": { "node": "22.x" }` to make the intended major explicit. Check the framework's minimum minor version too; a supported major alone may not be sufficient.

## Choose Static or Server

Astro normally builds a static site. Use Static when the generated pages and assets are enough for your site. Use Server when the application needs request-time pages, server endpoints, or server-side session behavior. Framework configuration and FlyWP runtime must agree. [Astro deployment guide](https://docs.astro.build/en/guides/deploy/).

Interactive React, Vue, or other hydrated components can still exist on a static site. Their browser-side code does not by itself require an Astro server. Backend operations still need a backend service.

## Option A: Prepare a Static site

For a standard project, merge these settings into `astro.config.mjs`:

```js
import { defineConfig } from 'astro/config';

export default defineConfig({
  site: 'https://example.com',
  output: 'static',
});
```

Replace `example.com` with your public hostname when known, and retain existing integrations and configuration. The `site` option identifies the final URL for features that need it. Astro's default build output directory is `dist`; adjust the hosting path if your project changes `outDir`. [Astro configuration reference](https://docs.astro.build/en/reference/configuration-reference/).

Ensure `package.json` has a build script:

```json
{
  "scripts": {
    "build": "astro build"
  },
  "engines": {
    "node": "22.x"
  }
}
```

Test in your development checkout:

```bash
npm ci
npm run build
```

Preview `dist` with a local static server. Check a nested page, assets, and any browser-side API calls. Verify that every expected route was generated before deploying.

## Option B: Prepare a Server application

Install Astro's Node adapter in your local project and commit the updated manifest and lockfile:

```bash
npx astro add node
```

Review the resulting configuration. A standalone server setup uses:

```js
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'server',
  adapter: node({ mode: 'standalone' }),
});
```

Merge this into your existing configuration. With the default output directory, the standalone entrypoint is `dist/server/entry.mjs`; the adapter also produces client assets. Do not configure middleware mode with the standalone start command. [Astro Node adapter](https://docs.astro.build/en/guides/integrations-guide/node/).

Build and test locally:

```bash
npm ci
npm run build
HOST=0.0.0.0 PORT=4321 node dist/server/entry.mjs
```

Port 4321 is a local test example. Open the reported address, verify request-time functionality, and stop the process. Production networking must match FlyWP's upstream; this example does not establish its production port.

<figure>
  <a
    href="https://flywp.com/images/docs/nodejs-sites/site-type.jpg"
    target="_blank"
    rel="noopener noreferrer"
    aria-label="Open full-size screenshot: FlyWP Create Site dialog with the Node.js Next.js Nuxt Astro choice"
  >
    <img
      src="https://flywp.com/images/docs/nodejs-sites/site-type.jpg"
      alt="FlyWP Create Site dialog with the Node.js Next.js Nuxt Astro choice"
      width="1280"
      height="1063"
      loading="lazy"
    />
  </a>
  <figcaption>
    Open the JavaScript site wizard from the application selector. Select the image to view the full screen.
  </figcaption>
</figure>

## Create the site in FlyWP

1. Sign in to [FlyWP](https://app.flywp.com).
2. Open **Dashboard → New Site → Select Server → Continue → Node.js Next.js / Nuxt / Astro**.
3. On **Domain**, select **Use flywp.xyz test domain** or enter your custom **Domain Name**. Configure the available DNS/HTTPS options for a custom domain, then click **Next**.
4. On **Configure Git**, select **Astro** and enter the settings for your build mode.

| Field            | Static                          | Server                                                                       |
| ---------------- | ------------------------------- | ---------------------------------------------------------------------------- |
| Application Type | Astro                           | Astro                                                                        |
| Runtime          | Static                          | Server                                                                       |
| Package manager  | npm                             | npm                                                                          |
| Build command    | `npm run build`                 | `npm run build`                                                              |
| Start command    | Hidden; no Node process         | `node dist/server/entry.mjs`                                                 |
| Web directory    | `/dist` — observed wizard value | `/dist` — observed wizard value; confirm client asset handling on deployment |

These values were observed in the live wizard for an Astro selection. If your project uses a custom `outDir`, update both paths as necessary. A Server build's `dist` contains server and client output; verify Nginx and adapter asset handling instead of treating all output as publicly served HTML.

Choose the matching package manager. For example, use `pnpm run build` with pnpm. Dependency installation happens before the build command.

5. Select your Git provider, **Repository**, and release **Branch**.
6. Enable **Push to deploy** if pushes to that branch should trigger releases.
7. Click **Next** and complete **Installation**. In the inspected test-domain flow, **Site Title** determines the test hostname.
8. Review **Summary**, including the runtime, commands, web directory, branch, and domain. Click **Create Site** when correct.

<figure>
  <a
    href="https://flywp.com/images/docs/nodejs-sites/astro-server.jpg"
    target="_blank"
    rel="noopener noreferrer"
    aria-label="Open full-size screenshot: FlyWP Configure Git with Astro and Server selected and production build and start commands visible"
  >
    <img
      src="https://flywp.com/images/docs/nodejs-sites/astro-server.jpg"
      alt="FlyWP Configure Git with Astro and Server selected and production build and start commands visible"
      width="1280"
      height="2157"
      loading="lazy"
    />
  </a>
  <figcaption>
    Astro Server setup in the actual FlyWP app. Repository and branch remain to be selected. Select the image to view
    the full screen.
  </figcaption>
</figure>

<figure>
  <a
    href="https://flywp.com/images/docs/nodejs-sites/astro-static.jpg"
    target="_blank"
    rel="noopener noreferrer"
    aria-label="Open full-size screenshot: FlyWP Configure Git with Astro and Static selected and its build command and web directory visible"
  >
    <img
      src="https://flywp.com/images/docs/nodejs-sites/astro-static.jpg"
      alt="FlyWP Configure Git with Astro and Static selected and its build command and web directory visible"
      width="1280"
      height="2045"
      loading="lazy"
    />
  </a>
  <figcaption>
    Astro Static configuration example entered in the real wizard. These settings were not deployed. Select the image to
    view the full screen.
  </figcaption>
</figure>

## Environment variables

Astro's Vite-style variables are read through `import.meta.env`. Variables prefixed with `PUBLIC_` may be exposed to browser code; keep credentials private. Values used during static generation need to be available at build time, and a static site has no application process that can read new runtime values. [Astro environment variables](https://docs.astro.build/en/guides/environment-variables/).

For example:

```dotenv
PUBLIC_API_BASE_URL=https://api.example.com
CMS_TOKEN=<private-build-or-server-token>
```

Provide these through your site's environment configuration, not a committed credentials file. If your Server app needs runtime values, use the approach supported by your Astro version and Node adapter, such as server-side `process.env` or the appropriate `astro:env` configuration. Do not assume a build-time substitution changes when a process restarts.

The inspected FlyWP creation wizard has no environment editor. Confirm build/runtime injection on the created site, along with the application's bind address and expected proxy port.

## Verify and update

Read the deployment's build and startup logs, then open the public hostname in a signed-out browser. Test a direct nested URL, navigation, CSS, JavaScript, and images. Check any base path or public API URL against the final domain.

For Static runtime, confirm that pages exist under the configured output directory and do not depend on Astro server endpoints. For Server runtime, exercise a request-time route and check that client assets load as well as server responses.

Push subsequent updates to the configured branch and inspect the resulting release. Changing generated content or public build variables requires a new build. To recover a source change, push a revert commit and redeploy; persistent data needs separate recovery.

## Troubleshooting

| Symptom                           | Action                                                                     |
| --------------------------------- | -------------------------------------------------------------------------- |
| `astro` command not found         | Verify dependencies were installed and the manifest contains Astro         |
| Missing server entrypoint         | Check `output: 'server'`, Node adapter, standalone mode, and build success |
| 403/404 on Static homepage        | Check generated `dist/index.html` and Web directory                        |
| CSS/JS missing on Server          | Check client output, asset URLs, and adapter/proxy serving behavior        |
| Server-only route fails on Static | Use Server runtime or redesign it for build-time/external API use          |
| Old public URL or content         | Rebuild using the updated build-time values                                |
| 502                               | Check process errors and match bind address/port with FlyWP's proxy        |

## Related guides

- [Next.js, Nuxt & Astro Site Support Through Git](https://flywp.com/docs/site/nodejs-sites/)
- [Deploy a Next.js Site on FlyWP Through Git](https://flywp.com/docs/site/nodejs-sites/nextjs/)
- [Deploy a Nuxt Site on FlyWP Through Git](https://flywp.com/docs/site/nodejs-sites/nuxt/)