Build Errors

Module not found errors

If you see errors like Cannot find module:

# Delete node_modules and reinstall
rm -rf node_modules
npm install

TypeScript errors in site.ts

Ensure all required fields are present. Check the Configuration docs for the full schema.

Recipe initialization fails

Make sure you're using the correct recipe name:

# List available recipes
npm run init:recipe -- --help

# Use exact recipe name
npm run init:recipe -- --recipe=corporate

Styling Issues

CSS variables not applying

CSS variables are defined in src/styles/global.css. Make sure:

  • The variable name matches exactly (case-sensitive)
  • You're using var(--variable-name) syntax
  • The variable is defined in :root or a parent element

Dark mode colors not working

Dark mode uses [data-theme="dark"] selector. Check that:

  • Your component has dark mode variants defined
  • The data-theme attribute is on <html> or <body>

Fonts not loading

Fonts are loaded via Google Fonts in Layout.astro. To use custom fonts:

  1. Add font files to public/fonts/
  2. Define @font-face in global.css
  3. Update --font-primary and --font-heading variables

Component Issues

Navigation mega menu not working

The mega menu requires React hydration. Ensure:

  • client:load directive is on the Navigation component
  • Radix UI packages are installed (@radix-ui/react-navigation-menu)

Logo not displaying

Check your site.ts logo configuration:

  • text-only: Only needs text field
  • icon-text: Needs src, svgIcon, or emoji
  • gradient-box: Needs text (first character used)

Form not submitting

Check the browser console for errors. Common causes:

  • Invalid action URL
  • CORS issues with external endpoints
  • Missing required fields

Deployment Issues

404 errors on deployed site

For GitHub Pages or subfolder deployments, set the base in astro.config.mjs:

export default defineConfig({
  site: 'https://username.github.io',
  base: '/repo-name',
});

Sitemap URLs are wrong

Set the correct site URL in astro.config.mjs:

export default defineConfig({
  site: 'https://yourdomain.com',
});

Assets not loading in production

Ensure paths are relative or use the base config. Avoid absolute paths like /images/logo.png if using a subfolder deployment.

Still Stuck?

If you can't find a solution: