refactor: replace Astro frontend with Vite and Preact

Author: gildesmarais

.github/copilot-instructions.md

@@ -3,8 +3,8 @@
 ## Overview
 
 - Ruby web app that converts websites into RSS 2.0 feeds.
-- Built with **Roda** backend + **Astro** frontend, using the **html2rss** gem (+ `html2rss-configs`).
-- **Frontend:** Modern Astro-based UI with component architecture, served alongside Ruby backend.
+- Built with **Roda** backend + **Preact** frontend, using the **html2rss** gem (+ `html2rss-configs`).
+- **Frontend:** Vite-built Preact UI, served alongside Ruby backend.
 
 ## Documentation website of core dependencies
 
@@ -14,10 +14,10 @@ Search these pages before using them. Find examples, plugins, UI components, and
 
 1. https://roda.jeremyevans.net/documentation.html
 
-### Astro & Starlight
+### Preact & Vite
 
-1. https://docs.astro.build/en/getting-started/
-2. https://starlight.astro.build/getting-started/
+1. https://preactjs.com/guide/v10/getting-started/
+2. https://vite.dev/guide/
 
 ### html2rss
 
@@ -40,8 +40,8 @@ Fix rubocop `RSpec/MultipleExpectations` adding rspec tag `:aggregate_failures`.
 - ✅ Validate all inputs. Pass outbound requests through **SSRF filter**.
 - ✅ Add caching headers where appropriate (`Rack::Cache`).
 - ✅ Errors: friendly messages for users, detailed logging internally.
-- ✅ **Frontend**: Use Astro components in `frontend/src/`. Keep it simple.
-- ✅ **CSS**: Use frontend styles provided by Astro Starlight.
+- ✅ **Frontend**: Use Preact components in `frontend/src/`. Keep it simple.
+- ✅ **CSS**: Use the app-owned frontend styles in `frontend/src/styles/`.
 - ✅ **Specs**: RSpec for Ruby, build tests for frontend.
 - ✅ When a spec needs to tweak environment variables, wrap the example in `ClimateControl.modify` so state is restored automatically.
 

.github/workflows/ci.yml

@@ -127,7 +127,7 @@ jobs:
         run: npm ci
         working-directory: frontend
 
-      - name: Build frontend
+      - name: Build frontend static assets
         run: npm run build
         working-directory: frontend
 
@@ -162,7 +162,7 @@ jobs:
         run: npm ci
         working-directory: frontend
 
-      - name: Build frontend
+      - name: Build frontend static assets
         run: npm run build
         working-directory: frontend
 

Dockerfile

@@ -77,6 +77,6 @@ USER html2rss
 
 COPY --from=builder /usr/local/bundle /usr/local/bundle
 COPY --chown=$USER:$USER . /app
-COPY --from=frontend-builder --chown=$USER:$USER /app/frontend/dist ./public/frontend
+COPY --from=frontend-builder --chown=$USER:$USER /app/public/frontend ./public/frontend
 
 CMD ["bundle", "exec", "puma", "-C", "./config/puma.rb"]

Makefile

@@ -28,7 +28,7 @@ dev: ## Start development server with live reload
 dev-ruby: ## Start Ruby server only
 	@bin/dev-ruby
 
-dev-frontend: ## Start Astro dev server only
+dev-frontend: ## Start frontend dev server only
 	@cd frontend && npm run dev
 
 test: ## Run all tests (Ruby + Frontend)
@@ -111,7 +111,7 @@ openai-lint-spectral: openapi-lint-spectral ## Alias for openapi-lint-spectral
 
 clean: ## Clean temporary files
 	@rm -rf tmp/rack-cache-* coverage/
-	@cd frontend && rm -rf dist/ .astro/ node_modules/
+	@cd frontend && rm -rf dist/ node_modules/
 	@echo "Clean complete!"
 
 frontend-setup: ## Setup frontend dependencies

README.md

@@ -2,7 +2,7 @@
 
 # html2rss-web
 
-html2rss-web converts arbitrary websites into RSS 2.0 feeds with a slim Ruby backend and an Astro-powered frontend.
+html2rss-web converts arbitrary websites into RSS 2.0 feeds with a slim Ruby backend and a Preact frontend.
 
 ## Links
 
@@ -12,25 +12,16 @@ html2rss-web converts arbitrary websites into RSS 2.0 feeds with a slim Ruby bac
 
 ## Highlights
 
-- Responsive Astro interface with gallery and custom feed creation.
+- Responsive Preact interface for demo, sign-in, conversion, and result flows.
 - Automatic source discovery with token-scoped permissions.
 - Signed public feed URLs that work in standard RSS readers.
 - Built-in SSRF defences, input validation, and HMAC-protected tokens.
 
 ## Architecture
 
 - **Backend:** Ruby + Roda, backed by the `html2rss` gem for extraction.
