Astro + React Guide To Create AI Websites

Understand the Astro + React project exported by Siteplay.ai, including its directory structure, generated pages, hydrated React components, styling, and local development workflow.

Introduction

Siteplay.ai can export your AI-built website as an Astro + React + TypeScript project. Use this guide when you have downloaded the Astro React framework code and want a quick map of what is inside, where to make changes, and how the generated site fits together.

The exported Astro React project is built for users who want Astro’s fast static-first routing with React components for interactive sections.

The project uses:

Astro for file-based routing, layouts, and static-first rendering.
React + TypeScript for generated interactive components.
Tailwind CSS v4 for styling.
Shadcn-style React primitives for interactive UI elements.
SVG files and Lucide React for icons.
Motion for generated animations.
Astro client directives such as client:load when React components need browser-side hydration.

Directory structure

A freshly exported Siteplay.ai Astro React project follows this structure:

Directory
public/
- Directoryimages/
  - …
- robots.txt
Directory
src/
- Directoryassets/
  - …
- Directorycomponents/
  - Directorycommon/
    …
  - Directorysections/ ------------ all sections here
    Directoryglobal/
    Navbar.tsx
    Footer.tsx
    …
    Directoryhome/
    Hero.tsx
    …
  - Directoryui/
    Directoryicons/
    …
    button.tsx
    …
- Directoryhooks/
  - …
- Directorylayouts/
  - FullPageLayout.astro --- shared page layout here
- Directorypages/ ---------------- all pages here
  - Directorypage-1/
    …
  - index.astro
- Directorytypes/
  - …
- constants.ts ---------- all site defaults here
- global.css -------- global styles here
- theme.css --------- design system tokens here
- utils.ts
.env.local
.env.production
.gitignore
.prettierignore
.prettierrc
astro.config.mjs
components.json
package.json
README.md
tailwind.config.ts
tsconfig.json

Your downloaded project may include more generated files in src/components/sections and src/pages than this starter structure.

Important files

astro.config.mjs

File: /astro.config.mjs

This is the main Astro configuration file. It enables the React integration, connects Tailwind through Vite, and defines the @ alias for imports from src.

Use this file when you want to:

Add Astro integrations.
Change build or dev server behavior.
Adjust aliases or Vite plugins.
Configure framework-level tooling.

FullPageLayout.astro

File: /src/layouts/FullPageLayout.astro

This is the shared layout used by generated Siteplay pages. It imports global styles, applies default language and text direction, writes title and description metadata, adds the favicon and viewport tags, and initializes the default theme.

Use this file when you want to:

Add scripts or analytics.
Change root HTML attributes.
Add site-wide <head> tags.
Adjust SEO metadata behavior.
Change global theme behavior.

Page files

File: /src/pages/**/*.astro

Astro uses file-based routing. Siteplay.ai creates .astro page files from the pages in your sitemap. Each page usually loads a page object, imports generated React sections, and renders them inside FullPageLayout.astro.

Use generated page files when you want to:

Adjust page-level copy, data, or metadata.
Add custom page logic.
Connect a page to dynamic data.
Change route-specific behavior.
Reorder or insert generated sections manually.

Section files

File: /src/components/sections/[page]/*.tsx

This folder contains the React section components generated from the Siteplay.ai editor. A hero, pricing block, feature grid, testimonial section, contact form, footer, or FAQ section will typically live here.

Section files are organized based on the pages in the sitemap. Example: /src/components/sections/home/Hero.tsx

Use this folder when you want to customize one specific visual section without changing the rest of the site.

Global section files

File: /src/components/sections/global/*.tsx

Global sections are shared across pages. Navigation bars, footers, announcement bars, and other repeated sections usually live here.

Use this folder when you want one edit to update every page that uses the same global section.

Common component files

File: /src/components/common/*.tsx

This folder contains shared wrappers and elements used across generated pages and sections, such as page wrappers, theme providers, buttons, images, links, rich content, and background rendering helpers.

Use this folder when you want a change to apply consistently across many generated sections.

UI component primitives

File: /src/components/ui/*.tsx

This folder is reserved for lower-level UI primitives. Siteplay.ai uses these for interactive components such as accordions, dialogs, selects, navigation menus, form controls, and other reusable building blocks.

Most users should customize sections and common components first, and only edit UI primitives when changing the behavior of a shared control.

Hooks

File: /src/hooks/*.ts

This folder contains reusable React hooks. Use it for shared state, form helpers, animation helpers, responsive behavior, or site-specific behavior that is needed by multiple components.

utils.ts

File: /src/utils.ts

This file contains shared helper functions used by generated components, including class merging, form submission helpers, animation helpers, color utilities, and small formatting helpers.

constants.ts

File: /src/constants.ts

This file serves as the central configuration layer for the application. It defines shared defaults, reusable UI settings, layout defaults, background settings, and predefined animation presets used throughout the project.

Styling with Tailwind CSS

Files: /src/global.css and /src/theme.css

global.css contains global app styles and Tailwind entry styles. theme.css contains design tokens and CSS variables generated from the Siteplay.ai design system.

Public folder

File: /public/*

Static assets live in public. Files placed here are served from the site root. For example, public/images/p.svg is available at /images/p.svg.

How Siteplay maps to Astro React

Siteplay.ai concept	Astro React output
Site	A complete Astro project with React integration
Page	A route under `src/pages`
Sitemap	Astro file-based routes generated from the sitemap
Section	A React component under `src/components/sections`
Global section	A reused React component under `src/components/sections/global`
Design system	Tailwind classes, CSS variables, theme constants, and layouts
SEO settings	Props passed into `FullPageLayout.astro`
Images and uploads	Static assets in `public` or imported assets in `src/assets`

Astro pages render mostly static HTML by default. React components become interactive when generated with Astro client directives such as client:load.

Run the project locally

Install dependencies
- npm
- pnpm
- Yarn
Terminal window
npm install
Terminal window
pnpm i
Terminal window
yarn
Run the code in local development
- npm
- pnpm
- Yarn
Terminal window
npm run dev
Terminal window
pnpm dev
Terminal window
yarn dev
Build for production
- npm
- pnpm
- Yarn
Terminal window
npm run build
Terminal window
pnpm build
Terminal window
yarn build
Preview production in local
- npm
- pnpm
- Yarn
Terminal window
npm run preview
Terminal window
pnpm preview
Terminal window
yarn preview

SEO metadata

Files: src/layouts/FullPageLayout.astro and src/pages/**/*.astro

Siteplay.ai page SEO settings are passed to the Astro layout through seo props.

<FullPageLayout seo={page.seo}>
  <!-- Page content -->
</FullPageLayout>

Deployment

The exported Astro React project produces a fast static build by default and can be deployed to Vercel, Netlify, Cloudflare Pages, GitHub Pages, S3, or any static hosting provider.

Before deploying:

Run npm run build.
Review final SEO metadata and domain-specific URLs.
Test key forms and links.
Check light and dark mode if both are enabled.

Troubleshooting

React components are not interactive

Check the generated .astro page and confirm interactive React components use an Astro client directive such as client:load.

Tailwind styles are missing

Check that src/global.css is imported by FullPageLayout.astro and that Tailwind is connected through astro.config.mjs.

Images are broken

Make sure referenced files exist in public or src/assets, and check whether the component expects a root URL such as /images/example.webp or an imported asset.