serpx-seo-meta-check 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SerpX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+# SerpX SEO Meta Check
+
+A fast, lightweight and zero-dependency command-line SEO checker for inspecting essential on-page and technical SEO metadata.
+
+SerpX SEO Meta Check is built by [SerpX](https://serpx.ai/), an AI-powered SEO platform for website analysis, keyword research, competitor intelligence and content optimization.
+
+## What It Checks
+
+The package analyzes a public webpage and reports:
+
+- Page title
+- Title length
+- Meta description
+- Meta description length
+- Canonical URL
+- Meta robots directives
+- Noindex detection
+- HTML language
+- Viewport configuration
+- H1 count and content
+- H2 count
+- H3 count
+- Approximate visible word count
+- Open Graph title
+- Open Graph description
+- Open Graph image
+- Twitter Card metadata
+- JSON-LD structured data count
+- Basic SEO score
+
+## Installation
+
+Install globally:
+
+```bash
+npm install -g serpx-seo-meta-check
+```
+
+Then analyze a page:
+
+```bash
+serpx-seo-check https://example.com
+```
+
+You can also run the package directly:
+
+```bash
+npx serpx-seo-meta-check https://example.com
+```
+
+## Example Output
+
+```text
+SerpX SEO Meta Check
+========================================
+Final URL:              https://example.com/
+Basic SEO score:        45/100
+
+Core Metadata
+----------------------------------------
+Title:                  Example Domain
+Title length:           14
+Meta description:       Not found
+Description length:     0
+Canonical:              Not found
+Robots:                 Not found
+Noindex:                No
+
+Page Structure
+----------------------------------------
+HTML lang:              en
+Viewport:               Found
+H1 count:               1
+H1:                     Example Domain
+H2 count:               0
+H3 count:               0
+Approx. word count:     28
+```
+
+## Why Use SerpX SEO Meta Check?
+
+Small technical SEO mistakes can create large search visibility problems.
+
+A missing canonical tag, an accidental noindex directive, weak metadata or incorrect heading structure can affect how search engines understand a webpage.
+
+SerpX SEO Meta Check provides a fast first-pass SEO inspection directly from the terminal.
+
+For deeper website analysis, SEO audits, keyword intelligence and AI-powered optimization, visit the [SerpX AI SEO Platform](https://serpx.ai/).
+
+## Competitor Keyword Research
+
+On-page metadata is only one part of a complete SEO strategy.
+
+Competitive keyword research can reveal the search queries competing websites rank for, identify content gaps and uncover new organic search opportunities.
+
+Read the detailed SerpX guide:
+
+[Competitor Keyword Research: How to Find and Analyze Competitor Keywords](https://serpx.ai/blog/competitor-keyword-research)
+
+The guide explains practical competitor keyword research workflows and how competitive search data can be converted into an actionable SEO strategy.
+
+## Programmatic Usage
+
+The analyzer can also be imported into a Node.js project:
+
+```js
+import { analyzeHtml } from "serpx-seo-meta-check";
+
+const html = `
+<!doctype html>
+<html lang="en">
+<head>
+  <title>Example Page</title>
+  <meta
+    name="description"
+    content="Example page description"
+  >
+  <link
+    rel="canonical"
+    href="https://example.com/"
+  >
+</head>
+<body>
+  <h1>Example Page</h1>
+</body>
+</html>
+`;
+
+const result = analyzeHtml(html);
+
+console.log(result);
+```
+
+## SEO Resources
+
+Useful SerpX resources:
+
+- [SerpX AI SEO Platform](https://serpx.ai/)
+- [Competitor Keyword Research Guide](https://serpx.ai/blog/competitor-keyword-research)
+
+## Requirements
+
+- Node.js 18 or newer
+- Public HTTP or HTTPS URL
+
+The package does not require third-party npm dependencies.
+
+## Privacy
+
+The CLI requests only the URL supplied by the user in order to analyze its publicly available HTML.
+
+It does not require:
+
+- A SerpX account
+- A SerpX API key
+- Analytics configuration
+- Tracking software
+
+## Limitations
+
+This package performs static analysis of the HTML returned by the target server.
+
+Websites that insert SEO metadata only after client-side JavaScript execution may require browser rendering for a complete audit.
+
+The SEO score is intended as a quick diagnostic indicator and is not a search-engine ranking score.
+
+## About SerpX
+
+[SerpX](https://serpx.ai/) is an AI-powered SEO and content optimization platform built for website owners, developers, marketers and SEO professionals.
+
+SerpX provides tools for website analysis, technical SEO, content optimization, competitor intelligence and keyword research.
+
+For competitive organic search analysis, read the [SerpX competitor keyword research guide](https://serpx.ai/blog/competitor-keyword-research).
+
+## Links
+
+Website:
+
+https://serpx.ai/
+
+Competitor Keyword Research:
+
+https://serpx.ai/blog/competitor-keyword-research
+
+## License
+
+MIT

package/cli.js

@@ -0,0 +1,287 @@
+#!/usr/bin/env node
+
+import { analyzeHtml } from "./index.js";
+
+const args = process.argv.slice(2);
+
+function showHelp() {
+  console.log(`
+SerpX SEO Meta Check
+
+Fast command-line on-page SEO metadata analyzer.
+
+Usage:
+  serpx-seo-check <url>
+
+Examples:
+  serpx-seo-check https://example.com
+  npx serpx-seo-meta-check https://example.com
+
+Checks:
+  - Page title
+  - Title length
+  - Meta description
+  - Meta description length
+  - Canonical URL
+  - Robots directives
+  - Noindex status
+  - H1 headings
+  - H2 and H3 counts
+  - HTML language
+  - Viewport
+  - Open Graph metadata
+  - Twitter Card
+  - JSON-LD structured data
+  - Approximate visible word count
+  - Basic SEO score
+
+More SEO tools:
+  https://serpx.ai/
+
+SEO research:
+  https://serpx.ai/blog/competitor-keyword-research
+`);
+}
+
+if (
+  args.length === 0 ||
+  args.includes("--help") ||
+  args.includes("-h")
+) {
+  showHelp();
+  process.exit(0);
+}
+
+if (
+  args.includes("--version") ||
+  args.includes("-v")
+) {
+  console.log("1.0.0");
+  process.exit(0);
+}
+
+const input = args[0];
+
+let parsedUrl;
+
+try {
+  parsedUrl = new URL(input);
+} catch {
+  console.error("Error: Invalid URL.");
+  console.error(
+    "Example: serpx-seo-check https://example.com"
+  );
+  process.exit(1);
+}
+
+if (
+  !["http:", "https:"].includes(
+    parsedUrl.protocol
+  )
+) {
+  console.error(
+    "Error: Only HTTP and HTTPS URLs are supported."
+  );
+  process.exit(1);
+}
+
+try {
+  const response = await fetch(parsedUrl, {
+    redirect: "follow",
+    signal: AbortSignal.timeout(15000),
+    headers: {
+      "user-agent":
+        "SerpX-SEO-Meta-Check/1.0 (+https://serpx.ai/)",
+      "accept":
+        "text/html,application/xhtml+xml"
+    }
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `HTTP ${response.status} ${response.statusText}`
+    );
+  }
+
+  const contentType =
+    response.headers.get("content-type") || "";
+
+  if (
+    contentType &&
+    !contentType.includes("text/html") &&
+    !contentType.includes(
+      "application/xhtml+xml"
+    )
+  ) {
+    throw new Error(
+      `Unsupported content type: ${contentType}`
+    );
+  }
+
+  const html = await response.text();
+
+  const result = analyzeHtml(html);
+
+  console.log("");
+  console.log("SerpX SEO Meta Check");
+  console.log(
+    "========================================"
+  );
+
+  console.log(
+    `Final URL:              ${response.url}`
+  );
+
+  console.log(
+    `Basic SEO score:        ${result.score}/100`
+  );
+
+  console.log("");
+  console.log("Core Metadata");
+  console.log(
+    "----------------------------------------"
+  );
+
+  console.log(
+    `Title:                  ${
+      result.title || "Not found"
+    }`
+  );
+
+  console.log(
+    `Title length:           ${result.titleLength}`
+  );
+
+  console.log(
+    `Meta description:       ${
+      result.metaDescription || "Not found"
+    }`
+  );
+
+  console.log(
+    `Description length:     ${result.metaDescriptionLength}`
+  );
+
+  console.log(
+    `Canonical:              ${
+      result.canonical || "Not found"
+    }`
+  );
+
+  console.log(
+    `Robots:                 ${
+      result.robots || "Not found"
+    }`
+  );
+
+  console.log(
+    `Noindex:                ${
+      result.noindex ? "Yes" : "No"
+    }`
+  );
+
+  console.log("");
+  console.log("Page Structure");
+  console.log(
+    "----------------------------------------"
+  );
+
+  console.log(
+    `HTML lang:              ${
+      result.lang || "Not found"
+    }`
+  );
+
+  console.log(
+    `Viewport:               ${
+      result.viewport ? "Found" : "Not found"
+    }`
+  );
+
+  console.log(
+    `H1 count:               ${result.h1Count}`
+  );
+
+  console.log(
+    `H1:                     ${
+      result.h1.join(" | ") || "Not found"
+    }`
+  );
+
+  console.log(
+    `H2 count:               ${result.h2Count}`
+  );
+
+  console.log(
+    `H3 count:               ${result.h3Count}`
+  );
+
+  console.log(
+    `Approx. word count:     ${result.wordCount}`
+  );
+
+  console.log("");
+  console.log(
+    "Social & Structured Data"
+  );
+
+  console.log(
+    "----------------------------------------"
+  );
+
+  console.log(
+    `Open Graph title:       ${
+      result.ogTitle || "Not found"
+    }`
+  );
+
+  console.log(
+    `Open Graph description: ${
+      result.ogDescription || "Not found"
+    }`
+  );
+
+  console.log(
+    `Open Graph image:       ${
+      result.ogImage || "Not found"
+    }`
+  );
+
+  console.log(
+    `Twitter Card:           ${
+      result.twitterCard || "Not found"
+    }`
+  );
+
+  console.log(
+    `JSON-LD blocks:         ${result.jsonLdCount}`
+  );
+
+  console.log("");
+  console.log("More SEO tools:");
+  console.log("https://serpx.ai/");
+
+  console.log("");
+  console.log(
+    "Competitor keyword research:"
+  );
+
+  console.log(
+    "https://serpx.ai/blog/competitor-keyword-research"
+  );
+
+  console.log("");
+
+} catch (error) {
+  if (error?.name === "TimeoutError") {
+    console.error(
+      "Failed to analyze URL: Request timed out."
+    );
+  } else {
+    console.error(
+      `Failed to analyze URL: ${error.message}`
+    );
+  }
+
+  process.exit(1);
+}

package/index.js

@@ -0,0 +1,294 @@
+function decodeHtml(value = "") {
+  return value
+    .replace(/&#(\d+);/g, (_, code) =>
+      String.fromCodePoint(Number(code))
+    )
+    .replace(/&#x([0-9a-f]+);/gi, (_, code) =>
+      String.fromCodePoint(parseInt(code, 16))
+    )
+    .replace(/ /gi, " ")
+    .replace(/&/gi, "&")
+    .replace(/"/gi, '"')
+    .replace(/'/gi, "'")
+    .replace(/&lt;/gi, "<")
+    .replace(/&gt;/gi, ">");
+}
+
+function cleanText(value = "") {
+  return decodeHtml(
+    value
+      .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, " ")
+      .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, " ")
+      .replace(/<noscript\b[^>]*>[\s\S]*?<\/noscript>/gi, " ")
+      .replace(/<svg\b[^>]*>[\s\S]*?<\/svg>/gi, " ")
+      .replace(/<template\b[^>]*>[\s\S]*?<\/template>/gi, " ")
+      .replace(/<!--[\s\S]*?-->/g, " ")
+      .replace(/<[^>]+>/g, " ")
+  )
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function getAttributes(tag = "") {
+  const attributes = {};
+
+  const pattern =
+    /([^\s=/>]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
+
+  let match;
+
+  while ((match = pattern.exec(tag)) !== null) {
+    const key = match[1].toLowerCase();
+
+    if (key.startsWith("<")) {
+      continue;
+    }
+
+    attributes[key] = decodeHtml(
+      (match[2] ?? match[3] ?? match[4] ?? "").trim()
+    );
+  }
+
+  return attributes;
+}
+
+function findMeta(html, attribute, expectedValue) {
+  const tags = html.match(/<meta\b[^>]*>/gi) || [];
+
+  for (const tag of tags) {
+    const attrs = getAttributes(tag);
+
+    if (
+      attrs[attribute] &&
+      attrs[attribute].toLowerCase() === expectedValue.toLowerCase()
+    ) {
+      return attrs.content || "";
+    }
+  }
+
+  return "";
+}
+
+function findLink(html, relValue) {
+  const tags = html.match(/<link\b[^>]*>/gi) || [];
+
+  for (const tag of tags) {
+    const attrs = getAttributes(tag);
+
+    const rel = (attrs.rel || "")
+      .toLowerCase()
+      .split(/\s+/)
+      .filter(Boolean);
+
+    if (rel.includes(relValue.toLowerCase())) {
+      return attrs.href || "";
+    }
+  }
+
+  return "";
+}
+
+function findHtmlLang(html) {
+  const match = html.match(/<html\b[^>]*>/i);
+
+  if (!match) {
+    return "";
+  }
+
+  return getAttributes(match[0]).lang || "";
+}
+
+function getTitle(html) {
+  const match = html.match(
+    /<title\b[^>]*>([\s\S]*?)<\/title>/i
+  );
+
+  return match ? cleanText(match[1]) : "";
+}
+
+function getHeadings(html, level) {
+  let pattern;
+
+  if (level === 1) {
+    pattern = /<h1(?:\s[^>]*)?>([\s\S]*?)<\/h1>/gi;
+  } else if (level === 2) {
+    pattern = /<h2(?:\s[^>]*)?>([\s\S]*?)<\/h2>/gi;
+  } else if (level === 3) {
+    pattern = /<h3(?:\s[^>]*)?>([\s\S]*?)<\/h3>/gi;
+  } else {
+    return [];
+  }
+
+  return [...html.matchAll(pattern)]
+    .map(match => cleanText(match[1]))
+    .filter(Boolean);
+}
+
+
+function countJsonLd(html) {
+  const matches =
+    html.match(
+      /<script\b[^>]*type=["']application\/ld\+json["'][^>]*>[\s\S]*?<\/script>/gi
+    ) || [];
+
+  return matches.length;
+}
+
+function calculateScore(result) {
+  let score = 0;
+
+  if (result.title) {
+    score += 15;
+  }
+
+  if (
+    result.titleLength >= 20 &&
+    result.titleLength <= 65
+  ) {
+    score += 10;
+  }
+
+  if (result.metaDescription) {
+    score += 15;
+  }
+
+  if (
+    result.metaDescriptionLength >= 70 &&
+    result.metaDescriptionLength <= 170
+  ) {
+    score += 10;
+  }
+
+  if (result.canonical) {
+    score += 10;
+  }
+
+  if (result.h1Count === 1) {
+    score += 15;
+  }
+
+  if (result.viewport) {
+    score += 5;
+  }
+
+  if (result.lang) {
+    score += 5;
+  }
+
+  if (!result.noindex) {
+    score += 5;
+  }
+
+  if (result.jsonLdCount > 0) {
+    score += 5;
+  }
+
+  if (result.ogTitle) {
+    score += 3;
+  }
+
+  if (result.ogDescription) {
+    score += 2;
+  }
+
+  return Math.min(score, 100);
+}
+
+export function analyzeHtml(html = "") {
+  if (typeof html !== "string") {
+    throw new TypeError("HTML input must be a string.");
+  }
+
+  const title = getTitle(html);
+
+  const metaDescription =
+    findMeta(html, "name", "description") ||
+    findMeta(html, "property", "description");
+
+  const canonical = findLink(html, "canonical");
+
+  const robots = findMeta(
+    html,
+    "name",
+    "robots"
+  );
+
+  const viewport = findMeta(
+    html,
+    "name",
+    "viewport"
+  );
+
+  const h1 = getHeadings(html, 1);
+  const h2 = getHeadings(html, 2);
+  const h3 = getHeadings(html, 3);
+
+  const visibleText = cleanText(html);
+
+  const wordCount = visibleText
+    ? visibleText.split(/\s+/).filter(Boolean).length
+    : 0;
+
+  const result = {
+    title,
+    titleLength: title.length,
+
+    metaDescription,
+    metaDescriptionLength: metaDescription.length,
+
+    canonical,
+
+    robots,
+    noindex: /\bnoindex\b/i.test(robots),
+
+    lang: findHtmlLang(html),
+
+    viewport,
+
+    h1Count: h1.length,
+    h1,
+
+    h2Count: h2.length,
+    h3Count: h3.length,
+
+    wordCount,
+
+    ogTitle: findMeta(
+      html,
+      "property",
+      "og:title"
+    ),
+
+    ogDescription: findMeta(
+      html,
+      "property",
+      "og:description"
+    ),
+
+    ogImage: findMeta(
+      html,
+      "property",
+      "og:image"
+    ),
+
+    ogUrl: findMeta(
+      html,
+      "property",
+      "og:url"
+    ),
+
+    twitterCard: findMeta(
+      html,
+      "name",
+      "twitter:card"
+    ),
+
+    jsonLdCount: countJsonLd(html)
+  };
+
+  result.score = calculateScore(result);
+
+  return result;
+}
+
+export default analyzeHtml;

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "serpx-seo-meta-check",
+  "version": "1.0.0",
+  "description": "Fast zero-dependency CLI for checking titles, meta descriptions, canonical tags, robots directives, headings and essential on-page SEO metadata.",
+  "homepage": "https://serpx.ai/",
+  "keywords": [
+    "seo",
+    "seo-checker",
+    "seo-audit",
+    "on-page-seo",
+    "technical-seo",
+    "meta-tags",
+    "meta-description",
+    "canonical",
+    "robots",
+    "headings",
+    "h1",
+    "word-count",
+    "seo-cli",
+    "website-audit",
+    "serpx"
+  ],
+  "author": {
+    "name": "SerpX",
+    "url": "https://serpx.ai/"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "bin": {
+    "serpx-seo-check": "cli.js"
+  },
+  "files": [
+    "index.js",
+    "cli.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "check": "node --check index.js && node --check cli.js",
+    "test": "node cli.js https://example.com",
+    "prepublishOnly": "npm run check"
+  }
+}