Skip to content

[NO-TICKET] Call the JS/Node widget the Patchstack Connector #96

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mariojgt merged 1 commit into from
Sep 25, 2026
Merged

[NO-TICKET] Call the JS/Node widget the Patchstack Connector #96

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions ...Getting Started/Installing Patchstack/installing-on-javascript-node-projects.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,15 +9,15 @@ sidebar:
label: "JavaScript / Node.js projects"
---

Patchstack monitors JavaScript and Node.js applications — not only WordPress sites — through [`@patchstack/connect`](https://www.npmjs.com/package/@patchstack/connect), the official Patchstack connector package, maintained and published by Patchstack on npm under the `@patchstack` organization.
Patchstack monitors JavaScript and Node.js applications — not only WordPress sites — through [`@patchstack/connect`](https://www.npmjs.com/package/@patchstack/connect), the official Patchstack Connect package, maintained and published by Patchstack on npm under the `@patchstack` organization.

- **npm:** https://www.npmjs.com/package/@patchstack/connect
- **Source (MIT-licensed):** https://github.com/patchstack/connect
- **Setup guide:** https://github.com/patchstack/connect/blob/main/GETTING-STARTED.md

## What it does

The connector reads the project's dependency lockfile (`package-lock.json`, `pnpm-lock.yaml`, or `yarn.lock`; bun projects are detected via `node_modules/`) and reports package names and versions to Patchstack, which matches them against its vulnerability database and notifies you when a dependency needs patching. It works with any framework — Next.js, Vite, Nuxt, Remix, SvelteKit, TanStack Start, plain Node — and with npm, pnpm, yarn, and bun.
Connect reads the project's dependency lockfile (`package-lock.json`, `pnpm-lock.yaml`, or `yarn.lock`; bun projects are detected via `node_modules/`) and reports package names and versions to Patchstack, which matches them against its vulnerability database and notifies you when a dependency needs patching. It works with any framework — Next.js, Vite, Nuxt, Remix, SvelteKit, TanStack Start, plain Node — and with npm, pnpm, yarn, and bun.

It sends dependency names and versions only: no source code, no environment variable values, no file paths, no git history.

Expand All @@ -34,7 +34,7 @@ npx --no-install patchstack-connect setup

1. **Scans the lockfile and sends the dependency manifest** (package names and versions) to Patchstack.
2. **Provisions a Patchstack site** on the first run and writes its UUID to `.patchstackrc.json` (commit this file); later runs reuse the existing site instead of creating a duplicate.
3. **Manages the disclosure-widget tag** in the project's root HTML shell (the first of `index.html`, `public/index.html`, or `src/app.html` that exists) — see the widget section below.
3. **Manages the Patchstack Connector tag** in the project's root HTML shell (the first of `index.html`, `public/index.html`, or `src/app.html` that exists) — see the widget section below.
4. **Adds production build integration to `package.json`:** `scan` runs before the build and `mark-build` after it, via `prebuild`/`postbuild` lifecycle hooks (or a direct build chain on bun, which skips npm-style hooks). Existing build commands are preserved, dev scripts are untouched, and `setup` never runs the build itself.
5. **Prints a status checklist** of anything that still needs a manual step, such as framework-specific widget placement.

Expand All @@ -48,7 +48,7 @@ A site that is scanning but not connected is an anonymous record: it is monitore
2. **From the dashboard link.** Open the link `setup`, `scan`, or `status` printed in your browser and sign in.
3. **From the terminal.** `npx @patchstack/connect claim` prints a link to sign in with, then attaches the site to that account.

On a **published** build the connect panel is hidden from ordinary visitors (see [the disclosure widget](#the-disclosure-widget) below). As the owner you can still reach the sign-in there by loading any page with `#patchstack` appended to the URL — `?patchstack` works too.
On a **published** build the connect panel is hidden from ordinary visitors (see [the Patchstack Connector](#the-patchstack-connector) below). As the owner you can still reach the sign-in there by loading any page with `#patchstack` appended to the URL — `?patchstack` works too.

Once the site is connected, the panel never appears again, and the widget shows the public report form instead.

Expand Down Expand Up @@ -80,17 +80,17 @@ The same pieces can be applied individually: `npx @patchstack/connect scan` perf

Run `npx @patchstack/connect guide` at any time for a project-aware checklist of what is present and what is missing, with commands tailored to the project. `npx @patchstack/connect status` re-prints the site UUID and dashboard link.

## The disclosure widget
## The Patchstack Connector

The connector installs Patchstack's **vulnerability disclosure widget** — a floating control that becomes a "Report a vulnerability" button once the site is connected to an account, so anyone who spots an issue can report it straight to you. The widget is a single script tag loading `https://cdn.patchstack.com/patchstack-widget.js`, configured with the site UUID (which is public by design — it ships in client-side HTML and is not a secret). A pre-existing manually placed widget tag is left untouched, and `mark-build` ensures the tag in build output (`dist/`, `build/`, `out/`, `.output/public`) without ever editing source.
Connect installs the **Patchstack Connector**, Patchstack's vulnerability disclosure widget — a floating control that becomes a "Report a vulnerability" button once the site is connected to an account, so anyone who spots an issue can report it straight to you. The widget is a single script tag loading `https://cdn.patchstack.com/patchstack-widget.js`, configured with the site UUID (which is public by design — it ships in client-side HTML and is not a secret). A pre-existing manually placed widget tag is left untouched, and `mark-build` ensures the tag in build output (`dist/`, `build/`, `out/`, `.output/public`) without ever editing source.

Frameworks without a static HTML shell need a one-line placement in the root layout; `guide` prints the exact snippet for the detected framework, and the [widget reference](https://cdn.patchstack.com/llm.html) covers additional patterns.

To run without the widget, set `"widget": false` in `.patchstackrc.json` — this disables all widget management; otherwise the next scan re-adds the tag.

**What the widget shows depends on whether the site is connected to an account.** While it is unclaimed, the widget serves the one-time "Connect this website" panel *instead of* the report button — so on a fresh install the first thing you see is the sign-in, not the floating button. Connect the site and the panel is replaced by the public **Report a vulnerability** button for good. To skip the onboarding entirely and always show the report form, set `data-build-mode="false"` on the script tag.

On a **published** build the connector's `mark-build` hook stamps `window.__PATCHSTACK_PROD__` into the built HTML, which hides the connect panel and the owner "Log in" link from visitors and leaves the report form only. Owners reach the sign-in there with `#patchstack` (or `?patchstack`) appended to any page URL.
On a **published** build Connect's `mark-build` hook stamps `window.__PATCHSTACK_PROD__` into the built HTML, which hides the connect panel and the owner "Log in" link from visitors and leaves the report form only. Owners reach the sign-in there with `#patchstack` (or `?patchstack`) appended to any page URL.

See [Troubleshooting JS / Node.js](/getting-started/installing-patchstack/troubleshooting-javascript-node-projects/) if the widget does not appear at all.

Expand Down Expand Up @@ -121,7 +121,7 @@ Reporting stops immediately. Local removal does not delete the site record on Pa

## Troubleshooting

A widget that never appears, a published site serving an old build, a broken config file, or a connector stuck on an old version are all covered — with copy-paste prompts for AI site builders — in [Troubleshooting JavaScript / Node.js projects](/getting-started/installing-patchstack/troubleshooting-javascript-node-projects/).
A widget that never appears, a published site serving an old build, a broken config file, or a Connect install stuck on an old version are all covered — with copy-paste prompts for AI site builders — in [Troubleshooting JavaScript / Node.js projects](/getting-started/installing-patchstack/troubleshooting-javascript-node-projects/).

## How this relates to host-level npm protection

Expand Down
24 changes: 12 additions & 12 deletions ...ting Started/Installing Patchstack/troubleshooting-javascript-node-projects.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "Troubleshooting JavaScript / Node.js projects"
excerpt: "Fix a disclosure widget that never appears or appears twice, a published build that serves an old integration, a broken config file, or an outdated @patchstack/connect — including prompts to paste into an AI site builder."
excerpt: "Fix a Patchstack Connector that never appears or appears twice, a published build that serves an old integration, a broken config file, or an outdated @patchstack/connect — including prompts to paste into an AI site builder."
hidden: false
createdAt: "Mon Sep 07 2026 00:00:00 GMT+0000 (Coordinated Universal Time)"
updatedAt: "Wed Sep 09 2026 00:00:00 GMT+0000 (Coordinated Universal Time)"
Expand All @@ -11,7 +11,7 @@ sidebar:

import { Steps, Aside } from '@astrojs/starlight/components';

This page covers the problems that come up after connecting a JavaScript or Node.js project with [`@patchstack/connect`](/getting-started/installing-patchstack/installing-on-javascript-node-projects/): a disclosure widget that never appears, a widget that appears twice, a published site still serving an old integration, a build that broke after a config change, a connector stuck on an old version, and an update that will not take because the package manager is holding the release back.
This page covers the problems that come up after connecting a JavaScript or Node.js project with [`@patchstack/connect`](/getting-started/installing-patchstack/installing-on-javascript-node-projects/): a Patchstack Connector that never appears, a widget that appears twice, a published site still serving an old integration, a build that broke after a config change, a Connect install stuck on an old version, and an update that will not take because the package manager is holding the release back.

Every section ends with a **prompt you can paste into your site builder's AI chat**. The prompts are deliberately explicit about proving the result, because builder assistants otherwise tend to report the version they remember, or stop after editing one file.

Expand Down Expand Up @@ -57,7 +57,7 @@ same package manager for every command. Do not create a second lockfile.

## The widget is not visible on my site

The visitor-facing **Report a vulnerability** button does not appear until the site is connected to a Patchstack account. If you installed the connector and never saw it, that is usually the reason rather than a broken install — work through these in order.
The visitor-facing **Report a vulnerability** button does not appear until the site is connected to a Patchstack account. If you installed Connect and never saw it, that is usually the reason rather than a broken install — work through these in order.

<Steps>

Expand Down Expand Up @@ -101,16 +101,16 @@ The visitor-facing **Report a vulnerability** button does not appear until the s
Use this when the widget works in the builder preview but is absent from the published site.

```text
Please diagnose why the Patchstack widget works in preview but is missing from
Please diagnose why the Patchstack Connector works in preview but is missing from
the published site.

1. Use the latest @patchstack/connect release from npm.
2. Confirm the root page contains exactly one connector-managed script from
2. Confirm the root page contains exactly one Connect-managed script from
https://cdn.patchstack.com/patchstack-widget.js with data-site-uuid set from
the public .patchstackrc.json value.
3. Do not read the site UUID from VITE_*, NEXT_PUBLIC_*, or another
environment-only variable.
4. Run the connector setup/scan flow and the complete production build,
4. Run the Connect setup/scan flow and the complete production build,
including mark-build where the project scripts require it.
5. Inspect the generated production output — not only source files — and verify
that the widget script and window.__PATCHSTACK_PROD__ marker are present.
Expand Down Expand Up @@ -147,7 +147,7 @@ Please do not stop at a source-code check; verify the live deployment.
Thank you.
```

## Is this the latest connector version?
## Is this the latest Connect version?

Site builders often resolve `@patchstack/connect` from cached package metadata and land on an older release. Check what npm actually has:

Expand Down Expand Up @@ -195,7 +195,7 @@ Patchstack allows for this. The update notice in your dashboard and in the widge

## The build broke after a config update

The connector uses two config files with different jobs, and mixing them up breaks the build:
Connect uses two config files with different jobs, and mixing them up breaks the build:

| File | Commit it? | Holds |
|------|-----------|-------|
Expand Down Expand Up @@ -225,14 +225,14 @@ Please diagnose and fix the Patchstack build after the config-file update.
Please complete and verify the fix. Thank you.
```

## I see two Patchstack widgets
## I see two Patchstack Connectors

Two shield buttons stacked in the corner, sometimes one opening the owner log-in and the other the report form, mean the widget script ran twice on that page. They often sit on exactly the same pixel, so the second one only shows when a panel opens or the layout shifts.

The widget keeps **one floating launcher per page** on its own:

- A second copy loaded by the **same document** is ignored, with a `[PatchstackWidget]` warning in the browser console.
- A copy inside a page of **your own site that the shell shows in an `<iframe>`** stands down as well, with a console message. The connector's `mark-build` step stamps every built HTML file, so an embedded static page carries the tag too; that copy is harmless and you can leave it.
- A copy inside a page of **your own site that the shell shows in an `<iframe>`** stands down as well, with a console message. Connect's `mark-build` step stamps every built HTML file, so an embedded static page carries the tag too; that copy is harmless and you can leave it.

What still needs your attention is a second tag that you, or the builder's AI, added by hand. It usually lives in a component, a layout, or a runtime `useEffect` that appends the script. Keep exactly one tag, in the root shell.

Expand All @@ -252,12 +252,12 @@ If the page embeds another page of your site in an `<iframe>`, run the same two
### Prompt: two widgets on the page

```text
Please make sure the Patchstack widget is loaded exactly once on this site.
Please make sure the Patchstack Connector is loaded exactly once on this site.

1. Search the entire project - source files, layouts, components, and static
HTML under public/ - for "patchstack-widget.js" and list every place that
loads it.
2. Keep exactly one <script> tag: the connector-managed one in the root shell
2. Keep exactly one <script> tag: the Connect-managed one in the root shell
(index.html, or the root layout for Next.js / TanStack Start / Remix). It
must carry data-site-uuid with the value from the committed
.patchstackrc.json.
Expand Down
Loading