seopilot

v0.1.7

Published

8 days ago

Herramienta CLI para análisis SEO en sitios estáticos.

0High
0Medium
0Low

estanisalpre

agriestanis

seo html cli analyzer static-site

✈️ SEOpilot

Una herramienta CLI ligera para detectar errores SEO en sitios web estáticos de forma automática, simple y efectiva.

🚀 ¿Qué es SEOpilot?

SEOpilot es un analizador SEO para sitios generados con frameworks como React, Astro, Vue, Next.js (modo export), Vite, entre otros. Escanea archivos HTML y te reporta errores comunes de SEO como:

Múltiples etiquetas <h1>
Falta de <title> o <meta name="description">
Imágenes sin atributo alt
Falta de lang en la etiqueta <html>

Ideal para proyectos estáticos y flujos de CI/CD donde el SEO importa desde el principio.

🧪 Características

✅ Fácil de usar: npx seopilot
✅ Soporte para --verbose, --json, --limit, --fail-on-error
✅ Análisis automático de Core Web Vitals con Lighthouse (LCP, FID, CLS, TBT, FCP, score)
✅ Recomendaciones automáticas según resultados de Lighthouse
✅ Funciona en cualquier framework moderno
✅ Puede integrarse en CI (GitHub Actions, etc.)
✅ Salida clara y útil para humanos o máquinas

🚦 Análisis Lighthouse y Core Web Vitals

SEOpilot ejecuta automáticamente Lighthouse sobre cualquier URL pública que le pases como argumento. Obtendrás métricas de Core Web Vitals y recomendaciones automáticas para mejorar el rendimiento y la experiencia de usuario.

Ejemplo de uso

npx seopilot https://www.tusitio.com

Salida esperada

🚦 Ejecutando Lighthouse para https://www.tusitio.com...

┌───────────────────────────────┐
│ Core Web Vitals:              │
│   lcp: '2.1 s',               │
│   fid: '30 ms',               │
│   cls: '0.01',                │
│   tbt: '120 ms',              │
│   fcp: '1.1 s',               │
│   score: 0.98                 │
└───────────────────────────────┘

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ 🔎 Recomendaciones Lighthouse:┃
┃ ✅ ¡Excelente! Tus métricas   ┃
┃ Core Web Vitals están dentro  ┃
┃ de los valores recomendados.  ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

Si alguna métrica está fuera de los valores recomendados, SEOpilot te dará sugerencias claras para mejorar tu sitio.

📦 Instalación

Opción 1: Uso directo con `npx`

npx seopilot

Opción 2: Instalar como dependencia

npm i -D seopilot

Luego, en tu package.json:

"scripts": {
  "seo": "seopilot"
}

📁 Estructura recomendada

📦 tu-proyecto/
├─ dist/                  ← carpeta de salida (HTMLs generados)
├─ src/
├─ .github/workflows/    ← integración con CI
└─ ...

🧰 Comandos y Flags

🔍 Análisis básico

npx seopilot

📍 Especificar carpeta

npx seopilot --path src/testing

🗣️ Modo verbose (por archivo)

npx seopilot --verbose

🧪 Modo JSON (para máquinas)

npx seopilot --json

🛑 Falla si hay errores (para CI)

npx seopilot --fail-on-error

⏱️ Limitar cantidad de archivos analizados

npx seopilot --limit 20

🔀 Combinado

npx seopilot --path src/testing --verbose --limit 10 --fail-on-error

✅ Salida esperada

✅ Modo normal

📊 Resumen de errores:

❌ Imagen sin alt: hero.jpg — 2 ocurrencias
❌ Falta <meta name="description"> — 1 ocurrencias

✅ Modo verbose

📄 dist/index.html
   ❌ Imagen sin alt: hero.jpg
   ❌ Falta <title>

✅ Modo JSON

{
  "totalFilesScanned": 5,
  "errors": [
    {
      "file": "dist/index.html",
      "messages": ["Falta <title>", "Imagen sin alt: hero.jpg"]
    }
  ],
  "summary": {
    "Falta <title>": 1,
    "Imagen sin alt: hero.jpg": 2
  }
}

🤖 Integración con GitHub Actions

`.github/workflows/seo-check.yml`

name: SEO Check

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  seo:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v3

      - name: Install dependencies
        run: npm install

      - name: Build project
        run: npm run build

      - name: Run SEOpilot
        run: npx seopilot --fail-on-error

🧪 Ejemplo de archivos HTML para testeo

Colocá estos archivos en una carpeta src/testing/ y corré:

npx seopilot --path src/testing --verbose

📄 `correct.html`

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Test</title>
    <meta name="description" content="Página correcta" />
  </head>
  <body>
    <h1>Hola mundo</h1>
    <img src="logo.png" alt="Logo" />
  </body>
</html>

📄 `no-title.html`

<html lang="es">
  <head></head>
  <body>
    <h1>Falta título</h1>
  </body>
</html>

📄 `multiple-h1.html`

<html lang="es">
  <head>
    <title>Error</title>
  </head>
  <body>
    <h1>Uno</h1>
    <h1>Dos</h1>
  </body>
</html>

💡 Roadmap

[x] Soporte CLI completo
[x] Modo JSON
[x] CI con GitHub Actions
[ ] Configuración por archivo seopilot.config.ts
[ ] Reglas personalizadas
[ ] Modo web/interfaz gráfica
[ ] Autocorrección básica (opcional)

💬 Contribuciones

¡Son bienvenidas! Puedes:

Abrir issues
Sugerir nuevas reglas SEO
Proponer mejoras de UX
Enviar PRs

🧠 Autor

Creado por @estanisalpre — para que ningún proyecto se quede sin SEO por descuido.

🧭 Licencia

MIT — Usá, modificá, compartí. Pero no pongas <h1> múltiples o SEOpilot te va a encontrar 😈