Plugins add integrations to a NextPress site. They ship as code (see ADR 0009) and administrators activate and configure them under Plugins in the admin.
-
Create
src/plugins/<id>/index.tsx:import Script from 'next/script' import { z } from 'zod' import { definePlugin } from '../types' export const myPlugin = definePlugin({ id: 'my-plugin', name: 'My plugin', description: 'One sentence shown in the plugin list.', category: 'analytics', version: '1.0.0', config: z.object({ siteId: z.string().regex(/^[a-z0-9]{6,32}$/) }), fields: [{ key: 'siteId', label: 'Site ID', placeholder: 'abc123' }], PublicScripts: ({ config }) => ( <Script src={`https://example.com/script.js?id=${config.siteId}`} strategy="lazyOnload" /> ), })
-
Register it in
src/plugins/index.ts. -
Allow its hosts in the CSP in
next.config.ts. -
If it needs a secret, add the variable to
src/lib/env.tsand.env.example, and list its name inrequiredEnv. -
Add a test next to the plugin that checks its config schema rejects unsafe values.
A plugin with captcha: 'turnstile' or captcha: 'recaptcha' protects the admin sign-in and the donation form. Only one captcha plugin can be active. The widget renders through components/captcha-widget.tsx (lazily on public forms, so it never affects the first paint), and verifyCaptcha() in src/lib/captcha.ts checks the token on the server with the secret from the environment.
- Validate every setting with a strict schema. Values end up inside scripts, so allow only the characters an ID can contain.
- Load third-party scripts with
strategy="lazyOnload"orafterInteractive, never in a way that blocks the first paint. - Render nothing in the admin.
PublicScriptsruns only on the public site.