@chiboycalix/auto-page-titles

v1.0.0

Published

a month ago

CLI tool that automatically generates consistent page titles for Next.js, Vite+React, and CRA projects

0High
0Medium
0Low

chiboycalix

nextjs react vite page-title seo cli auto metadata

auto-page-titles

A production-ready CLI that automatically generates consistent page titles across your React project in the format:

Page Name | App Name

Works seamlessly with Next.js (App Router & Pages Router), Vite + React, and Create React App.

Features

Interactive-first workflow — guided checkboxes, live title editing, before-and-after preview
Framework auto-detection — picks the right strategy automatically
Safe AST editing via ts-morph — never corrupts your JSX/TSX
Idempotent — skips files that already have a title (unless --force)
Automatic backups — creates .auto-page-titles-backup/<timestamp>/ before touching anything
Config file — .auto-page-titles.json tracks processed files, enabling incremental runs
Watch mode — detects newly created page files and prompts you instantly
Dry-run mode — see exactly what would happen without writing a single byte

Quick Start

# Run interactively from your project root
npx auto-page-titles

# Override the app name
npx auto-page-titles --name "Crevoe"

# Preview changes only
npx auto-page-titles --dry-run

# Automatically title all untitled pages (great for CI)
npx auto-page-titles --auto-new

# Force-overwrite existing titles
npx auto-page-titles --force

# Watch for new files
npx auto-page-titles --watch

Interactive Flow

  auto-page-titles v1.0.0
  ─────────────────────────────────────

  ✔ Detected: Next.js (App Router)
  App name: Crevoe

  ✔ Found 6 page file(s) (4 untitled)
  ✔ Backup created at .auto-page-titles-backup/2026-04-05T...

  ✅ app/layout.tsx: set title template → '%s | Crevoe'

  Step 1 — Select files to process

  ? How would you like to select files?
    ❯ Select All New/Untitled  (recommended)
      Select All
      Manual Select
      Skip / Exit

  📁 Next.js App Router
    ✓ app/page.tsx                    → Home          New / Untitled
    ✓ app/about/page.tsx              → About         New / Untitled
    ○ app/dashboard/page.tsx          → Dashboard     Already Titled
    ✓ app/dashboard/settings/page.tsx → Dashboard Settings  New / Untitled

  Step 2 — Confirm / edit page titles

  app/page.tsx
  Suggested: Home | Crevoe
  Enter page title: Home

  app/about/page.tsx
  Suggested: About | Crevoe
  Enter page title: About Us      ← custom!

  ─── Summary ───────────────────────────────

  ✅ app/page.tsx: title → 'Home'
  ✅ app/about/page.tsx: title → 'About Us'
  ✅ app/dashboard/settings/page.tsx: title → 'Dashboard Settings'
  ○ app/dashboard/page.tsx: title already set (use --force to overwrite)

  Updated 3 file(s), skipped 1

CLI Options

| Flag | Description | |---|---| | --name <string> | Override app name (default: from package.json) | | --dry-run | Preview changes; write nothing | | --force | Overwrite existing page titles | | --auto-new | Non-interactive: title untitled pages automatically | | --watch | Watch for new page files after initial run | | --pages-glob <glob> | Custom glob to find page files | | --version | Print version | | --help | Show help |

Framework Support

Next.js App Router

Root layout (app/layout.tsx) — adds/updates metadata.title.template:

export const metadata: import("next").Metadata = {
  title: { template: '%s | Crevoe', default: 'Crevoe' }
};

Page files (app/**/page.tsx) — adds/updates metadata.title:

export const metadata: import("next").Metadata = { title: 'Dashboard Settings' };

Next.js Pages Router

Injects <title> via next/head (adds the import if missing):

import Head from 'next/head';
// …
<Head>
  <title>Dashboard | Crevoe</title>
</Head>

Vite + React / CRA

Inserts a useEffect that sets document.title (adds useEffect import automatically):
```
useEffect(() => {
  document.title = 'Products | Crevoe';
}, []);
```

Title Inference

| File path | Inferred title | |---|---| | app/page.tsx | Home | | app/about/page.tsx | About | | app/dashboard/settings/page.tsx | Dashboard Settings | | src/pages/Products.tsx | Products | | src/pages/admin/users.tsx | Admin Users | | app/blog/[slug]/page.tsx | ⚠ Dynamic Page (skipped, with warning) |

Rules:

Strip file extension and framework segment names (app, src, pages, routes, views)
Remove terminal index / page segment
Root with nothing left → Home
Replace /, -, _ with spaces → Title Case
Dynamic segments [...] → warn and skip

Config File

After the first run, .auto-page-titles.json is created in your project root:

{
  "appName": "Crevoe",
  "processedFiles": [
    "app/about/page.tsx",
    "app/page.tsx"
  ],
  "lastRun": "2026-04-05T12:34:56.000Z"
}

This enables --auto-new and --watch to recognise truly new files on subsequent runs.

Backups

Before writing any file, a backup is created:

.auto-page-titles-backup/
  2026-04-05T12-34-56-000Z/
    app/
      page.tsx
      about/
        page.tsx

Backups are never created in --dry-run mode.

Installation (for publishing)

npm install
npm run build
npm publish

The bin field in package.json registers the auto-page-titles command globally when installed.

Development

npm install
npm run dev   # runs via ts-node (no build step)
npm run build # compiles TypeScript to dist/

License

MIT