Building a Claude Code plugin with zero npm dependencies

Max Schottke — Fri, 22 May 2026 08:29:44 +0000

Building a Claude Code plugin with zero npm dependencies

I shipped a Claude Code plugin last week called seo-survival-kit. It generates publication-quality SEO outreach PDFs by pulling data from three APIs (Sistrix, DataForSEO, Google PageSpeed Insights) and rendering everything through headless Chrome. The whole thing is four Node.js files plus a small shared library, around 1000 lines of source. No package.json. No node_modules. No Puppeteer.

This is the design log. Why no dependencies, how the Chrome render works without Puppeteer, what I learned about Claude Code plugin security, and the two bugs I only caught after running against a real domain.

The dependency rule

Every npm dependency in a Claude Code plugin is a supply-chain attack surface. The plugin runs in the user's shell with their privileges. One compromised transitive dep, one tampered postinstall script, and you've shipped a credential-stealer to everyone who installed your plugin.

I made it a hard rule for this project. The plugin runs on raw Node 20 with whatever ships in node:fs, node:path, node:child_process, node:os. No package.json, so no install step, so no npm to compromise. The user reads a thousand lines of source and that's the full attack surface they're trusting.

This sounds restrictive in 2026. Mostly it wasn't.

Replacing Puppeteer with three Chrome flags

Most "render HTML to PDF" pipelines reach for Puppeteer, which pulls down 100MB of Chromium plus a couple of dependency chains. I needed two things from Puppeteer: launch Chrome, give it an HTML file, get a PDF. Both are command-line flags.

const { spawnSync } = require('node:child_process');

const result = spawnSync(CHROME_PATH, [
  '--headless=new',
  '--disable-gpu',
  '--no-default-browser-check',
  '--no-first-run',
  `--user-data-dir=${path.join(runDir, 'chrome-profile')}`,
  `--print-to-pdf=${pdfPath}`,
  '--no-pdf-header-footer',
  `file://${tmpHtmlPath}`,
], { stdio: 'pipe', shell: false, timeout: 120_000 });

A few things in this snippet matter beyond "I called Chrome."

The first version of this code used execSync with a string command. That made CHROME_PATH (which I read from env to allow override) a shell-injection vector. Anyone who could set the env var could append a semicolon and arbitrary shell. Switching to spawnSync with an argv array kills that. Node passes each array entry to the OS as a literal argv element. Quoting, $VAR expansion, semicolons, backticks all become impossible.

The --user-data-dir flag points at an isolated directory I create per run with fs.mkdtempSync. Without it, headless Chrome opens with the user's real profile. Your cookies, extensions, saved passwords are all in scope during the render. With the isolated dir, none of that loads.

The HTML carries a Content-Security-Policy meta tag. Chrome rendering file:// URLs has read access to the local filesystem. If a malicious string slips into my HTML and emits <iframe src="file:///etc/passwd">, Chrome will obediently render the file's contents into the iframe, and that ends up in my PDF. The fix is a CSP that refuses to load iframes and external resources:

<meta http-equiv="Content-Security-Policy"
      content="default-src 'none'; style-src 'unsafe-inline';
               img-src data:; font-src data:;
               base-uri 'none'; form-action 'none';
               frame-src 'none'; object-src 'none'">

Even if my HTML escaper has a bug, Chrome refuses to load the iframe. Two layers of defense for the cost of one meta tag.

Path validation everywhere, not just one place

The plugin reads an audit-config.json with target entries like {"slug": "client-a", "domain": "example.com"}. The slug becomes part of every cache filename and intermediate path. So what happens if slug equals "../../etc/foo"?

The check is one regex:

function safeSlug(s) {
  if (typeof s !== 'string' || !/^[a-z0-9][a-z0-9_-]{0,63}$/i.test(s)) {
    throw new Error(`Unsafe slug rejected: ${JSON.stringify(s)}`);
  }
  return s;
}

The trick is calling it at every file boundary, not just one. My first version validated only in the PDF-render script. The security review caught that the two upstream scripts (the extract and the on-page parser) accepted raw slugs straight into path interpolations. A crafted config could write files outside the cache dir. After that I pulled safeSlug into a shared lib/safe.js and called it at every config load.

/tmp is a trap on macOS

