Skip to content
FiNAN Logo FiNAN Docs

Build Process

This guide explains how to build the FiNAN website for production. The project uses Astro’s static site generation (SSG) to create highly optimized HTML, CSS, and JavaScript files.

Running a Production Build

Section titled “Running a Production Build”

To can create a production build locally by running the build command. This is exactly what the CI/CD pipeline runs when you push to GitHub.

  1. Open your terminal to the project root directory.

  2. Run the build command:

    Terminal window
    pnpm build

  3. Wait for completion. You should see output indicating that pages are being generated:

    Terminal window
    16:45:01 [build] output: "static"
    16:45:01 [build] directory: /dist/
    16:45:01 [build] Collecting build info...
    16:45:01 [build] Completed in 54ms.
    16:45:01 [build] Building client...
    16:45:03 [build] Completed in 1.45s.

Build Output

Section titled “Build Output”

The build process generates a dist/ directory containing the static files. This directory is what gets deployed to the hosting platform.

  • Directorydist/
    • Directory_astro/ # Hashed JavaScript and CSS assets
      • …
    • Directoryassets/ # Processed images
      • …
    • Directoryrepresentation/ # Generated country pages
      • …
    • Directoryicons/ # Icon assets
      • …
    • 404.html # Custom error page
    • index.html # Homepage
    • sitemap-0.xml # XML Sitemap
    • site.webmanifest # PWA Manifest

What Happens During Build?

Section titled “What Happens During Build?”
  1. Validation: Astro checks your content collections (Markdown/MDX frontmatter) against the schemas defined in src/content/config.ts.
  2. Code Compilation: TypeScript is compiled to JavaScript, and modern JavaScript is transpiled for browser compatibility.
  3. Asset Optimization: Images in src/assets/ are optimized and converted to WebP/AVIF formats.
  4. Static Generation: Every .astro page and Markdown file is rendered into a static .html file.
  5. Sitemap Creation: A sitemap-index.xml and sitemap-0.xml are automatically generated based on your routes.

Pre-Deployment Checklist

Section titled “Pre-Deployment Checklist”

Before pushing code to main or triggering a deployment, run through this checklist to ensure a smooth update.

1. Verification

Section titled “1. Verification”
  • Run pnpm build locally - Verify there are no errors.
  • Check pnpm dev - Browse the site locally to spot check visual regressions.
  • Validate Links - Ensure internal links point to valid pages.

2. Assets & Content

Section titled “2. Assets & Content”
  • Optimize Images - Ensure new images are placed in src/assets/ and use the built-in optimization.
  • Check Frontmatter - Verify all new markdown content has required fields (title, description).
  • Committee Data - If updating committee members, ensure IDs are unique and photos exist.

3. SEO & Metadata

Section titled “3. SEO & Metadata”
  • Page Titles - Ensure all new pages have unique, descriptive titles.
  • Descriptions - Check meta descriptions for accuracy.
  • Open Graph - Verify social sharing images if custom ones are used.

Troubleshooting Builds

Section titled “Troubleshooting Builds”

If the build fails, check common culprits:

  • Type Errors: Run pnpm typecheck (or check your editor) to find TypeScript mismatches.
  • Missing Assets: Ensure images referenced in Markdown or components actually exist.
  • Invalid Frontmatter: Check that dates are valid and required fields are present.
  • Broken Links: Astro will warn or fail if you link to a non-existent internal page.