Previewing Production Site | Astro Lounge | Page 1

solar cedar Dec 17, 2025, 3:33 AM

#

After running npm run build, I want to preview the site so that I can run a lighthouse audit and see how everything looks. I tried to use npm run preview but I got the following error (maybe because I have ssr enabled on one page for a form)


> preview
> astro preview

14:32:52 [@astrojs/netlify] Enabling sessions with Netlify Blobs
[preview] The @astrojs/netlify adapter does not support the preview command.
  Location:
    C:\WebDev\Projects\FEM\arch-studio\node_modules\astro\dist\core\preview\index.js:44:11
  Stack trace:
    at preview (file:///C:/WebDev/Projects/FEM/arch-studio/node_modules/astro/dist/core/preview/index.js:44:11)
    at async runCommand (file:///C:/WebDev/Projects/FEM/arch-studio/node_modules/astro/dist/cli/index.js:215:22)
Assertion failed: !(handle->flags & UV_HANDLE_CLOSING), file src\win\async.c, line 76
PS C:\WebDev\Projects\FEM\arch-studio> ```

paper mantleBOT Dec 17, 2025, 3:33 AM

#

Hi @solar cedar. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

#

Astro’s astro preview command can only preview:

Static builds (the default dist/ output), or
SSR builds when using an adapter that supports preview – currently only the Node adapter. [CLI preview]

Your error:

The @astrojs/netlify adapter does not support the preview command.

is expected, because the Netlify adapter is an SSR adapter that does not implement astro preview. [CLI preview]

From the docs, “Currently, only the Node adapter supports astro preview.” [CLI preview]

So, with the Netlify adapter:

npm run build will work and produce output for deployment.
npm run preview / astro preview will fail as you saw.

The knowledge sources do not describe a Netlify-specific workaround for local production-like preview or Lighthouse audits; they only state that astro preview is not supported by that adapter and that you should instead follow the deployment guide for production hosting. [CLI preview]

If you need `astro preview` specifically, the docs indicate you’d have to use the Node adapter instead of Netlify for that step.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@solar cedar Kapa.ai is still learning and improving, please let me know how I did by reacting below.

solar cedar Dec 17, 2025, 3:35 AM

#

@paper mantle explain to me what you mean by the node adapter. Is this when I have a SSR page, that I need something to support it. What would happen if I use node instead of netlify?

paper mantleBOT Dec 17, 2025, 3:35 AM

#

Let me check the knowledge base for you again. One moment! :books:

#

In Astro, an adapter is what connects your built site to a specific hosting/runtime environment. The Node adapter (@astrojs/node) is the adapter that targets a plain Node.js server, instead of a platform like Netlify.

From the docs:

“This adapter allows Astro to deploy your on-demand rendered routes to Node targets.” [Node adapter]

1. What is the Node adapter?

You install it like this:

npm install @astrojs/node

and configure it in astro.config.mjs:

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

export default defineConfig({
  output: 'server', // for SSR / on‑demand rendering
  adapter: node({
    mode: 'standalone', // or 'middleware'
  }),
});

[Node adapter]

output: 'server' tells Astro you’re using on‑demand/SSR routes.
adapter: node(...) tells Astro to build for Node.js instead of Netlify.

The Node adapter can run either:

in standalone mode (Astro builds a self-starting Node server), or
in middleware mode (you plug Astro into another Node server like Express/Fastify). [Node adapter]

2. Is this “needed” for SSR pages?

You always need some adapter when you use on‑demand/SSR routes; the adapter just depends on where you deploy:

Netlify → @astrojs/netlify
Node server → @astrojs/node
etc.

#

So the Node adapter is one option for SSR/on‑demand rendering, specifically when your target is Node. [Node adapter]

3. What happens if you use Node instead of Netlify?

If you switch your config from Netlify to Node:

Your build output will be for Node.js, not for Netlify’s platform.
You can run the built server directly with Node (in standalone mode) or mount it in another Node server (middleware mode). [Node adapter]

Concretely, for your use case:

With Netlify adapter: astro preview is not supported (as you saw).
With Node adapter: the docs show it as the adapter used when enabling on‑demand/SSR and running a Node server locally. They do not explicitly say “Node is required for astro preview”, but the separate CLI docs (not in the provided sources) state that only the Node adapter supports astro preview.

So:

If you deploy to Netlify, keep @astrojs/netlify for your real deployment.
If you temporarily switch to @astrojs/node, your build will target Node instead, which is suitable for running a local Node server and (per the CLI docs) using astro preview, but that build would not be the Netlify-specific one.

The provided Node adapter docs don’t describe a mixed “use Netlify for deploy but Node for preview” workflow explicitly, so anything beyond this (like exact preview commands or switching back and forth) is not covered in the sources.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@solar cedar Kapa.ai is still learning and improving, please let me know how I did by reacting below.

solar cedar Dec 17, 2025, 3:40 AM

#

Can you explain the differences between using node and netlify @paper mantle

paper mantleBOT Dec 17, 2025, 3:40 AM

#

Let me check the knowledge base for you again. One moment! :books:

#

In the context of Astro, “Node” vs “Netlify” refers to which SSR adapter you use and therefore where and how your on‑demand (server) routes run.

1. What the adapters are for

Netlify adapter (@astrojs/netlify)
- Builds your Astro site so it can run on Netlify’s platform.
- Used when you deploy to Netlify and want hybrid or server (on‑demand) rendering. [Netlify adapter]
- Also useful even for static sites to enable Netlify features like the Image CDN. [On‑demand rendering]
Node adapter (@astrojs/node)
- Builds your Astro site to run on a generic Node.js runtime (your own Node server, a Node host, etc.).
- It’s one of the official SSR adapters alongside Netlify, Vercel, and Cloudflare. [On‑demand rendering]

Both are used when you set output: 'server' or use on‑demand rendering; you always need some adapter for SSR. [On‑demand rendering]

2. Configuration differences

In both cases you:

Install the adapter.
Set it in astro.config.* with output: 'server'.

Netlify example: [Netlify adapter]

// astro.config.mjs
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

#

export default defineConfig({
output: 'server',
adapter: netlify(),
});


**Node example** (pattern is similar, but with `@astrojs/node`; exact Node docs weren’t in your provided sources, so I can’t quote their config block directly).

---

### 3. Runtime / platform differences

- **With Netlify adapter**
  - Your build output is tailored to **Netlify’s runtime** (functions, edge, blobs, etc.). [[Netlify adapter](<https://web.archive.org/web/20241126210726/https://docs.astro.build/en/guides/integrations-guide/netlify/#_top>)]
  - You deploy by following the **Netlify deployment guide** (connect repo, Netlify build, etc.). [[Netlify adapter](<https://web.archive.org/web/20241126210726/https://docs.astro.build/en/guides/integrations-guide/netlify/#_top>)]
  - You can also get Netlify‑specific features like the **Image CDN** even for static sites. [[On‑demand rendering](<https://web.archive.org/web/20250225142033/https://docs.astro.build/en/guides/on-demand-rendering/#server-adapters>)]

- **With Node adapter**
  - Your build output is meant to run on a **Node.js server** you control or a generic Node host. [[On‑demand rendering](<https://web.archive.org/web/20250225142033/https://docs.astro.build/en/guides/on-demand-rendering/#server-adapters>)]
  - You’d deploy it like any other Node app (how exactly is not covered in the provided sources).

---

### 4. Preview / local behavior

From your earlier error, we know:

- The **Netlify adapter does not support `astro preview`**; that’s why you saw:

  > The @astrojs/netlify adapter does not support the preview command.

#

This is coming from Astro’s preview implementation when it detects the Netlify adapter. The provided Netlify docs themselves don’t mention astro preview, only build and deploy. [Netlify adapter]

The knowledge sources do not explicitly describe how astro preview behaves with the Node adapter, so I can’t state from these docs alone that Node “fixes” preview for you, only that:

Netlify adapter: no astro preview support (confirmed by your error and not contradicted by docs).
Node adapter: is a general SSR adapter for Node runtimes, but preview behavior is not detailed in the sources you provided.

5. When to choose which

Based on the docs:

Choose Netlify when:
- Your production hosting is Netlify.
- You want Netlify‑specific features (Image CDN, Netlify platform services). [On‑demand rendering; Netlify adapter]
Choose Node when:
- Your production hosting is a plain Node.js environment (VPS, Docker, custom Node host, etc.). [On‑demand rendering]

The docs don’t describe a recommended workflow where you switch between Node and Netlify just for local preview, so anything beyond “use the adapter that matches your deployment environment” would be outside what’s in the sources.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@solar cedar Kapa.ai is still learning and improving, please let me know how I did by reacting below.

solar cedar Dec 17, 2025, 4:10 AM

#

@paper mantle I added export const prerender = false; on my Form component as I needed it for some of the client side validation I was doing. I added the netlify adapter because of this.

I'm wondering exactly how my astro.config.mjs should look now.

  devToolbar: {
    enabled: false,
  },

  adapter: netlify(),
});```
Am I supposed to include ```output: `server```` in the defineConfig object?

paper mantleBOT Dec 17, 2025, 4:10 AM

#

Let me check the knowledge base for you again. One moment! :books:

#

Yes, when you use the Netlify adapter for SSR / on‑demand rendering, you should set output: 'server' in your astro.config.mjs.

The Netlify deployment guide shows the config like this: [Netlify deploy]

import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  output: 'server',
  adapter: netlify(),
});

