Web Tech Stack

Tech Preference

• Free Open Source Software (FOSS)
  • Often the lowest cost solution, if technical expertise exists in house.
  • Prefer free FOSS solutions as long as functionality and deliverability don’t suffer. Do not want to get locked into monthly subscriptions that must be paid regardless of usage.
  • Must be careful not to be penny wise and pound foolish, recognizing that time and technical expertise required to set up and maintain free solutions come at a price.

Framework

Primary: Astro Components (Default Strategy - 90% of cases)

• Astro (latest); really like Astro, especially for mostly static content and blogs, and flexibility to use any JavaScript framework for components
  • Astro Docs MCP server available
  • Strategic Decision (2025-11): Default to Astro components for all structural/layout components
  • Benefits: Zero framework overhead, native to Astro, zero build friction, perfect for static content
  • Use for: Headers, footers, navigation, layouts, cards, grids, and any component that doesn’t need complex reactivity

Secondary: Lightweight Interactivity Solutions (10% of cases)

• AlpineJS for interactive components when vanilla JavaScript is insufficient
  • Tiny library (~15KB), no build step required, perfect Astro integration
  • Use for: dropdowns, modals, tabs, dynamic filtering, form interactions
• Vanilla JavaScript Web Components for custom interactive elements
  • Framework-agnostic, future-proof, zero runtime overhead
  • Use for: custom animated elements, specialized interactive patterns
• Svelte (5.x) for complex interactive features only (if needed)
  • Reserve for: complex forms with real-time validation, state-heavy interactive UIs
  • Status: May experience build friction; only use if truly necessary

Minimal Use: React

• React with shadcn/ui available as fallback for complex interactive components
  • Only if Svelte 5 ecosystem issues persist
  • Can use original shadcn/ui (React) components with Astro’s partial hydration
  • More stable than Svelte 5 currently, but larger bundle size

Blog Content & Inline Content

• blog content and static pages
  • .md or .mdx
  • use a Web Component or Alpine directive for inline <SmartDebt entity="Coach"/> component (no framework needed)

Fluid Design System

• Hybrid Fluid Design System: Continuous fluid scaling (typography, spacing) constrained by breakpoints for structural changes.
• Tools: Utopia.fyi principles for generating fluid scales.
• Units: Primary use of rem, vw, and clamp() for continuous scaling.
• Constraints (Breakpoints for Structural/Legibility Control):
  • Text Readability Container Width: min: 25rem to max: 80rem.
  • Primary Navigation Structural Breakpoint: Header replaced with hamburger menu when container < 50rem (~768px).
  • CSS Variables: Used for all design parameters (tokens) to ensure themeability and maintainability.

UI Component System & Styling

Component Strategy: Build Custom Astro Components

• Primary Approach: Build a minimal custom component library using Astro + Tailwind CSS
  • Achieving Semantic Purity: Create reusable Astro components that encapsulate Tailwind utility classes, keeping page files semantic and readable
  • For example, instead of writing <p class="text-3xl font-bold">, create a custom <Price> component: <Price>$99</Price>
  • Benefits: No framework overhead, native to Astro, zero build friction, full control over styling
  • Starting point: Use Shadcn MCP Server to convert React/Svelte shadcn components to Astro syntax

Theming & Brand Colors

