How to Build an Astro Website for Production

Build an Astro website for production by installing its recorded dependencies, supplying the required configuration and running the project’s build script. Then test the resulting output before publishing. A successful build confirms that generation completed; it does not prove that content, forms, metadata or deployment settings are correct.

For a static Astro template, the default output directory is usually dist. A server-rendered project has runtime requirements that change the deployment process. Establish which mode the package uses before choosing host settings.

Freeze the intended source state

Start from a known revision of the project. Check that intended content and configuration changes are saved, and keep unrelated experiments out of the release. Preserve the lockfile used to resolve dependencies.

Write down the runtime major version and package manager. A local build and a hosting build should use compatible environments. Otherwise, a project may work on one machine and fail during deployment for reasons unrelated to the page source.

If the package has never run successfully, complete template installation first. Production preparation is easier when you already have a verified baseline.

Review the build script

Inspect package.json rather than assuming every project defines the same commands. A common arrangement is:

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

Do not replace a real project’s manifest with this extract. It only illustrates the script names used in the following steps. A product may also generate search data, validate content or run other preparation tasks before Astro builds.

Read the instructions for those steps and keep their order. Skipping a generated search index can leave a website that builds but has an incomplete customer-facing feature.

Configure the public destination

Set the site’s intended public origin where the package expects it. Review any deployment base path, canonical generation, sitemap integration and social preview URLs. These settings should agree with the actual domain and route structure.

A preview deployment can use a different address from production. Decide how the project handles that difference so temporary preview URLs are not accidentally published as permanent metadata.

Also inspect environment variable names and required service settings. Supply private values through the intended environment mechanism, and check that they are not rendered into public pages or browser assets.

Run a clean build

For an npm project with a matching lockfile and the scripts above, a typical sequence is:

npm ci
npm run build
npm run preview

Use the project’s documented package manager if it differs. Read build warnings as well as the final success message, especially warnings about missing content, unresolved assets or unsupported configuration.

Astro’s deployment documentation explains the standard build and output model. The host’s settings must still match your actual project, including any adapter or custom output directory.

Know which checks build does not perform

A production build can generate a page whose telephone number is wrong. It can also generate a button pointing at a nonexistent service or a form that has no working delivery destination. Structural success and business correctness are separate checks.

Astro’s TypeScript guide also distinguishes ordinary development and build work from dedicated type checking. If the project defines a check script, run the documented check and make sure the required checking tools are installed.

Avoid claiming that all TypeScript is error-free solely because a build completed. Use the project’s actual checks and report what they establish.

Inspect the generated website

Choose representative routes rather than checking only the homepage. Include a long article, a listing, a nested service page, a contact page and a missing-page response.

Open important routes directly. Check images, fonts and scripts on nested paths. Test menu behaviour and focus visibility at narrow widths, and verify that important content is readable without interacting with decorative effects.

Compare the generated page title, description and canonical value with the intended destination. If the project uses a sitemap, inspect its URLs and verify that they refer to public pages rather than source files or temporary previews.

Deploy the right output

A static host needs the generated public files, not the source folder containing package.json. A connected build service usually needs the repository, build command and output directory so it can generate those files itself.

A project with on-demand rendering needs a compatible adapter and runtime. Read Astro static rendering vs server rendering before applying a static-only deployment recipe to it.

Do not infer compatibility from a product demo alone. The ProofCase listing gives product-specific requirements to compare with a proposed deployment environment.

Verify after publication

Open the final domain and repeat the critical checks there. Confirm secure connections, redirects, form delivery and direct access to inner routes. Local preview cannot establish that DNS, host rules or external service credentials are configured correctly.

Keep the source revision and deployment record so a release can be identified and reversed. The Astro template overview explains how this repeatable publication process supports later edits and content expansion.