Web Development Standards

Overview

This standard covers every web project I ship — from content-heavy Astro sites and SaaS dashboards to marketing landing pages and API services. It assumes familiarity with the General Standards (file structures, Git, a11y, privacy) and builds on them with web-specific guidance.

What this covers:

• Full-stack applications (Next.js, Astro + API routes)
• Content-driven sites (Astro, MDX collections)
• SaaS platforms (auth, billing, multi-tenant)
• Landing pages and marketing sites
• API services and backend utilities

Tech Stack (2026)

Recommended Core

When to Deviate

• Astro vs Next.js: Choose Astro when content-to-code ratio is high (portfolios, blogs, marketing). Choose Next.js when the app has significant server-rendered interactive features (dashboards, real-time UIs, complex auth flows).
• Preact vs React: Use Preact for content-focused sites with minimal interactivity (this site saves ~40KB gzipped). Use React 19 when you need React-specific libraries (React Three Fiber, DnD kits, complex charting).
• Database choice: Neon for relational data with complex queries. Turso for edge-read-heavy workloads. Supabase when you want auth + DB + storage in one service.

Project Scaffolding

File Structure

src/
├── app/                          # Next.js App Router or Astro pages
│   ├── (marketing)/              # Route groups for Next.js
│   ├── (dashboard)/
│   │   ├── layout.astro          # Dashboard shell with auth guard
│   │   └── settings/
│   └── api/                      # API routes
├── components/
│   ├── astro/                    # Zero-JS components (no hydration)
│   ├── react/                    # Client-island interactive components
│   └── mdx/                      # MDX custom components (Callout, CodeBlock, etc.)
├── content/                      # Astro content collections
│   ├── config.ts                 # Collection schemas
│   └── posts/                    # MDX content files
├── lib/
│   ├── db/                       # Database client and queries
│   ├── auth/                     # Auth configuration
│   ├── api/                      # External API clients
│   └── utils/                    # Pure utility functions
├── store/                        # Nanostores (client state)
├── styles/                       # Global CSS, Tailwind config
│   ├── global.css
│   └── tokens.css                # Design tokens as CSS variables
├── types/                        # Shared TypeScript types
├── layouts/                      # Astro layouts
│   ├── MainLayout.astro
│   └── ResourceLayout.astro
├── pages/                        # Next.js Pages Router (legacy)
└── middleware.ts                 # Next.js middleware (auth, redirects)

Initial Setup Checklist

• npm create astro@latest or npx create-next-app@latest
• TypeScript strict mode enabled
• Path aliases configured (@/ → src/)
• Tailwind configured with design tokens (dark/light theme)
• ESLint + Prettier configured
• Husky pre-commit hooks: check → test → build
• Environment variable schema (Zod or Env)
• CI/CD pipeline (GitHub Actions)
• Error monitoring (Sentry)
• Lighthouse CI automation

Architecture & Design Patterns

Astro-Specific Patterns

Islands architecture: Only ship JavaScript for interactive components. Everything else is static HTML. Use client directives strategically:

Content collections: Use Zod-validated frontmatter schemas for all content. This provides type safety, validation errors at build time, and IDE autocompletion.

View transitions: Use Astro’s built-in view transitions for smooth page navigation without client-side routing overhead. Add transition:persist to persistent elements (navbar, search trigger).

Next.js-Specific Patterns

• App Router for new projects (Pages Router only for legacy)
• Server Components by default, client components only when interactivity requires it
• Route handlers for API endpoints (avoid Pages API routes)
• Middleware for auth checks, redirects, and geolocation
• Server Actions for form mutations

Patterns That Apply to Both

Component organization:

• Presentational components are Astro or server components (zero JS)
• Interactive components are Preact/React islands or client components
• Shared logic lives in lib/ as pure functions
• Feature modules in features/ for complex domains

Data fetching:

• Fetch at the page/layout level, pass down to components
• Use Astro’s Astro.fetch() or Next.js server components for data
• Client-side fetching only for real-time data or user-specific content
• Cache strategy: static generation where possible, ISR for dynamic content, SSR for personalized

Performance Standards

Build Targets

Astro-Specific Optimization

• Zero-JS baseline — Every page should function (and look complete) with JavaScript disabled. Only interactive islands require JS.
• Preact over React — Replace React with Preact via @preact/compat for ~40KB gzipped savings. See the Preact migration guide.
• Component islands — Each island is independently hydrated. Unused framework code is tree-shaken by Astro’s compiler.
• Static generation — Pre-render every possible page at build time. Use export const prerender = true for static pages in hybrid mode.
• Image optimization — Use Astro’s <Image /> or <OptimizedImage /> component with responsive srcsets and modern formats.
• Font subsetting — Use @fontsource packages or manually subset fonts for Latin-only character support.

Next.js-Specific Optimization

