How to Generate Website Previews for a Directory Built with Astro

For a local preview of an Astro directory’s production build, run npm run build and then npm run preview. The build writes the generated site to dist/ by default, and Astro’s preview server serves that output so you can inspect it before deployment. It reflects the most recent completed build, so rebuild after source changes. Use it for local checking, not production hosting. Astro CLI reference

For a URL teammates or a client can open, use a hosting provider’s branch or deploy preview workflow. The local Astro preview and a hosted branch preview solve different review needs: one checks generated output on your machine; the other provides a shareable deployment. Astro on Vercel · Astro on Netlify

1. Preview the built site locally

From the Astro project directory, use the package manager and scripts already configured by the project. A typical npm project has build and preview scripts that call the Astro CLI:

{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  }
}

If those scripts are present, run:

npm install
npm run build
npm run preview

Open the local address printed by the preview command. If the project does not define a preview script, invoke Astro through the package runner:

npx astro build
npx astro preview

With pnpm or Yarn, use the equivalent scripts, such as pnpm build and pnpm preview, or yarn build and yarn preview. Check package.json first: a repository may use a different script name or package manager.

Development server versus build preview

Workflow	What it serves	Best for
`astro dev`	The development site as you edit source files.	Day-to-day implementation and fast feedback.
`astro build` then `astro preview`	The output of the latest completed build, usually in `dist/`.	Checking the generated site before deployment and finding build-only issues.
Hosted deploy preview	A deployment created by the configured hosting workflow.	Sharing a review URL with people outside your machine.

The preview server does not rebuild when you edit source. After a change, run the build again and refresh the preview. Astro documents the development and build workflows separately in its development and build guide.

2. Check the directory’s build configuration

Astro’s common static build command is astro build (often exposed as npm run build), and the default output directory is dist/. A project can override the output directory, so confirm its configuration before setting up hosting or troubleshooting a missing folder. Astro deployment guide

Build command: commonly npm run build.
Output directory: commonly dist.
Package manager: use the lockfile and package manager adopted by the repository.
Monorepo: run the command in the Astro app’s directory, or configure the host’s project root and build paths accordingly.
Custom output: if the project changes outDir, configure the host to publish that directory rather than assuming dist.

For a static directory, Astro’s default prerendering and the build-preview workflow are usually appropriate. If pages must render on demand, configure the server output and an adapter for the selected host/runtime; the static preview workflow alone does not turn a static build into a deployed server-rendered application. Astro on-demand rendering

3. Create shareable previews for review

A local preview address is reachable from your machine, but it is not automatically a public review URL. To let teammates or a client inspect a change, connect the repository to a host and configure its preview deployment workflow.

Import or connect the repository with the hosting provider.
Set the Astro app’s project root if it lives in a monorepo.
Set the build command, typically npm run build, and the publish directory, commonly dist, for a static site.
Configure the production branch and preview behavior according to the team’s review process.
Push a branch or change and use the preview URL produced by the provider.

Astro’s Vercel guide describes Preview Deployments for branch pushes, with production deployments for the configured production branch. Its Netlify guide documents repository-triggered preview and production deploys according to the site’s deployment configuration. Provider settings vary, so check the relevant guide if the project changes its output directory, uses a monorepo, or needs an adapter. Vercel deployment guide · Netlify deployment guide

There is no universal host choice for every directory. Decide based on whether reviews must be local or shareable, whether each branch needs its own URL, how the build and output paths are configured, and whether the site is static or needs on-demand rendering.

4. Capture a preview as an image or PDF

Once a hosted preview URL exists, you can capture it for a ticket, design review, or document. For example, open the page in a browser and use its screenshot or print-to-PDF feature. A screenshot service can also capture a remote URL without setting up browser automation in your project. It needs a URL it can reach; a private branch deployment may require suitable access configuration.

Or skip the browser setup

For a reachable preview URL, ScreenshotNeo takes a screenshot with one GET request. See the ScreenshotNeo API documentation for request options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://your-preview.example.com -o preview.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://your-preview.example.com"},
    timeout=90,
)
open("preview.webp", "wb").write(r.content)

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://your-preview.example.com'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('preview.webp', res);

Replace the example URL with the full, reachable URL for the directory page. The Node.js example uses Bun’s file-writing helper; in Node.js, write the response body with await fs.writeFile('preview.webp', Buffer.from(await res.arrayBuffer())) after importing writeFile from node:fs/promises. The API can return PNG, JPEG, WebP, or PDF; configure the requested format as described in the docs.

ScreenshotNeo accepts cookie or consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each of those steps can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots.

5. Troubleshooting

Symptom	Likely cause	What to do
`astro preview` says the build output is missing.	The project has not been built, or its output directory differs from the expected default.	Run the build script first. Check Astro configuration for a custom output directory.
The preview does not show my latest edit.	The preview server serves the last completed build.	Run the build again, wait for it to finish, then reload the preview.
The build command fails.	Dependencies, package manager, working directory, or project configuration may be wrong.	Install dependencies using the repository’s package manager, run the script from the Astro app directory, and read the first build error for the specific cause.
A hosted deploy preview is missing or builds the wrong folder.	The repository root, build command, output directory, or branch workflow may not match the project.	Check the host’s project root, set the build command and publish directory to the app’s actual configuration, and review the provider’s preview deployment settings.
Static preview works but an on-demand page does not behave as expected.	The page requires server rendering, while the deployment is configured as a static build.	Configure Astro’s server output and the appropriate adapter for the intended host/runtime.
A screenshot of a private preview fails to load.	The capture service cannot access a URL protected by a login, VPN, or network restriction.	Use a reachable preview URL and configure access using the service’s supported headers or authentication options. Never place a reusable secret in a public URL.
The screenshot is blank or misses content.	The page may still be loading, require client-side rendering, or show a bot check.	Confirm the preview URL loads in a normal browser, then use capture wait options appropriate to the page. Check the response verdict and billing headers when using ScreenshotNeo.

6. Performance, reliability, and cost considerations

Build previews: local build-and-preview adds a build step, but provides a useful check of generated output. Keep the project’s normal development server for rapid edits.
Hosted previews: branch deployments make reviews shareable; build time and provider usage depend on the hosting configuration. The cited Astro documentation does not establish a universal cost or speed comparison between providers, so use the provider’s current plan details for budgeting.
Static versus on-demand: static output is generated ahead of time. Pages requiring server rendering need the matching adapter and host configuration, which changes the deployment setup.
Screenshot capture: capture only after the deployment is reachable. A URL that requires private network access cannot be fetched by an external service unless access is arranged. For ScreenshotNeo, cache hits and failed or blocked page outcomes are not billed, and the response identifies billing and page verdict.

FAQ

Does `astro preview` create a public URL?

No. It serves the generated build locally. Use a host’s deploy preview workflow when reviewers need a shareable URL.

Do I need an adapter for every Astro directory?

No. Static generation is Astro’s default. An adapter is needed when configuring on-demand rendering for a host/runtime.

Can I capture a local preview with a screenshot API?

A remote service needs to reach the URL it is asked to capture. A machine-only local address is generally not reachable from that service; use a reachable hosted preview URL.

Is there one best provider for Astro deploy previews?

The reviewed Astro guides describe workflows for Vercel and Netlify but do not establish a universal winner. Choose based on your repository workflow, build configuration, and rendering needs.