env-flag 1.0.2 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +83 -59
  2. package/dist/index.d.ts +41 -0
  3. package/dist/index.js +1 -0
  4. package/package.json +16 -11
package/README.md CHANGED
@@ -1,91 +1,115 @@
1
- # env-flag
1
+ # 🚩 env-flag
2
2
 
3
- A lightweight, customizable environment flag indicator for browser applications. Shows DEV/PROD/STAGING/TEST status as a badge in your app. Perfect for distinguishing environments at a glance!
3
+ A premium, ultra-lightweight environment indicator for browser applications. Distinguish between **DEV**, **STAGING**, and **PROD** instantly with badges and screen frames.
4
+
5
+ [![npm version](https://img.shields.io/npm/v/env-flag.svg)](https://www.npmjs.com/package/env-flag)
6
+ [![bundle size](https://img.shields.io/bundlephobia/min/env-flag)](https://bundlephobia.com/package/env-flag)
7
+ [![license](https://img.shields.io/npm/l/env-flag.svg)](https://github.com/koraytuncer/env-flag/blob/main/LICENSE)
8
+
9
+ ---
10
+
11
+ ## ✨ Why env-flag?
12
+
13
+ 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.
14
+
15
+ - 🚀 **Ultra-Small:** Only **~2.5KB** minified. Zero dependencies.
16
+ - 🖼️ **Visual Safety:** Full-screen frame indicator for instant recognition.
17
+ - ⚡ **Performance First:** Optimized DOM operations and `pointer-events: none` ensures no interaction lag.
18
+ - 🧠 **Auto-Detection:** Works out-of-the-box with **Vite, Webpack, Next.js,** and **Create React App**.
19
+ - 🎨 **Fully Customizable:** Match your brand or stick with our premium defaults.
20
+
21
+ ---
4
22
 
5
23
  ## 🚀 Features
6
- - **Automatic environment detection** (development, production, staging, test)
7
- - **Customizable colors, text, position, and size**
8
- - **Accessible** (keyboard, screen reader, ARIA labels)
9
- - **TypeScript support**
10
- - **No dependencies**
24
+
25
+ - [x] **Automatic environment detection** (Node, Vite, React, Vue, or Hostname).
26
+ - [x] **Screen Frame:** A colored border around your entire viewport (Safe & Fast).
27
+ - [x] **Minimal Badge:** A subtle, customizable badge in any corner.
28
+ - [x] **Smart Styling:** Zero Layout Shift (ZLS) design.
29
+ - [x] **TypeScript Native:** Full type safety included.
30
+
31
+ ---
11
32
 
12
33
  ## 📦 Installation
13
34
 
14
35
  ```sh
15
36
  npm install env-flag
37
+ # or
38
+ yarn add env-flag
39
+ # or
40
+ pnpm add env-flag
16
41
  ```
17
42
 
18
- or
43
+ ---
19
44
 
20
- ```sh
21
- yarn add env-flag
22
- ```
45
+ ## 🛠️ Getting Started
23
46
 
24
- ## 🛠️ Usage
47
+ ### 1. Basic Setup
25
48
 
26
- ### Basic
27
- ```js
28
- import EnvFlag from 'env-flag';
49
+ Just import and initialize. It will try to detect your environment automatically.
50
+
51
+ ```typescript
52
+ import EnvFlag from "env-flag";
29
53
 
30
54
  const flag = new EnvFlag();
31
55
  flag.init();
32
56
  ```
33
57
 
34
- ### With Custom Options
35
- ```js
36
- import EnvFlag from 'env-flag';
58
+ ### 2. Advanced Configuration
37
59
 
38
- const flag = new EnvFlag({
39
- position: 'top-left',
40
- size: 'large',
41
- productionColor: '#27ae60',
42
- developmentText: 'DEVS',
43
- debug: true
44
- });
45
- flag.init();
46
- ```
60
+ Customize colors, thickness, and visibility.
47
61
 
48
- ### Force Environment (for testing)
49
- ```js
62
+ ```typescript
50
63
  const flag = new EnvFlag({
51
- forceEnv: 'staging',
52
- stagingColor: '#ff9800',
53
- stagingText: 'STAGING'
64
+ position: "top-left",
65
+ showFrame: true, // Enable the full screen border
66
+ frameWidth: "6px", // Frame thickness
67
+ developmentColor: "#00D1FF",
68
+ productionText: "⚠️ LIVE SYSTEM",
69
+ size: "large",
54
70
  });
71
+
55
72
  flag.init();
56
73
  ```
57
74
 
58
- ## ⚙️ Configuration
59
-
60
- | Option | Type | Default | Description |
61
- |--------------------|----------|-----------------|----------------------------------------------|
62
- | productionColor | string | `#e74c3c` | Prod badge color |
63
- | developmentColor | string | `#3498db` | Dev badge color |
64
- | stagingColor | string | `#f39c12` | Staging badge color |
65
- | testColor | string | `#9b59b6` | Test badge color |
66
- | productionText | string | `PROD` | Prod badge text |
67
- | developmentText | string | `DEV` | Dev badge text |
68
- | stagingText | string | `STAGING` | Staging badge text |
69
- | testText | string | `TEST` | Test badge text |
70
- | position | string | `bottom-right` | Badge position (`top-right`, `top-left`, `bottom-right`, `bottom-left`) |
71
- | size | string | `medium` | Badge size (`small`, `medium`, `large`) |
72
- | autoDetectEnv | boolean | `true` | Try to detect environment automatically |
73
- | forceEnv | string | | Force environment (`production`, `development`, `staging`, `test`) |
74
- | enabled | boolean | `true` | Show/hide the flag |
75
- | debug | boolean | `false` | Enable debug logs |
75
+ ---
76
76
 
77
- ## 🧑‍💻 Contributing
77
+ ## ⚙️ Configuration Options
78
78
 
79
- 1. Fork the repo
80
- 2. Create your feature branch (`git checkout -b feature/your-feature`)
81
- 3. Commit your changes (`git commit -am 'Add new feature'`)
82
- 4. Push to the branch (`git push origin feature/your-feature`)
83
- 5. Open a Pull Request
79
+ | Option | Type | Default | Description |
80
+ | ------------------ | --------- | -------------- | ------------------------------------------ |
81
+ | `enabled` | `boolean` | `true` | Show/hide the flag entirely. |
82
+ | `showFrame` | `boolean` | `true` | Show a colored frame around the screen. |
83
+ | `frameWidth` | `string` | `4px` | Thickness of the screen frame. |
84
+ | `productionColor` | `string` | `#f8285a` | Color for Production environment. |
85
+ | `developmentColor` | `string` | `#17c653` | Color for Development environment. |
86
+ | `stagingColor` | `string` | `#f39c12` | Color for Staging environment. |
87
+ | `testColor` | `string` | `#9b59b6` | Color for Test environment. |
88
+ | `position` | `string` | `bottom-right` | Badge corner position (see below). |
89
+ | `size` | `string` | `medium` | Badge size (`small`, `medium`, `large`). |
90
+ | `autoDetectEnv` | `boolean` | `true` | Try to detect env via bundler or hostname. |
91
+ | `forceEnv` | `string` | `undefined` | Manually override detection. |
84
92
 
85
- ## 📄 License
93
+ ### Valid Positions
86
94
 
87
- ISC
95
+ `top-right` | `top-left` | `bottom-right` | `bottom-left`
88
96
 
89
97
  ---
90
98
 
91
- Made with ❤️ by Koray TUNCER
99
+ ## 🛡️ Performance Note
100
+
101
+ The screen frame uses `box-shadow: inset` and `pointer-events: none`. This means:
102
+
103
+ 1. It **does not affect** your layout (won't push elements).
104
+ 2. It **does not block** clicks (you can click buttons "under" the frame).
105
+ 3. It has **zero GPU impact** during scrolling.
106
+
107
+ ---
108
+
109
+ ## 🧑‍💻 Contributing
110
+
111
+ Contributions are welcome! If you find a bug or have a feature request, please open an issue.
112
+
113
+ ## 📄 License
114
+
115
+ ISC © [Koray TUNCER](mailto:ktuncerr@gmail.com)
package/dist/index.d.ts ADDED
@@ -0,0 +1,41 @@
1
+ /**
2
+ * Environment Flag - A lightweight library to display environment indicators
3
+ * @version 1.1.0
4
+ */
5
+ declare global {
6
+ interface ImportMeta {
7
+ readonly env: any;
8
+ }
9
+ }
10
+ type Environment = "development" | "production" | "staging" | "test";
11
+ type Position = "top-right" | "top-left" | "bottom-right" | "bottom-left";
12
+ type Size = "small" | "medium" | "large";
13
+ interface EnvFlagConfig {
14
+ productionColor?: string;
15
+ developmentColor?: string;
16
+ stagingColor?: string;
17
+ testColor?: string;
18
+ productionText?: string;
19
+ developmentText?: string;
20
+ stagingText?: string;
21
+ testText?: string;
22
+ position?: Position;
23
+ size?: Size;
24
+ autoDetectEnv?: boolean;
25
+ forceEnv?: Environment;
26
+ enabled?: boolean;
27
+ debug?: boolean;
28
+ showFrame?: boolean;
29
+ frameWidth?: string;
30
+ }
31
+ declare class EnvFlag {
32
+ private config;
33
+ private el;
34
+ private frame;
35
+ constructor(config?: EnvFlagConfig);
36
+ init(): void;
37
+ destroy(): void;
38
+ private getEnv;
39
+ }
40
+
41
+ export { EnvFlag, type EnvFlagConfig, type Environment, type Position, type Size, EnvFlag as default };
package/dist/index.js ADDED
@@ -0,0 +1 @@
1
+ var d={productionColor:"#f8285a",developmentColor:"#17c653",stagingColor:"#f39c12",testColor:"#9b59b6",productionText:"PROD",developmentText:"DEV",stagingText:"STAGING",testText:"TEST",position:"bottom-right",size:"medium",autoDetectEnv:!0,forceEnv:"development",enabled:!0,debug:!1,showFrame:!0,frameWidth:"4px"},r=class{config;el=null;frame=null;constructor(e={}){this.config={...d,...e},e.forceEnv&&(this.config.forceEnv=e.forceEnv)}init(){if(typeof window>"u"||!this.config.enabled)return;this.destroy();let e=this.getEnv(),i=this.config[`${e}Color`],t=document.createElement("div");this.el=t,t.id="env-flag-badge",t.setAttribute("role","status"),t.textContent=this.config[`${e}Text`];let o={small:["10px","4px 8px"],medium:["12px","6px 12px"],large:["14px","8px 16px"]}[this.config.size],s={"top-right":{top:0,right:0,borderRadius:"0 0 0 4px"},"top-left":{top:0,left:0,borderRadius:"0 0 4px 0"},"bottom-right":{bottom:0,right:0,borderRadius:"4px 0 0 0"},"bottom-left":{bottom:0,left:0,borderRadius:"0 4px 0 0"}}[this.config.position];if(Object.assign(t.style,{position:"fixed",zIndex:"999999",backgroundColor:i,color:"#fff",fontFamily:"system-ui, sans-serif",fontWeight:"600",fontSize:o[0],padding:o[1],opacity:"0.9",cursor:"pointer",userSelect:"none",transition:"all 0.2s",...s}),t.onclick=()=>this.destroy(),t.onmouseenter=()=>{t.style.opacity="1",t.style.transform="scale(1.05)"},t.onmouseleave=()=>{t.style.opacity="0.9",t.style.transform="scale(1)"},this.config.showFrame){let n=document.createElement("div");this.frame=n,n.id="env-flag-frame",Object.assign(n.style,{position:"fixed",inset:"0",pointerEvents:"none",zIndex:"999998",boxShadow:`inset 0 0 0 ${this.config.frameWidth} ${i}`,transition:"box-shadow 0.2s"}),document.body.appendChild(n)}document.body.appendChild(t)}destroy(){[this.el,this.frame].forEach(e=>e?.remove()),this.el=this.frame=null}getEnv(){if(this.config.forceEnv&&this.config.forceEnv!=="development")return this.config.forceEnv;if(!this.config.autoDetectEnv)return"development";let e=window.location.hostname,i=typeof import.meta<"u"?import.meta.env:{},t=globalThis.process?.env||{},o=n=>{let l=i?.[n]||t[n];return["development","production","staging","test"].includes(l)?l:null},s=o("NODE_ENV")||o("VITE_APP_ENV")||o("REACT_APP_ENV")||o("VUE_APP_ENV");return s||(e.includes("prod")||e&&!/localhost|127\.0\.0\.1|dev|staging|test/.test(e)?"production":/staging|stage/.test(e)?"staging":e.includes("test")?"test":"development")}};if(typeof window<"u"){let a=new r;document.readyState==="loading"?document.addEventListener("DOMContentLoaded",()=>a.init()):a.init()}var c=r;export{r as EnvFlag,c as default};
package/package.json CHANGED
@@ -1,18 +1,24 @@
1
1
  {
2
2
  "name": "env-flag",
3
- "version": "1.0.2",
4
- "main": "dist/index.js",
5
- "module": "dist/index.js",
6
- "types": "dist/index.d.ts",
3
+ "version": "1.1.0",
4
+ "description": "A lightweight environment flag indicator for browser apps.",
7
5
  "type": "module",
6
+ "main": "./dist/index.js",
7
+ "module": "./dist/index.js",
8
+ "types": "./dist/index.d.ts",
9
+ "exports": {
10
+ ".": {
11
+ "types": "./dist/index.d.ts",
12
+ "import": "./dist/index.js"
13
+ }
14
+ },
8
15
  "files": [
9
- "dist",
10
- "README.md"
16
+ "dist"
11
17
  ],
12
18
  "scripts": {
13
- "build": "tsc",
14
- "start": "tsc && node dist/index.js",
15
- "test": "echo \"Error: no test specified\" && exit 1"
19
+ "build": "tsup src/index.ts --format esm --dts --minify",
20
+ "dev": "tsup src/index.ts --format esm --watch",
21
+ "prepublishOnly": "npm run build"
16
22
  },
17
23
  "keywords": [
18
24
  "env",
@@ -25,14 +31,13 @@
25
31
  ],
26
32
  "author": "Koray TUNCER <ktuncerr@gmail.com>",
27
33
  "license": "ISC",
28
- "description": "A lightweight, customizable environment flag indicator for browser apps. Shows DEV/PROD/STAGING status as a badge.",
29
34
  "repository": {
30
35
  "type": "git",
31
36
  "url": "https://github.com/koraytuncer/env-flag.git"
32
37
  },
33
38
  "homepage": "https://github.com/koraytuncer/env-flag",
34
39
  "devDependencies": {
35
- "@types/node": "^24.0.11",
40
+ "tsup": "^8.5.1",
36
41
  "typescript": "^5.8.3"
37
42
  }
38
43
  }