-- **Frontend:** Astro static site with progressive enhancement.
+- **Frontend:** Preact app built with Vite into `public/frontend`.
 - **Distribution:** Docker Compose by default; other deployments require manual wiring.
-
-## Documentation
-
-In-repo docs live under `frontend/src/content/docs/` and are published by Astro.
-
-- [Configuration Guide](frontend/src/content/docs/configuration.md)
-- [Security Guide](frontend/src/content/docs/security.md)
-- [REST API v1](frontend/src/content/docs/api/v1.md)
-- [Testing Overview](frontend/src/content/docs/testing.md)
 - [v2 Migration Guide](docs/migrations/v2.md)
 
 ## REST API Snapshot
@@ -73,17 +64,17 @@ bundle exec rspec
 make openapi
 ```
 
-Dev URLs: Ruby app at `http://localhost:4000`, Astro dev server at `http://localhost:4001`.
+Dev URLs: Ruby app at `http://localhost:4000`, frontend dev server at `http://localhost:4001`.
 
 ## Make Targets
 
 | Command              | Purpose                                                 |
 | -------------------- | ------------------------------------------------------- |
 | `make help`          | List available shortcuts.                               |
 | `make setup`         | Install Ruby and Node dependencies.                     |
-| `make dev`           | Run Ruby (port 4000) and Astro (port 4001) dev servers. |
+| `make dev`           | Run Ruby (port 4000) and frontend (port 4001) dev servers. |
 | `make dev-ruby`      | Start only the Ruby server.                             |
-| `make dev-frontend`  | Start only the Astro dev server (port 4001).            |
+| `make dev-frontend`  | Start only the frontend dev server (port 4001).         |
 | `make test`          | Run Ruby and frontend test suites.                      |
 | `make test-ruby`     | Run Ruby specs.                                         |
 | `make test-frontend` | Run frontend unit and contract tests.                   |
@@ -105,8 +96,8 @@ The OpenAPI file is generated from Ruby request specs only.
 
 | Command                 | Purpose                                       |
 | ----------------------- | --------------------------------------------- |
-| `npm run dev`           | Astro dev server with hot reload (port 4001). |
-| `npm run build`         | Production build.                             |
+| `npm run dev`           | Vite dev server with hot reload (port 4001).  |
+| `npm run build`         | Build static assets into `public/frontend`.   |
 | `npm run test:run`      | Unit tests (Vitest).                          |
 | `npm run test:contract` | Contract tests with MSW.                      |
 

bin/dev

@@ -26,17 +26,17 @@ cleanup() {
     wait $RUBY_PID 2>/dev/null || true
   fi
 
-  # Kill Astro server and its children
-  if [ ! -z "$ASTRO_PID" ]; then
+  # Kill frontend dev server and its children
+  if [ ! -z "$FRONTEND_PID" ]; then
     # Kill the npm process and its children
-    pkill -P $ASTRO_PID 2>/dev/null || true
-    kill $ASTRO_PID 2>/dev/null || true
-    wait $ASTRO_PID 2>/dev/null || true
+    pkill -P $FRONTEND_PID 2>/dev/null || true
+    kill $FRONTEND_PID 2>/dev/null || true
+    wait $FRONTEND_PID 2>/dev/null || true
   fi
 
   # Clean up any remaining processes on our ports
   pkill -f "puma.*html2rss-web" 2>/dev/null || true
-  pkill -f "astro.*dev.*4001" 2>/dev/null || true
+  pkill -f "vite.*4001" 2>/dev/null || true
 
   echo "✅ Development servers stopped"
   exit 0
@@ -77,18 +77,18 @@ if [ "$ruby_started" != "true" ]; then
   exit 1
 fi
 
-# Start Astro dev server
+# Start frontend dev server
 cd frontend
 npm run dev &
-ASTRO_PID=$!
+FRONTEND_PID=$!
 
-# Verify Astro server started
+# Verify frontend server started
 sleep 3
-if ! kill -0 $ASTRO_PID 2>/dev/null; then
-  echo "❌ Astro dev server failed to start"
+if ! kill -0 $FRONTEND_PID 2>/dev/null; then
+  echo "❌ Frontend dev server failed to start"
   kill $RUBY_PID 2>/dev/null || true
   exit 1
 fi
 
 echo "✅ Development environment ready at http://localhost:4001"
-wait $RUBY_PID $ASTRO_PID
+wait $RUBY_PID $FRONTEND_PID

frontend/.astro/types.d.ts

@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="robots" content="noindex, nofollow" />
+    <meta
+      name="description"
+      content="Convert websites to RSS feeds instantly with html2rss-web."
+    />
+    <title>Turn Any Website Into an RSS Feed Instantly</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+  </html>