So your config should be updated to:

import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  devToolbar: {
    enabled: false,
  },
  output: 'server',
  adapter: netlify(),
});

`export const prerender = false;` on a page/component is what makes that route use on‑demand rendering, and `output: 'server'` + the Netlify adapter tells Astro to build the project for Netlify’s server/edge environment. [Netlify deploy]

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@solar cedar Kapa.ai is still learning and improving, please let me know how I did by reacting below.

solar cedar Dec 17, 2025, 4:56 AM

#

@paper mantle and for the pages that are server side rendered, do I have to set export const prerender = true or thats implied.
Just double checking that the output: 'server' doesnt force everything

paper mantleBOT Dec 17, 2025, 4:56 AM

#

Let me check the knowledge base for you again. One moment! :books:

#

output: 'server' changes the default, but you can still control each route with prerender.

From the docs:

With the default (output: 'static'), everything is prerendered unless you opt out on a page/endpoint with:
```
export const prerender = false;
```
That page/endpoint will be server‑rendered on demand. [On‑demand guide]
With output: 'server', the opposite is true: all pages are server‑rendered by default. [On‑demand guide]

Then you can opt in specific routes to prerendering with:
```
export const prerender = true;
```
Example from the docs:
```
---
```

// src/pages/about-my-app.astro
export const prerender = true;


