The Problem
Modern web projects still generate code that relies on legacy APIs, polyfills, and bulky libraries. Training data for LLMs is saturated with these patterns, so coding agents frequently suggest outdated solutions. Developers need a lightweight, token‑efficient reference that natively understands the latest browser capabilities and can be queried or injected into an agent’s prompt.
What This Does
The repository packages a CLI tool, modern‑web‑guidance, that exposes a small set of commands:
install– sets up the skill in a project, creating amodern-web-guidanceentry inpackage.json.search <term>– looks up relevant guides in the localskills/tree and prints concise snippets.retrieve <id>– returns a specific guide by its identifier.legacy-scan <dir>– walks a codebase, matches patterns against the guide corpus, and emits a report of legacy practices that can be modernized.
All guides live under skills/modern-web-guidance/ as Markdown files. The CLI loads these files at runtime and serves them as plain text; no external network calls are made.
How It Is Wired
Entry point – package.json defines a binary:
"bin": { "modern-web-guidance": "src/index.js" }
src/index.js initializes the commander parser, registers subcommands located in src/commands/*.js, and forwards control to the chosen command handler.
Command flow – For example, legacy-scan follows:
src/commands/legacy-scan.jsreceives the directory argument.- It calls
src/lib/scanner.js, which uses Node’sfsandpathto enumerate files. - For each file,
scanner.jsloads the guide corpus (skills/modern-web-guidance/*.md) and applies a simple regex‑based pattern matcher defined insrc/lib/patterns.js. - Results are formatted by
src/lib/reporter.jsand written to stdout.
The only external dependencies are the Node standard library and the commander package declared in package.json. No network or database writes occur; the tool is purely read‑only against the local filesystem.
Responsibility map
| File | Responsibility |
|---|---|
src/index.js | CLI bootstrap, command registration |
src/commands/*.js | Individual subcommand logic |
src/lib/scanner.js | File traversal & pattern matching |
src/lib/patterns.js | Regex definitions for legacy API detection |
src/lib/reporter.js | Output formatting |
skills/modern-web-guidance/*.md | Guideline content |
The graph is acyclic; the only hub is src/index.js, which delegates to command modules.
How To Use It
Setup
# From a fresh project
npm init -y
npm install modern-web-guidance@latest
Configuration
No environment variables are required. The only configuration file is skills/modern-web-guidance/ where new guides can be added.
Running it
# Search for a phrase
npx modern-web-guidance search "animate a dialog modal backdrop"
# Retrieve a guide by ID
npx modern-web-guidance retrieve "animate-to-from-top-layer"
# Scan a codebase
npx modern-web-guidance legacy-scan .
The CLI outputs plain text; redirect or pipe as needed.
Real‑World Use
A CI job could invoke legacy-scan and fail if legacy patterns exceed a threshold:
steps:
- uses: actions/checkout@v4
- name: Install guidance
run: npm install modern-web-guidance@latest
- name: Legacy scan
run: npx modern-web-guidance legacy-scan . > legacy-report.txt
- name: Fail on legacy
if: ${{ steps.legacy-scan.outcome != 'success' }}
run: exit 1
The report can be reviewed manually or fed into an issue template.
Code Health & Issues
- Low – No lockfile (
package-lock.jsonorpnpm-lock.yaml) → builds may differ across environments. - Medium – No CI/CD pipeline (
.github/workflowsmissing) → no automated test or build gate. - Low – Only three unit tests; coverage for CLI commands and scanner logic is minimal.
Other than these, the repository contains a license and CI‑friendly README. All files are under version control, and the guide corpus is entirely static.
The Bottom Line
Modern‑web‑guidance is a lean, npm‑installable tool that bridges the gap between legacy code patterns and modern browser APIs. Its design keeps the skill corpus local and versioned, making it easy to embed in existing developer workflows or agents. The lack of a lockfile and CI pipeline are the main maintenance risks; adding a lockfile and a basic GitHub Actions workflow would strengthen reliability. Teams building LLM‑based coding assistants or automated refactoring pipelines would benefit most.