• Easy to change themes with a single CSS file (CSS variables)
• Support custom brand colors: Blue (primary), Hunter Green, Gold (#E6BA1D)
• Theme switching via dropdown (AlpineJS for interactivity)

Available Resources & Tools

Shadcn Component Conversion:

• Shadcn MCP Server
  • Enables AI assistants to convert React (shadcn/ui) components to Astro syntax
  • Can switch between React (shadcn/ui) and Svelte (shadcn-svelte) as reference
  • Can produce fully fluid design components
• Astro Integration - Official Shadcn/ui has Astro support

UI Block Libraries:

• Spectrum UI - Shadcn companion for UI components and blocks
• Kibo UI - High quality Shadcn/ui components
• Tailwind UI - Premium component library (if needed)
• SV Blocks - 100+ UI & marketing blocks (can be converted to Astro)

Theming Tools:

• Tweakcn - Theme customizer
• Custom CSS variables approach (already implemented in design-tokens.css)

Testing

A/B Testing

• important for efficiency of communication, mission, growth efforts
• Cloudflare Pages and Netlify both have built-in A/B testing that lets you split traffic between two different Git branches. This is the easiest and most efficient way to test different landing pages or layouts without complex setup.

Responsiveness

• Responsively App lets you preview your website on multiple device screens side by side, instantly synced.

Hosting

Static/Jamstack Hosting

• currently use CanadianWebHosting

  • Windows hosting for talbotstevens.com
  • Linux hosting for SmartDebtCoach.com
  • use for registering several domains (future use)

• Cloudflare Pages

  • Unbeatable performance, with massive global network. The free tier is incredibly generous and has no “fluff” that tries to upsell you. It integrates perfectly with other Cloudflare services you might use later (like R2 for storage or Workers for serverless functions). It has a FOSS-like feel in its generosity and power.
  • Cloudflare MCP server

• Alternative: Vercel, industry standard for Jamstack hosting, with very generous free tier.

Backend/VPS Hosting

• Frontend
  • Cloudflare Pages
• Backend
  • Want a Managed VPS for reliability, easy developer/deployment experience and customer support.
  • Cloudways on DigitalOcean Toronto
    • for hosting PHP/mySQL apps (EspoCRM, MariaDB, Sendy)
  • n8n Cloud, for n8n automation

Package Management

• pnpm instead of npm
• pnpm workspaces for monorepo structure

Build & Task Orchestration

• Astro (site framework, built on top of Vite)
• Vite (dev/build pipeline for Astro + Svelte)
• Optional: Turborepo or Nx if multiple sites/packages with heavy CI/CD builds

JavaScript Runtime

• Deno (preferred, modern runtime with built-in tooling)
• Node.js (legacy support, compatibility with many npm packages)

Monitoring

• Uptime Kuma A self-hosted monitoring tool, run in a Docker container on VPS. It will ping websites and backend services every minute and instantly notify you via email, Slack, Discord, etc., if anything goes down.

Auth

• might want restricted content on website or apps
• EspoCRM Portal / Supabase Auth Start Simple: EspoCRM has a built-in “Portal” feature that allows your contacts to log in and see specific data you expose to them.
• For more power: Supabase. Its Auth component is a standalone, world-class solution you can self-host or use their generous free tier. It provides social logins, magic links, etc., via a simple API.

Analytics

• Plausible Analytics A lightweight, privacy-first, open-source alternative to Google Analytics, without the complexity or privacy invasion. Self-host it in a Docker container on VPS.

Payments

• Stripe (or better)

Form Endpoints

• Need: A secure and reliable way to capture form submissions from the static Astro site and forward them to n8n without building a custom API.
• Solution(s):
  • Web3Forms: Excellent service with a generous free tier, spam protection, and simple setup.
  • Formspree: A mature, feature-rich alternative with a solid free tier.
• Why it’s important: Offloads the critical tasks of spam protection and high availability for form submissions, letting you focus on handling the data, not just capturing it.

Object Storage

• Need: A dedicated, scalable, and cost-effective place to store and serve files like lead magnet PDFs, user uploads, or large images.
• Solution(s):
  • Cloudflare R2: Integrates perfectly with Cloudflare Pages, is S3-compatible, and has $0 egress fees, making it extremely cost-effective for serving files.
• Why it’s important: Decouples file storage from your primary server, leading to better performance, simplified server backups, and lower costs at scale.

Secrets Management

• Need: A secure way to manage and use API keys, database passwords, and other credentials.
• Solution(s):
  • Platform Built-ins: Use the secure environment variable managers provided by Cloudflare Pages and n8n Cloud. This is a great starting point.
  • Doppler: A FOSS-friendly, professional-grade secret manager with a generous free tier. It centralizes all secrets and syncs them securely across all environments.
• Why it’s important: Prevents accidental exposure of critical credentials, a major and common security risk.

Backup Strategy

• Backend (Cloudways): Handled by Cloudways’ automated backups.
• Website Code (Git): Your Git provider (e.g., GitHub) is the versioned backup, and ZIP backups.
• n8n Workflows: n8n Cloud is backed up.
• Object Storage (R2): Inherently highly-redundant.

Site Search

• Need: An effective way for users to search your content as the site grows.
• Solution(s):
  • FOSS/Self-Hosted: Meilisearch: An incredibly fast, easy-to-use, and lightweight search engine you can self-host.
  • SaaS: Algolia: The industry gold standard for powerful, hosted search-as-a-service.

Error Tracking

• Need: Know when website has client-side bugs (JavaScript errors) that don’t cause the site to go down but break functionality for users.
• Solution(s):
  • Sentry.io: The industry standard for application error tracking with a very generous free tier. Add a small code snippet to your Astro site to get detailed reports on any errors users encounter.

IDE & Development Tools

Primary IDE: Cursor

• Cursor - AI-enhanced code editor (fork of VS Code with integrated AI)
• Much better than VS Code for AI-assisted development
• Can configure with indexed docs and knowledge base links for better context

Cursor Configuration for Website Development

Indexing & Docs Setup:

1. Open Cursor Settings: File → Preferences → Settings (or Ctrl+,)
2. Navigate to: Extensions → Cursor Settings → Indexing
3. Add Knowledge Base Paths:
   • Primary: D:\FSS\KB\Business\03_Processes\Website Dev\ (Main tech stack docs)
     • Web Tech Stack.md - Tech choices and architecture (critical context)
     • Template\Lessons-Template-Dev.md - Lessons learned from Template project
     • Template\Plan-Template-Dev.md - Development planning
   • Secondary: D:\FSS\Websites\monorepo\sites\Template\docs\ (Project-specific docs)
     • COMPONENT_LIBRARY.md - Custom Astro components documentation
     • COMPONENT_IMPLEMENTATION_PLAN.md - Component build roadmap

Features to Enable:

• ✅ Indexing: Enable for faster context retrieval
• ✅ Docs: Link to knowledge base files for AI context
• ✅ @-mentions: Use @web-tech-stack to reference KB documents in chat

Development Workflow:

• Local Dev Server: pnpm dev - Runs Astro on http://localhost:4321
• Browser Preview: Open dev site directly in browser (see Live Dev Build section)
• Component Editing: Edit source files while viewing live preview
• AI Pair Programming: Use Cursor’s AI with @-references to relevant docs

Live Astro Dev Build Viewing (CRITICAL)

Direct Access (RECOMMENDED):

1. Start dev server: pnpm dev
2. In your web browser, navigate to: http://localhost:4321
3. This shows your live Astro site with all components
4. Changes auto-refresh as you edit files

Testing & Development Flow:

1. Start dev server: pnpm dev (runs on http://localhost:4321)
2. Open browser to http://localhost:4321/components
3. Edit components in src/components/ui/ or src/pages/
4. Changes auto-refresh in browser
5. Use browser dev tools to inspect and debug

Browser Dev Tools Usage:

• F12 - Open dev tools
• Ctrl+Shift+C - Element picker (click to inspect)
• Ctrl+Shift+M - Responsive design mode
• Right-click element → “Inspect” to view HTML/CSS directly
• Elements tab - View DOM structure
• Console tab - Check for JavaScript errors
• Network tab - Monitor asset loading

Git & Version Control

• GitHub - Remote repository hosting
• Git - Local version control
• Cursor Git Integration: Built-in source control panel (Ctrl+Shift+G)
  • Stage/unstage files
  • Commit with meaningful messages
  • Push/pull changes
  • View commit history

Browser Tools for Component Testing

• Responsively App - Multi-device simultaneous preview
• Browser DevTools (F12) - Built-in browser developer tools
  • Element inspection
  • CSS debugging
  • Console for errors
  • Network monitoring