console-self-xss-warning

console-self-xss-warning

Show a self-XSS warning in the browser console to protect users from social engineering.

Features

• Runs only in the browser and is safe for SSR.
• Default language is auto-detected via navigator.language with en fallback.
• Language tags use BCP 47 with normalization and primary subtag fallback (e.g. en-US -> en).
• Built-in translations for 40+ languages.
• \\n in translations is converted to a real line break in console output.
• No external dependencies.

Install

npm install console-self-xss-warning

Quick start

import { showConsoleWarning } from "console-self-xss-warning";

showConsoleWarning();

Framework examples

Full examples for popular frameworks and Vanilla JS are in examples/.

• Vanilla JS: examples/vanilla/README.md
• React: examples/react/README.md
• Next.js: examples/nextjs/README.md
• Vue: examples/vue/README.md
• Nuxt: examples/nuxt/README.md
• Svelte/SvelteKit: examples/svetle/README.md
• Vite: examples/vite/README.md
• Angular: examples/angular/README.md
• Astro: examples/astro/README.md
• Remix: examples/remix/README.md
• Gatsby: examples/gatsby/README.md
• Solid: examples/solid/README.md
• Qwik: examples/qwik/README.md

Configuration

parameter	default	required	description
translations	built-in translations	no	override texts and styles per language
forceLang	auto-detect (navigator.language)	no	force a specific language
once	true	no	show only once per page load
productionOnly	false	no	show only in production mode
clearConsole	false	no	clear the console before logging
productionOnlyEnvKey	default key list	no	read productionOnly from an env variable
config	default warning config	no	override styles and behavior defaults

Language tags (BCP 47)

Language keys and forceLang accept BCP 47 language tags (e.g. en, en-US, pt-BR). Tags are normalized to lowercase with -, and if a region-specific tag is not found the primary subtag is used as a fallback (e.g. en-US -> en).

Common options

showConsoleWarning({
  once: true,            // show only once per page load
  clearConsole: false,   // optionally clear console before warning
  productionOnly: false  // gate by production environment
});

Custom translation

showConsoleWarning({
  translations: {
    en: {
      title: "STOP!",
      message:
        "This is for developers only.\nIf someone asks you to paste code here, it is a scam.",
      titleStyle: "color:#d00;font-size:52px;font-weight:900;",
      messageStyle: "font-size:16px;"
    }
  }
});

Full custom JSON

const translations = {
  en: {
    title: "STOP!",
    message: "Private area.\nDo not paste anything here."
  },
  fr: {
    title: "STOP !",
    message: "Zone privée.\nNe collez rien ici."
  }
};

showConsoleWarning({
  translations,
  forceLang: "en",
  clearConsole: true
});

Config overrides

key	default	description
defaultTitleStyle	color:red;font-size:48px;font-weight:bold;	default title style
defaultMessageStyle	font-size:16px;	default message style
defaultSpamIntervalMs	2000	repeat interval for the warning in ms
devtoolsSizeThresholdPx	160	threshold used to detect open devtools

Environment config for productionOnly

If you want productionOnly to be driven by an environment variable, pass your own key name using productionOnlyEnvKey.

showConsoleWarning({
  productionOnlyEnvKey: "MY_APP_CONSOLE_WARNING_PROD_ONLY"
});

You can also pass multiple keys (first match wins):

showConsoleWarning({
  productionOnlyEnvKey: ["MY_KEY_1", "MY_KEY_2"]
});

Boolean values accepted: 1/0, true/false, yes/no, on/off

Default keys (if you do not pass anything):

• CONSOLE_SELF_XSS_WARNING_PRODUCTION_ONLY
• VITE_CONSOLE_SELF_XSS_WARNING_PRODUCTION_ONLY
• NEXT_PUBLIC_CONSOLE_SELF_XSS_WARNING_PRODUCTION_ONLY

API

type Options = {
  translations?: {
    [lang: string]: {
      title: string
      message: string
      titleStyle?: string
      messageStyle?: string
    }
  }
  forceLang?: string
  once?: boolean
  productionOnly?: boolean
  clearConsole?: boolean
  productionOnlyEnvKey?: string | string[]
  config?: {
    defaultTitleStyle?: string
    defaultMessageStyle?: string
    defaultSpamIntervalMs?: number
    devtoolsSizeThresholdPx?: number
  }
}

showConsoleWarning(options?)