So to answer your questions:

- **Pages that are server‑side rendered in `output: 'server'` mode do _not_ need `export const prerender = false`; SSR is already the default.**
- You only use `export const prerender = true` on the pages/endpoints you want to be **static** in `output: 'server'` mode.
- `output: 'server'` does **not** force everything to be static; it forces everything to be **server‑rendered**, unless you explicitly mark a route with `prerender = true`.
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------

#

@solar cedar Kapa.ai is still learning and improving, please let me know how I did by reacting below.

solar cedar Dec 17, 2025, 4:58 AM

#

To confirm, if I only have 1 page/component that needs prerender to be false, I should keep output to server and just apply export const prerender = false on that specfic page @paper mantle

paper mantleBOT Dec 17, 2025, 4:58 AM

#

Let me check the knowledge base for you again. One moment! :books:

#

Not quite—this is reversed.

From the docs:

In the default output: 'static' mode, everything is prerendered by default, and you mark individual routes as server‑rendered with:
```
export const prerender = false;
```
[On-demand rendering]
In output: 'server' mode, everything is server‑rendered by default, and you mark individual routes as static with:
```
export const prerender = true;
```
[On-demand rendering]

So for your case:

If you have only one page that needs prerender = false and the rest can be static, the docs recommend staying in the default output: 'static' mode and just putting:
```
export const prerender = false;
```
on that specific page/endpoint. [On-demand rendering]
You would use output: 'server' only when most or all pages are server‑rendered, and then selectively mark static ones with prerender = true. [On-demand rendering]

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@solar cedar Kapa.ai is still learning and improving, please let me know how I did by reacting below.