• React Server Components — Zero JS for server-rendered content
• Streaming — Use loading.tsx and Suspense boundaries for progressive rendering
• Image optimization — Built-in <Image> component with automatic AVIF/WebP
• Partial Prerendering (PPR) — Static shell + dynamic holes for hybrid pages

SEO & Content Strategy

On-Page SEO Checklist

• Unique h1 that includes primary keyword
• Meta description ≤ 160 chars with CTA
• URL is descriptive, short, kebab-case
• Open Graph image (1200×630) for every page
• JSON-LD structured data (Article, TechArticle, BreadcrumbList)
• Internal links to related content (≥ 3 per page)
• Proper heading hierarchy (h1 → h2 → h3)
• Alt text on all images
• Canonical URL set
• Sitemap submitted to Google Search Console

Content Architecture

• Pillar pages — Comprehensive guides on core topics (like this Resources section)
• Cluster content — Blog posts that link back to pillar pages
• Topic tags — Consistent tagging across all content for topic clusters
• Freshness — Update dates on content pages to signal recency to search engines and AI models
• Readability — Short paragraphs, clear headings, bullet points for scannability

Content Collections Schema (Astro)

title: string (max 60 chars)        → SEO title
description: string (max 160 chars) → meta description
pubDate: date                        → publish date
updatedDate: date?                   → last significant update
category: enum                       → topic grouping
tags: string[]                       → internal tagging, URL params
image: string                        → OG image path
draft: boolean                       → skip in production builds

Development Workflow

Pre-Commit Pipeline (Husky)

1. npm run check    → TypeScript check + Astro diagnostics
2. npm test         → Unit + integration tests
3. npm run build    → Production build (catches build errors)

This runs on every commit. If any step fails, the commit is blocked. Fix, re-stage, and commit again.

Branch Strategy

main                         → production (protected, auto-deploys)
feat/feature-name            → new features
fix/bug-description          → bug fixes
chore/dependency-update      → tooling, deps, config
docs/content-update          → blog posts, documentation

PR Review Checklist (Self)

• Tests pass and new tests added for changes
• Lighthouse 100 verified
• Accessibility: keyboard nav + screen reader spot-check
• Mobile responsive: test at 375px and 768px widths
• Dark mode: verify all new UI elements in both themes
• No new dependencies without review (bundle impact)
• .env.example updated if new environment variables added

APIs & Backend

API Design Principles

• RESTful for public APIs, tRPC for internal full-stack typesafety
• Input validation on every endpoint (Zod schemas)
• Rate limiting on all public endpoints
• Error responses follow a consistent shape:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "details": [{ "field": "email", "issue": "required" }]
  }
}

• Authentication via Supabase Auth or NextAuth.js
• Database queries use Prisma for type safety and migrations
• Edge functions for latency-sensitive operations (Vercel Edge, Cloudflare Workers)

Review & Shipping Checklist

• All tests passing (unit + integration + E2E)
• Lighthouse 100 on desktop and mobile
• Accessibility audit: axe-core scan, keyboard tab-through, screen reader test
• Mobile responsive: 375px, 768px, 1024px, 1440px breakpoints
• Dark/light mode: all new components render correctly in both
• SEO: title, description, OG image, canonical, structured data
• Performance budget met: JS bundle ≤ 100KB, LCP ≤ 2.5s
• Dependency audit: npm audit, no new vulnerabilities
• Privacy review: no data collection without consent, no unexpected network calls
• Error monitoring configured (Sentry)
• CHANGELOG updated
• Production build tested locally (npm run build && npm run preview)
• Staging/preview deployment verified
• DNS/domain configured (see DevOps, Domains & Infrastructure)

Trends to Watch (2026+)

• React Compiler — Automatic memoization in React 19+ reduces manual useMemo/useCallback
• Edge rendering maturity — More workloads move to the edge for lower latency
• AI-generated UI — Component generation from prompts becoming practical for scaffolding
• WebGPU — Browser-based compute for data-heavy applications
• Islands everywhere — Astro’s partial hydration pattern being adopted by other frameworks
• Biome — Replacing ESLint + Prettier with a single Rust-based tool

Project Templates

• Astro Starter Kit — Complete project scaffold with Tailwind tokens, AI workflow cheatsheet, and this site’s exact config
• Next.js SaaS Template — Reference architecture from Creator Hub (this site)
• SaaS Starter — Next.js + Prisma + Stripe + auth scaffold from Xcelerate

References

• Deploying Astro in 2026 — Vercel vs Cloudflare vs Netlify comparison
• Astro 6 Islands Architecture — How this site implements partial hydration
• State Management with Nanostores — Client-side stores without React
• Zero-JS Theme Toggle — Dark/light mode without JavaScript for the initial render
• Privacy-First Analytics — Analytics without compromising user trust
• External: Astro Documentation, Next.js Documentation, Web.dev