Plugin Next.js

Installation

Installez le plugin avec votre gestionnaire de paquets :

npm install @withpanache/nextjs
# ou
pnpm add @withpanache/nextjs
# ou
yarn add @withpanache/nextjs

Demarrage rapide

Wrappez votre config Next.js avec withPanache. C'est tout : votre app a maintenant des headers de securite et X-Powered-By est desactive.

// next.config.ts
import { withPanache } from "@withpanache/nextjs"

export default withPanache({
  // votre config Next.js existante
})

Headers de securite

Par defaut, withPanache injecte les headers suivants sur toutes les routes. Ils sont assez permissifs pour la plupart des apps Next.js tout en passant les checks de securite Panache.

Personnaliser les headers

Passez un objet security pour modifier ou desactiver des headers individuels. Mettez un header a false pour le desactiver.

export default withPanache(nextConfig, {
  security: {
    // Desactiver HSTS (ex. derriere un reverse proxy)
    strictTransportSecurity: false,

    // Politique de referrer personnalisee
    referrerPolicy: "no-referrer",

    // Framing plus strict
    xFrameOptions: "DENY",
  },
})

Content Security Policy

Le CSP peut etre configure comme un objet type ou une chaine brute. Forme objet : vos sources sont ajoutees aux valeurs par defaut (dedupliquees). Pas besoin de repeter 'self' ou les autres valeurs par defaut. Les directives que vous ne mentionnez pas gardent leurs valeurs par defaut. Pour remplacer une directive specifique au lieu de l'etendre, utilisez le helper replace(). Forme chaine : remplace entierement le CSP par defaut. Toutes les formes beneficient de l'autocompletion TypeScript pour les noms de directives et les valeurs sources.

import { withPanache, replace } from "@withpanache/nextjs"

export default withPanache(nextConfig, {
  security: {
    contentSecurityPolicy: {
      // Etend : les sources s'ajoutent aux defaults
      "script-src": ["https://cdn.example.com"],
      // Remplace : cette directive ecrase entierement le default
      "connect-src": replace(["'self'", "https://api.example.com"]),
    },
  },
})

// Forme chaine : remplace tout le CSP
export default withPanache(nextConfig, {
  security: {
    contentSecurityPolicy: "default-src 'none'; script-src 'self'",
  },
})

Permissions Policy

Meme principe que le CSP. La forme objet ajoute aux valeurs par defaut, la forme chaine remplace. Un tableau vide desactive la fonctionnalite.

export default withPanache(nextConfig, {
  security: {
    permissionsPolicy: {
      // Fusion avec les defaults (camera, micro, geoloc restent desactives)
      fullscreen: ["self"],
      payment: [],
    },
  },
})

Comportement de fusion

Si vous definissez deja une fonction headers() dans votre config Next.js, Panache ajoute ses headers a votre route catch-all sans ecraser ceux que vous avez definis. Si vous n'avez pas de fonction headers(), Panache en cree une. Vos headers ont toujours la priorite. Panache n'ecrase jamais un header existant. En developpement, le CSP par defaut inclut 'unsafe-eval' dans script-src car le mode dev de React en a besoin. Ceci est automatiquement retire en production.

Monitoring des dependances

Pendant next build, le plugin detecte votre gestionnaire de paquets, collecte l'arbre complet des dependances et l'envoie a Panache pour le suivi des vulnerabilites. Cela s'execute dans un sous-processus detache et ne bloque ni ne ralentit jamais votre build. En cas d'echec, il echoue silencieusement. Gestionnaires supportes : pnpm, npm, yarn (classic et berry). Pour l'activer, ajoutez votre token de site :

export default withPanache(
  { /* next config */ },
  { token: process.env.PANACHE_SITE_TOKEN }
)

Detection CI/CD

Le plugin detecte automatiquement le SHA git, la branche et l'URL de preview depuis les environnements CI courants : SHA Git : GITHUB_SHA, CI_COMMIT_SHA, VERCEL_GIT_COMMIT_SHA, CF_PAGES_COMMIT_SHA, ou git local. Branche : GITHUB_REF_NAME, CI_COMMIT_BRANCH, VERCEL_GIT_COMMIT_REF, CF_PAGES_BRANCH, ou git local. URL Preview : VERCEL_URL, CF_PAGES_URL, DEPLOY_URL. Aucune configuration necessaire. Si les variables d'environnement sont presentes, elles sont utilisees automatiquement.

Toutes les options

Reference complete des options :

interface PanacheOptions {
  /** Token de site depuis le dashboard Panache. Lit aussi l'env PANACHE_SITE_TOKEN. */
  token?: string
  /** URL de l'API d'ingestion. Default: "https://withpanache.dev/api/v1/ingest" */
  apiUrl?: string
  /** Headers de securite. true = tous les defaults, false = aucun, objet = personnaliser. Default: true */
  security?: boolean | SecurityHeadersConfig
}

TypeScript

Tous les types sont exportes pour utilisation dans votre config :

import type {
  PanacheOptions,
  SecurityHeadersConfig,
  CspDirectives,
  CspDirectiveName,
  CspSourceValue,
  PermissionsPolicyDirectives,
  PermissionsPolicyFeature,
  ReferrerPolicy,
} from "@withpanache/nextjs"