solar cedar Dec 17, 2025, 5:13 AM

#

@paper mantle When preparing to build my project, do I need a gitignore file for anything in particular?

paper mantleBOT Dec 17, 2025, 5:13 AM

#

Let me check the knowledge base for you again. One moment! :books:

#

You don’t need a .gitignore specifically for building, but the docs do recommend ignoring one Astro‑specific directory:

.astro directory – Astro stores metadata for content collections here and updates it automatically when you run astro dev, astro build, or astro sync. You’re encouraged to ignore it in Git:
```
echo "\n.astro" >> .gitignore
```
[Content collections]

#Previewing Production Site

If you need `astro preview` specifically, the docs indicate you’d have to use the Node adapter instead of Netlify for that step.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

1. What is the Node adapter?

2. Is this “needed” for SSR pages?

3. What happens if you use Node instead of Netlify?

The provided Node adapter docs don’t describe a mixed “use Netlify for deploy but Node for preview” workflow explicitly, so anything beyond this (like exact preview commands or switching back and forth) is not covered in the sources.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

1. What the adapters are for

2. Configuration differences

5. When to choose which

The docs don’t describe a recommended workflow where you switch between Node and Netlify just for local preview, so anything beyond “use the adapter that matches your deployment environment” would be outside what’s in the sources.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

`export const prerender = false;` on a page/component is what makes that route use on‑demand rendering, and `output: 'server'` + the Netlify adapter tells Astro to build the project for Netlify’s server/edge environment. [Netlify deploy]

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

// src/pages/about-my-app.astro
export const prerender = true;

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

Beyond that, the knowledge sources don’t list any other required `.gitignore` entries for builds.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#Previewing Production Site

If you need astro preview specifically, the docs indicate you’d have to use the Node adapter instead of Netlify for that step.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

1. What is the Node adapter?

2. Is this “needed” for SSR pages?

3. What happens if you use Node instead of Netlify?

The provided Node adapter docs don’t describe a mixed “use Netlify for deploy but Node for preview” workflow explicitly, so anything beyond this (like exact preview commands or switching back and forth) is not covered in the sources.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

1. What the adapters are for

2. Configuration differences

5. When to choose which

The docs don’t describe a recommended workflow where you switch between Node and Netlify just for local preview, so anything beyond “use the adapter that matches your deployment environment” would be outside what’s in the sources.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

export const prerender = false; on a page/component is what makes that route use on‑demand rendering, and output: 'server' + the Netlify adapter tells Astro to build the project for Netlify’s server/edge environment. [Netlify deploy]

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

// src/pages/about-my-app.astro export const prerender = true;

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

Beyond that, the knowledge sources don’t list any other required .gitignore entries for builds.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

If you need `astro preview` specifically, the docs indicate you’d have to use the Node adapter instead of Netlify for that step.

`export const prerender = false;` on a page/component is what makes that route use on‑demand rendering, and `output: 'server'` + the Netlify adapter tells Astro to build the project for Netlify’s server/edge environment. [Netlify deploy]

// src/pages/about-my-app.astro
export const prerender = true;

Beyond that, the knowledge sources don’t list any other required `.gitignore` entries for builds.