Skip to content

README.md

Latest commit

 

History

History
257 lines (191 loc) · 6.07 KB

README.md

File metadata and controls

257 lines (191 loc) · 6.07 KB
Raw

SSR/CSR Analytics Dashboard

Changelog Live Dashboard

Real-time analytics dashboard for the CSR vs SSR Detector Chrome extension.

Live Dashboard

View Live Dashboard

Features:

  • Real-time stats with 30-second auto-refresh
  • SSR/CSR/Hybrid distribution charts
  • Core Web Vitals by render type (LCP, CLS, TTFB, pass rate)
  • SPA vs MPA navigation behavior by render type
  • Framework detection trends
  • Top analyzed domains (with country flags and page titles)
  • Recent analyses table with infinite scroll and record deletion

Tech Stack

  • Framework: Next.js 14 (App Router)
  • Database: Vercel Postgres
  • UI: Tremor (charts and dashboard components)
  • Styling: Tailwind CSS
  • Hosting: Vercel

Setup Instructions

1. Install Dependencies

npm install

2. Set Up Environment Variables

Create a .env.local file:

cp .env.example .env.local

Then fill in the values:

# After creating Vercel Postgres, copy these from Vercel dashboard
POSTGRES_URL="postgres://..."
POSTGRES_PRISMA_URL="postgres://..."
POSTGRES_URL_NON_POOLING="postgres://..."
POSTGRES_USER="..."
POSTGRES_HOST="..."
POSTGRES_PASSWORD="..."
POSTGRES_DATABASE="..."

# Optional: API key for additional security (not required, CORS is used)
# API_SECRET_KEY="your-super-secret-key-here"

3. Run Locally

npm run dev       # http://localhost:3000
npm run test:run  # unit tests

Deployment to Vercel

Day-to-day deploys are automatic: merges to main deploy production via the Vercel GitHub integration (project root is backend/). The options below are only needed for first-time project setup.

Option 1: Using Vercel CLI

  1. Install Vercel CLI:
npm i -g vercel
  1. Login to Vercel:
vercel login
  1. Deploy:
cd backend
vercel

  1. Add Vercel Postgres:

    • Go to your project on Vercel dashboard
    • Navigate to Storage tab
    • Click "Create Database"
    • Select "Postgres"
    • Environment variables will be automatically added

  2. Set up the database:

    • After Postgres is connected, run the setup script:
vercel env pull .env.local  # Pull environment variables
npm run db:setup

  1. Optional API Key:

    • In Vercel dashboard, go to Settings > Environment Variables
    • Add API_SECRET_KEY with a secure random value

  2. Redeploy:

vercel --prod

Option 2: Using Vercel Dashboard

  1. Push this backend folder to a GitHub repository
  2. Go to vercel.com
  3. Click "Import Project"
  4. Select your repository
  5. Configure:
    • Root Directory: backend
    • Framework Preset: Next.js
  6. Add environment variables in the dashboard
  7. Deploy
  8. Add Vercel Postgres from Storage tab
  9. Run setup script (see above)

Database Setup

After deploying and adding Vercel Postgres, run:

npm run db:setup

This creates the analyses table with all necessary indexes.

API Endpoints

POST /api/analyze

Submit analysis data from the extension.

Headers:

  • Content-Type: application/json
  • x-api-key: (Optional) API key if configured on server

Body:

{
  "url": "https://example.com",
  "domain": "example.com",
  "renderType": "Server-Side Rendered (SSR)",
  "confidence": 85,
  "frameworks": ["Next.js", "React"],
  "performanceMetrics": {
    "domReady": 125,
    "fcp": 650
  },
  "indicators": ["Rich initial content", "Hydration markers"],
  "version": "3.7.0"
}

Response:

{
  "success": true,
  "id": 123
}

GET /api/stats

Get aggregated statistics.

Query Parameters:

  • type: all, total, frameworks, domains, timeline, recent, contentComparison
  • limit: Number of results (for frameworks, domains, recent)
  • offset: Pagination offset (for recent)
  • days: Number of days for timeline (default: 30)

Examples:

  • /api/stats?type=all - All stats (Phase 1-3, preferred)
  • /api/stats?type=frameworks&limit=10 - Top 10 frameworks
  • /api/stats?type=timeline&days=7 - Last 7 days

DELETE /api/analyze/[id]

Remove a single analysis record (used by the dashboard's delete action).

Dashboard

Access at: /dashboard

Features:

  • Total analyses count
  • SSR/CSR/Hybrid distribution
  • Top frameworks detected
  • Timeline of analyses
  • Recent analyses table
  • Real-time updates

Chrome Extension Integration

Telemetry is already built into the extension (since v3.2.0) — see sendAnalysisData() in extension/popup.js. To point it at your own deployment, change the BACKEND_URL constant there. Users can opt out via the "Share Anonymous Data" toggle in the extension settings.

Security

  • CORS headers restrict browser requests to allowed origins
  • Optional API key authentication (disabled by default)
  • Rate limiting (implement with Upstash Redis in production)
  • Input validation and sanitization
  • No sensitive user data stored (only domains, not full URLs)
  • HTTPS only in production

Monitoring

  • Check Vercel dashboard for deployment logs
  • Monitor database usage in Vercel Postgres tab
  • Set up alerts for errors

Cost Estimate

Free Tier (Starting out):

  • Vercel: Free (100GB bandwidth, unlimited requests)
  • Vercel Postgres: Free (256MB storage, 60 hours compute/month)

Pro Tier (If you exceed free tier):

  • Vercel Pro: $20/month
  • Postgres Pro: $10+/month

Changelog

See CHANGELOG.md for version history.

Related

Support

For issues or questions:

  • GitHub Issues
  • Check Vercel logs for errors
  • Review database queries in Vercel Postgres dashboard
  • Check environment variables are set correctly

License

MIT License - see LICENSE