🚩 env-flag

A premium, ultra-lightweight environment indicator for browser applications. Distinguish between DEV, STAGING, and PROD instantly with badges and screen frames.

✨ Why env-flag?

Ever accidentally ran a destructive script on a Production database thinking it was Development? env-flag prevents "environment confusion" by giving you high-visibility visual cues that are impossible to miss, yet zero-impact on your app's performance.

• 🚀 Ultra-Small: Only ~2.5KB minified. Zero dependencies.
• 🖼️ Visual Safety: Full-screen frame indicator for instant recognition.
• ⚡ Performance First: Optimized DOM operations and pointer-events: none ensures no interaction lag.
• 🧠 Auto-Detection: Works out-of-the-box with Vite, Webpack, Next.js, and Create React App.
• 🎨 Fully Customizable: Match your brand or stick with our premium defaults.

🚀 Features

• [x] Automatic environment detection (Node, Vite, React, Vue, or Hostname).
• [x] Screen Frame: A colored border around your entire viewport (Safe & Fast).
• [x] Minimal Badge: A subtle, customizable badge in any corner.
• [x] Smart Styling: Zero Layout Shift (ZLS) design.
• [x] TypeScript Native: Full type safety included.

📦 Installation

npm install env-flag
# or
yarn add env-flag
# or
pnpm add env-flag

🛠️ Getting Started

1. Basic Setup

Just import and initialize. It will try to detect your environment automatically.

import EnvFlag from "env-flag";

const flag = new EnvFlag();
flag.init();

2. Advanced Configuration

Customize colors, thickness, and visibility.

const flag = new EnvFlag({
  position: "top-left",
  showFrame: true, // Enable the full screen border
  frameWidth: "6px", // Frame thickness
  developmentColor: "#00D1FF",
  productionText: "⚠️ LIVE SYSTEM",
  size: "large",
});

flag.init();

⚙️ Configuration Options

| Option | Type | Default | Description | | ------------------ | --------- | -------------- | ------------------------------------------ | | enabled | boolean | true | Show/hide the flag entirely. | | showFrame | boolean | true | Show a colored frame around the screen. | | frameWidth | string | 4px | Thickness of the screen frame. | | productionColor | string | #f8285a | Color for Production environment. | | developmentColor | string | #17c653 | Color for Development environment. | | stagingColor | string | #f39c12 | Color for Staging environment. | | testColor | string | #9b59b6 | Color for Test environment. | | position | string | bottom-right | Badge corner position (see below). | | size | string | medium | Badge size (small, medium, large). | | autoDetectEnv | boolean | true | Try to detect env via bundler or hostname. | | forceEnv | string | undefined | Manually override detection. |

Valid Positions

top-right | top-left | bottom-right | bottom-left

🛡️ Performance Note

The screen frame uses box-shadow: inset and pointer-events: none. This means:

1. It does not affect your layout (won't push elements).
2. It does not block clicks (you can click buttons "under" the frame).
3. It has zero GPU impact during scrolling.

🧑‍💻 Contributing

Contributions are welcome! If you find a bug or have a feature request, please open an issue.

📄 License

ISC © Koray TUNCER