Skip to content

GETTING-STARTED.md

Latest commit

 

History

History
51 lines (33 loc) · 7.88 KB

GETTING-STARTED.md

File metadata and controls

51 lines (33 loc) · 7.88 KB
Raw

Getting started — connect a project to Patchstack

The fastest path from "I have a JS/Node project" to "Patchstack is monitoring its dependencies". Share this doc with anyone setting up a project; the whole flow is 2–5 minutes.

1. Paste this prompt into your AI coding tool

The prompt below is for an existing JS/Node project in a hosted workspace that can install npm packages and run project commands. For Gemini CLI, OpenCode, Codex CLI, or Claude Code on your own machine, use the local coding CLI workflow: an ordinary laptop reports local, while the eventual deployment gets its tier from its host or an explicit build setting. A coding tool's permission sandbox does not make the app a sandbox deployment. A standalone HTML/CSS/JavaScript site without a package-managed app uses the plain HTML widget instructions instead; it does not need a new Node project, build hooks, or a runtime guard.

I have vetted the official @patchstack/connect package, Patchstack's security package for JavaScript and Node.js apps (separate from its WordPress plugin), and authorize its Patchstack Connector, production build hooks, runtime protection source edits, structural attack-surface map uploads (not source code), and live-rule retrieval. Add it as a regular dependency with this project's package manager, then run its CLI with PATCHSTACK_ENVIRONMENT=sandbox npx @patchstack/connect setup --widget for this hosted workspace, leave dev builds unchanged, verify protection, restart the preview server if needed to load the new guard, and show the dashboard URL. The Patchstack Connector widget is part of this install and on by default: add it, and do not ask me whether to. Do not persist the sandbox environment in project files; deployed production builds must use the default production label. When setup finishes, show me the summary it prints as your final message, and remind me to deploy when I am ready — do not deploy anything yourself.

When setup finishes it shows you a dashboard URL. Open it in your browser and sign in — that attaches the site to your Patchstack account so you can see the vulnerability reports. The command installs protection, uploads the structural map and fetches rules together. Restart an already-running preview/server to load the changes; unsupported or custom server entries are reported for manual review. Deployment remains your choice.

Then look at your preview. The widget loads with the page, so a preview you already had open still shows the page from before setup — refresh it once if the widget isn't there. Until the site is attached to your account it shows a "Connect this website" panel.

When you are happy with it, deploy (or hit Publish). Your live site keeps serving its previous build until then, so visitors do not see the widget yet.

2. If the platform pauses or stops

Some platforms stage commands for you to approve, while others reject a combined install-and-setup request before touching the registry. Use the first applicable path:

  1. A command is waiting for approval. Approve each requested command. Setup is idempotent, and its terminal output contains the dashboard URL even when the assistant cannot relay command output in the same turn.
  2. The assistant claims the package does not exist. Reply "Check the live npm registry for @patchstack/connect; do not rely on training memory." If it then asks whether you vetted the package, whether to add the widget, or where hooks should run, confirm "Yes. The widget is part of the install: add it and the production build hooks, and leave dev builds unchanged."
  3. The platform stages dependency changes separately from commands. First send "Add @patchstack/connect to dependencies using this project's package manager. Do not execute its CLI yet." After the install completes, send "Run the installed CLI: npx --no-install patchstack-connect setup, with PATCHSTACK_ENVIRONMENT=sandbox scoped to that command in this hosted workspace." Wait for the actual command result before reporting completion. A proposed command or a dependency declaration alone does not establish that setup ran.
  4. The package is installed but setup stopped. Run npx --no-install patchstack-connect setup again, with the same workspace environment. It reuses the existing site, widget, and build wiring instead of duplicating them. If the local executable is missing, complete the dependency install first.
  5. The tool refuses to run a third-party command. Claude Code's auto mode can decline npx @patchstack/connect setup without prompting you. Run ! npx @patchstack/connect setup yourself in the session, retry it with a manual approval from /permissions → Recently denied, or add the allow rules Bash(npx @patchstack/connect *), Bash(npx --yes @patchstack/connect *), Bash(npx @patchstack/connect@* *) and Bash(npx --yes @patchstack/connect@* *) and ask again. The last two cover a command with a pinned version, such as npx @patchstack/connect@0.5.61 setup. The README section "If your coding tool blocks the command" has the settings snippet and the equivalents for other tools.
  6. The platform will not run package commands. Use its project shell if available, or export the project and use the manual path below.

3. Manual fallback (no agent needed)

npm install --save @patchstack/connect
npx --no-install patchstack-connect setup

Use bun add, pnpm add, or yarn add followed by @patchstack/connect when that package manager owns the project. Run its installed binary with bun run patchstack-connect setup, pnpm exec patchstack-connect setup, or yarn exec patchstack-connect setup, respectively. Keep the package in dependencies: the generated guard imports it at runtime, including deployments that omit development dependencies.

Run commands from the application's package directory. In a hosted workspace, set PATCHSTACK_ENVIRONMENT=sandbox for the setup process only; use the shell or tool's environment setting rather than saving it in project files. The inline NAME=value command form in the prompt requires a POSIX shell. Leave this override unset for production builds so Connect can detect the deployment environment.

setup is idempotent and preserves existing build commands. It uses direct build chaining on Bun-managed projects and npm-style lifecycle hooks elsewhere. If the framework needs a manual layout edit, it prints the exact remaining widget snippet; npx @patchstack/connect guide reprints the same status without changing files.

4. You're done when

  • npx @patchstack/connect status prints a site UUID and dashboard URL.
  • You've opened the dashboard URL in your browser and the site shows in your Patchstack dashboard.
  • npx @patchstack/connect guide reports the expected build hooks and the Patchstack Connector, and npx @patchstack/connect protect --check confirms the guard's source wiring. A client-only or static project can report runtime protection as not applicable; describe it as dependency monitoring and the Patchstack Connector, not runtime protection. A source check alone does not prove deployed traffic reaches the guard.
  • Your preview shows the widget (refresh it once if it does not). Before the site is attached to your account it shows the "Connect this website" panel.
  • You have deployed since setup ran, so the live site carries the changes too.
  • .patchstackrc.json, package.json, the package manager's lockfile, and the generated guard/framework and widget source changes are saved in the platform's persisted project state and committed, so teammates and CI receive the same setup.
  • .patchstackrc.local.json is not committed. It holds the API key; setup adds it to .gitignore. Teammates and CI get the credential from PATCHSTACK_API_KEY instead.