npm package: @lxgicstudios/head-check
Description: Audit HTML head tags for missing elements, wrong order, and SEO issues. Check charset, viewport, title, meta ordering. Detect render-blocking scripts and missing preconnect hints. Auto-fix with --fix flag. Zero dependencies.
Author: LXGIC Studios
Latest version: 1.0.0

# @lxgicstudios/head-check

[![npm version](https://img.shields.io/npm/v/@lxgicstudios/head-check.svg)](https://www.npmjs.com/package/@lxgicstudios/head-check)
[![license](https://img.shields.io/npm/l/@lxgicstudios/head-check.svg)](https://github.com/lxgicstudios/head-check/blob/main/LICENSE)
[![node](https://img.shields.io/node/v/@lxgicstudios/head-check.svg)](https://nodejs.org)

Audit your HTML `<head>` tag for missing elements, wrong ordering, and SEO issues. Checks charset, viewport, title, meta description, Open Graph tags, Twitter Cards, favicon, render-blocking scripts, and preconnect hints. Use `--fix` to get a corrected version.

**Zero dependencies.** Just Node.js built-ins.

## Install

```bash
npm install -g @lxgicstudios/head-check
```

Or run directly with npx:

```bash
npx @lxgicstudios/head-check https://example.com
```

## Usage

```bash
# Audit a live URL
head-check https://example.com

# Audit a local HTML file
head-check index.html

# Get a corrected head section
head-check https://example.com --fix

# JSON output for CI/CD
head-check https://example.com --json
```

## Features

- Checks charset declaration and positioning
- Validates viewport meta tag configuration
- Audits title length (30-60 chars recommended)
- Checks meta description length (120-160 chars recommended)
- Verifies canonical link tag
- Validates Open Graph tags (og:title, og:description, og:image, og:url)
- Checks Twitter Card meta tags
- Detects missing favicon declaration
- Flags render-blocking scripts without async/defer
- Suggests preconnect hints for external domains
- Checks html lang attribute
- Detects duplicate tags
- Scores your head section out of 100
- Auto-fix mode reorders and adds missing tags
- Works with live URLs and local HTML files
- Zero external dependencies

## Options

| Option | Description | Default |
|--------|-------------|---------|
| `--fix` | Output a corrected `<head>` section | `false` |
| `--json` | Output results as JSON | `false` |
| `--timeout <ms>` | Request timeout in milliseconds | `10000` |
| `--help` | Show help message | |

## What It Checks

| Check | Severity | Description |
|-------|----------|-------------|
| Charset | Error | Must be present and first in head |
| Viewport | Error | Required for mobile rendering |
| Title | Error | Required, 30-60 chars recommended |
| Description | Warning | 120-160 chars recommended |
| Canonical | Warning | Prevents duplicate content issues |
| Open Graph | Warning | Needed for social sharing |
| Twitter Card | Info | Falls back to OG but explicit is better |
| Favicon | Warning | Declare it or browsers guess |
| Blocking Scripts | Warning | Use async or defer |
| Preconnect | Info | Speed up third-party connections |
| Language | Warning | Set lang on html tag |

## Example Output

```
head-check v1.0.0

Fetching https://example.com...

Score: 85/100

Charset
  ✔ charset="utf-8" is present and correctly positioned.

Viewport
  ✔ Viewport is properly configured.

Title
  ✔ Title is good (42 chars): "Example Domain - Your Site Title"

Description
  ⚠ Missing meta description. Search engines may generate one.

Open Graph
  ⚠ Missing OG tags: og:title, og:description, og:image, og:url.

Summary: 0 errors | 2 warnings | 3 passed
```

## License

MIT - [LXGIC Studios](https://lxgicstudios.com)