Key Concepts

Pagesmith uses modern web architecture to create fast, SEO-friendly websites. This guide explains the key concepts so you understand what's happening under the hood.

Rendering Strategies: SSG vs SSR vs CSR

How a website renders determines its performance, SEO, and user experience.

Static Site Generation (SSG)

What it is: Pages are pre-built at compile time. When a user visits, they get pre-rendered HTML instantly.

Pagesmith default: Most pages use SSG.

Build time:  Markdown/Components → HTML files
User visit:  HTML served immediately (no processing)

Benefits:

• Fastest possible load times
• Perfect for SEO (HTML ready for crawlers)
• Cheap to host (just static files)
• Works without JavaScript

Best for: Landing pages, blogs, documentation, marketing sites.

Server-Side Rendering (SSR)

What it is: Pages are generated on each request by a server.

Pagesmith option: Add SSR when you need dynamic content.

User visit:  Request → Server generates HTML → Response

Benefits:

• Fresh data on every request
• Can access databases and APIs
• Content personalization possible

Best for: User dashboards, authenticated content, real-time data.

Client-Side Rendering (CSR)

What it is: An empty HTML shell loads, then JavaScript builds the page in the browser.

This is NOT what Pagesmith uses. Most AI builders generate CSR apps.

User visit:  Empty <div> → Download JS → Execute → Render content

Problems:

• Slow initial load (wait for JS)
• SEO issues (crawlers may not execute JS)
• Requires JavaScript to see content

Astro: The Framework Behind Pagesmith

Pagesmith generates Astro projects. Astro is a modern static site generator designed for content-focused websites.

Why Astro?

1. Zero JavaScript by default — Ships only HTML and CSS unless you add interactivity
2. Framework-agnostic — Use React, Vue, Svelte, or plain HTML
3. Islands architecture — JavaScript only where needed
4. Built-in optimizations — Image compression, CSS minification, prefetching

Astro Project Structure

my-site/
├── src/
│   ├── pages/           # Routes (each file = a page)
│   │   ├── index.astro  # → yoursite.com/
│   │   ├── about.astro  # → yoursite.com/about
│   │   └── blog/
│   │       └── [slug].astro  # → Dynamic blog posts
│   ├── components/      # Reusable UI pieces
│   ├── layouts/         # Page templates
│   └── content/         # Markdown/MDX content
├── public/              # Static assets (images, fonts)
└── astro.config.mjs     # Configuration

Islands Architecture

Islands let you add interactivity to specific parts of a static page without hydrating the entire page with JavaScript.

How Islands Work

┌─────────────────────────────────────────┐
│  Static HTML (no JS)                    │
│  ┌─────────────┐                        │
│  │ React Island│ ← Interactive component│
│  │ (with JS)   │   hydrates independently│
│  └─────────────┘                        │
│  More static HTML (no JS)               │
│  ┌─────────────┐                        │
│  │ React Island│ ← Another island       │
│  └─────────────┘                        │
└─────────────────────────────────────────┘

Example: Contact Form Island

Most of your landing page is static. Only the contact form needs JavaScript:

---
// Static page content
import ContactForm from '../components/ContactForm.jsx';
---

<h1>Contact Us</h1>
<p>We'd love to hear from you.</p>

<!-- This React component hydrates on page load -->
<ContactForm client:load />

The page loads instantly with static HTML. The form becomes interactive after its small JS bundle loads.

Island Directives

Astro provides different loading strategies:

Edge Deployment

Pagesmith deploys sites to Cloudflare's global edge network.

What is Edge Deployment?

Instead of serving from one server, your site is copied to 300+ locations worldwide. Users get content from the nearest location.

Traditional:
User (Tokyo) → Server (US) → Response (200ms latency)

Edge:
User (Tokyo) → Edge (Tokyo) → Response (20ms latency)

Benefits

• Speed — Sub-50ms responses globally
• Reliability — No single point of failure
• Scalability — Handle traffic spikes automatically
• Cost — Static files are cheap to serve

Database: Cloudflare D1

When you need dynamic data, Pagesmith can add a SQLite database via Cloudflare D1.

How It Works

SSR Page Request
       ↓
Cloudflare Worker (Edge)
       ↓
D1 Database Query
       ↓
Generated HTML Response

Use Cases

• User-generated content
• Dynamic listings
• Simple authentication
• Form submissions storage

See Database for implementation details.

SEO Fundamentals

Pagesmith handles SEO basics automatically, but understanding them helps you optimize further.

What Pagesmith Generates

For every page:

<head>
  <title>Page Title | Site Name</title>
  <meta name="description" content="Page description...">
  <link rel="canonical" href="https://yoursite.com/page">

  <!-- Open Graph (Facebook, LinkedIn) -->
  <meta property="og:title" content="Page Title">
  <meta property="og:description" content="...">
  <meta property="og:image" content="/og-image.png">

  <!-- Twitter Card -->
  <meta name="twitter:card" content="summary_large_image">
</head>

Plus site-wide:

• sitemap.xml — All pages for search engines
• robots.txt — Crawling instructions

Why This Matters

Search engines read HTML to understand your content. With SSG:

1. Crawler visits your page
2. Gets complete HTML immediately
3. Indexes your content

With CSR (what other AI builders use):

1. Crawler visits your page
2. Gets empty <div id="root"></div>
3. May or may not execute JavaScript
4. May or may not see your content

Summary

Pagesmith handles all of this. You describe what you want, and the AI generates code using these patterns correctly.