🔮 SelfOpt — Self-Optimizing Frontend Library

Observe site health, detect decay, and apply safe optimizations.

The Problem

Websites decay over time even if no code changes are made:

• Performance regressions (slower LCP, higher CLS)
• Broken links or failed resources
• SEO hygiene decay (missing meta tags, broken canonical URLs)
• Browser API deprecations
• UX instability (layout shifts, dead buttons)

Most tools are heavy, backend-driven, or dashboard-based. SelfOpt is different.

The Solution

A frontend-first, zero-backend JavaScript library that:

• ✅ Observes site health in real-time
• ✅ Detects decay signals using Web Vitals
• ✅ Applies safe, transparent auto-optimizations
• ✅ Works without any server or paid service

Quick Start

npm install selfopt

import { initSelfOpt } from 'selfopt';

// Initialize in detect-only mode (safe, default)
const selfopt = initSelfOpt();

// Get health score
console.log('Health:', selfopt.getHealth().overall); // 0-100

// Get warnings
selfopt.getWarnings().forEach(w => console.log(w.message));

// Cleanup
selfopt.destroy();

Packages

| Package | Description | |---------|-------------| | selfopt | Core runtime library | | selfopt-react | React provider and hooks | | selfopt-cli | Command-line scanner and reporter |

React Usage

npm install selfopt-react

import { SelfOptProvider, useHealth, useWarnings } from 'selfopt-react';

function App() {
  return (
    <SelfOptProvider config={{ mode: 'detect' }}>
      <Dashboard />
    </SelfOptProvider>
  );
}

function Dashboard() {
  const { health } = useHealth();
  const { warnings } = useWarnings();
  
  return (
    <div>
      <h1>Health: {health?.overall}</h1>
      <ul>
        {warnings.map(w => <li key={w.id}>{w.message}</li>)}
      </ul>
    </div>
  );
}

CLI Usage

# Scan a built site
npx selfopt-cli scan ./dist

# Generate report
npx selfopt-cli scan ./dist -o report.json
npx selfopt-cli report report.json -f markdown

# Compare for regressions
npx selfopt-cli compare baseline.json current.json

Configuration

initSelfOpt({
  mode: 'detect',        // 'detect' | 'optimize'
  debug: false,
  observers: {
    performance: true,
    errors: true,
    resources: true,
    layout: true,
  },
  optimizers: {
    images: true,        // lazy loading
    fonts: true,         // preload hints
    scripts: true,       // preconnect
    preconnect: true,
  },
  seo: true,
  storage: {
    persist: false,
    prefix: 'selfopt',
  },
});

What It Detects

| Category | Signals | |----------|---------| | Performance | LCP, CLS, INP, FCP, TTFB degradation | | Stability | JS errors, unhandled rejections | | Resources | Failed loads, broken links, third-party failures | | Layout | Layout shifts, images without dimensions | | SEO | Missing title, meta description, alt text, Open Graph |

What It Optimizes (in optimize mode)

| Optimization | Safety | |--------------|--------| | Image lazy loading | ✅ Safe — only below-fold images | | Font preload hints | ✅ Safe — adds resource hints | | Preconnect hints | ✅ Safe — adds connection hints | | Script defer warnings | ⚠️ Detection only — no runtime changes |

Philosophy

Websites don't suddenly fail. They slowly decay.

This project exists to observe, explain, and gently prevent that decay — without hype, surveillance, or lock-in.

Development

# Install dependencies
npm install

# Build all packages
npm run build

# Run tests
npm test

License

MIT © 2024