The first version cached intermediate JSON files in /tmp. The pattern was /tmp/seo-${slug}-summary.json. On macOS, /tmp is world-writable (mode 1777). If you write to a predictable path there and another local process pre-creates that path as a symlink to ~/.ssh/authorized_keys, your fs.writeFileSync follows the symlink and overwrites the target. Done.

I moved cache to ~/.cache/seo-rescue/, mode 0700, refused if the path itself is a symlink:

function getCacheDir() {
  const dir = process.env.SEO_CACHE_DIR ||
              path.join(os.homedir(), '.cache', 'seo-rescue');
  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
  try { fs.chmodSync(dir, 0o700); } catch {}
  if (fs.lstatSync(dir).isSymbolicLink()) {
    throw new Error(`SEO_CACHE_DIR must not be a symlink: ${dir}`);
  }
  return dir;
}

For intermediate HTML that Chrome reads, I create a per-run mkdtempSync directory under $TMPDIR, write the HTML there, render, then rmSync it in a finally block.

Two bugs I missed until live-testing

I shipped v0.2.0 after a clean smoke test with mock data. Then I ran the pipeline against a real domain. Two things broke.

The position distribution chart in the PDF was always nearly 100% Top 3. The DataForSEO ranked_keywords call used limit:100 with order_by:rank_group asc. So the 100 returned items were exactly the 100 best-ranking keywords. The chart was meant to show how keywords spread across Top 3, 4-10, 11-20, 21-50, 51-100. With that fetch it was lying. The fix was limit:1000 with order_by:search_volume desc, then re-sort locally for the Top-Keywords table. Real distribution went from { t3:100, t10:0, t20:0, t50:0, t100:0 } to { t3:101, t10:226, t20:203, t50:376, t100:94 }.

The target domain was also listed as its own #1 competitor. DataForSEO's competitors_domain endpoint returns the target with 100% SERP overlap as the first item. Trivial to filter, painful to discover via embarrassed re-read of the generated PDF.

Neither bug was caught by my mock tests because the mocks returned clean, target-free, evenly-distributed data. There's a useful lesson in that, but mostly it's just "run against real data sooner."

Shipping a wrong manifest path for two releases

A separate kind of bug I want to mention because it cost me a release cycle. The first two tagged releases (v0.2.0 and v0.2.1) had the plugin manifest at plugins/seo-rescue/plugin.json. Claude Code expects it at plugins/seo-rescue/.claude-plugin/plugin.json. The plugin was never installable from the published marketplace.json. The marketplace.json metadata pointed to the plugin folder. The folder existed. The manifest existed. Just not at the path the loader checks first.

Anthropic ships claude plugin validate as a CLI command. Running it would have caught the path issue immediately. I just hadn't run it. v0.2.2 is the first release where /plugin install actually works, which is humbling to write in release notes.

The lesson is to run the platform's validator before tagging. Specifically:

claude plugin validate plugins/seo-rescue
claude plugin validate .  # validates marketplace.json

Both passing is now a release prerequisite for this project.

The skills are domain knowledge, not just code

This is the part Claude Code's plugin model enables that I didn't expect to use as much as I did. Two of the six skills in seo-survival-kit are pure Markdown. No scripts, no automation, just frameworks. The post-core-update-recovery skill is 152 lines of Markdown that encode a diagnose decision tree and a 4-phase recovery plan I built from one extended real recovery case. Claude reads it, applies it to whatever specific situation the user describes, and produces tailored output.

You're not shipping code, you're shipping a way of thinking about a problem. The code is the optional automation around it. That separation actually makes the plugin more useful for SEO consultants who want to read the framework without installing anything.

Repo and install

Tag-pinned install is the recommended default in the README, to protect installers from any future maintainer-account compromise. v0.2.2 is the first installable release:

/plugin marketplace add maxschottke-spec/seo-survival-kit#v0.2.2
/plugin install seo-rescue@seo-survival-kit

Repo: https://github.com/maxschottke-spec/seo-survival-kit
License: MIT
Source: ~1000 lines across four scripts + lib/safe.js
Runtime dependencies: zero

DEV Community: Max Schottke

Building a Claude Code plugin with zero npm dependencies

Building a Claude Code plugin with zero npm dependencies

The dependency rule

Replacing Puppeteer with three Chrome flags

Path validation everywhere, not just one place

/tmp is a trap on macOS

Two bugs I missed until live-testing

Shipping a wrong manifest path for two releases

The skills are domain knowledge, not just code

Repo and install