https://github.com/skullcrawler/react-env-secrets
A zero-config React hook for environment variables - drop-in replacement for process.env
https://github.com/skullcrawler/react-env-secrets
dotenv env environment-variables process-env react react-hook typescript zero-config
Last synced: 2 months ago
JSON representation
A zero-config React hook for environment variables - drop-in replacement for process.env
- Host: GitHub
- URL: https://github.com/skullcrawler/react-env-secrets
- Owner: SkullCrawler
- License: gpl-3.0
- Created: 2025-08-04T11:26:17.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-08-05T13:08:27.000Z (11 months ago)
- Last Synced: 2025-09-11T22:02:29.611Z (9 months ago)
- Topics: dotenv, env, environment-variables, process-env, react, react-hook, typescript, zero-config
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/react-env-secrets
- Size: 230 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# react-env-secrets
[](https://badge.fury.io/js/react-env-secrets)
[](https://opensource.org/licenses/MIT)
[](http://www.typescriptlang.org/)
**A zero-configuration React hook for environment variables - the perfect drop-in replacement for `process.env`**
Stop writing `process.env.REACT_APP_SOMETHING` everywhere. Get clean, type-safe access to your environment variables with zero setup required.
## ✨ Features
- 🚀 **Zero Configuration** - Just install and use
- 🔄 **Drop-in Replacement** - Replace `process.env.VARIABLE` with `useEnv()`
- 🏷️ **TypeScript Support** - Full type safety out of the box
- 🎯 **Smart Prefix Detection** - Works with React, Next.js, Vite, and more
- 🧹 **Clean Variable Names** - No more prefixes in your code
- ⚡ **Performance Optimized** - Cached for efficiency
- 🛡️ **Error Handling** - Built-in validation and helpful error messages
## 📦 Installation
```bash
npm install react-env-secrets
```
```bash
yarn add react-env-secrets
```
```bash
pnpm add react-env-secrets
```
## 🚀 Quick Start
### Before (the old way):
```tsx
const API_URL = process.env.REACT_APP_API_URL;
const PORT = process.env.REACT_APP_PORT;
const DATABASE_URL = process.env.REACT_APP_DATABASE_URL;
// Lots of repetitive process.env.REACT_APP_ everywhere! 😫
```
### After (the clean way):
```tsx
import { useEnv } from 'react-env-secrets';
function MyComponent() {
const { API_URL, PORT, DATABASE_URL } = useEnv();
return
API URL: {API_URL};
}
```
That's it! No configuration needed. 🎉
## 📝 Usage Examples
### Basic Usage
```tsx
import { useEnv } from 'react-env-secrets';
function App() {
// Get all your environment variables at once
const { API_URL, PORT, DEBUG_MODE } = useEnv();
return (
My App
API: {API_URL}
Port: {PORT}
Debug: {DEBUG_MODE}
);
}
```
### With Validation & Fallbacks
```tsx
import { useEnv } from 'react-env-secrets';
function App() {
const env = useEnv({
required: ['API_URL', 'DATABASE_URL'], // Will show helpful errors if missing
fallbacks: {
PORT: '3000',
DEBUG_MODE: 'false'
}
});
return
API: {env.API_URL};
}
```
### Single Variable Hook
```tsx
import { useEnvVar } from 'react-env-secrets';
function ApiComponent() {
const apiUrl = useEnvVar('API_URL', 'http://localhost:3000');
return
Connecting to: {apiUrl};
}
```
### TypeScript Support
```tsx
import { useEnv, type EnvVars } from 'react-env-secrets';
interface MyEnvVars extends EnvVars {
API_URL: string;
PORT: string;
DEBUG_MODE?: string;
}
function App() {
const { API_URL, PORT, DEBUG_MODE } = useEnv() as MyEnvVars;
// Full type safety! ✅
}
```
## 🔧 Environment Setup
Create a `.env` file in your project root:
```env
# React apps
REACT_APP_API_URL=https://api.example.com
REACT_APP_PORT=3000
REACT_APP_DEBUG_MODE=true
# Next.js apps
NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_PORT=3000
# Vite apps
VITE_API_URL=https://api.example.com
VITE_PORT=3000
# Or custom prefix
PUBLIC_API_URL=https://api.example.com
```
The hook automatically detects and strips these prefixes:
- `REACT_APP_`
- `NEXT_PUBLIC_`
- `VITE_`
- `PUBLIC_`
So `REACT_APP_API_URL` becomes just `API_URL` in your code! 🎯
## 📚 API Reference
### `useEnv(options?)`
Main hook for accessing environment variables.
**Parameters:**
- `options` (optional): Configuration object
- `prefix?: string` - Custom prefix filter
- `required?: string[]` - Required variable names
- `fallbacks?: Record` - Fallback values
**Returns:** Object with all environment variables
### `useEnvVar(key, fallback?)`
Hook for a single environment variable.
**Parameters:**
- `key: string` - Variable name (without prefix)
- `fallback?: string` - Fallback value
**Returns:** Variable value or fallback
### `clearEnvCache()`
Clears the internal cache. Useful for testing.
### `listEnvVars()`
Development helper to see all available variables.
## 🌟 Why react-env-secrets?
### The Problem
```tsx
// This is what we're all tired of writing:
const API_URL = process.env.REACT_APP_API_URL;
const API_KEY = process.env.REACT_APP_API_KEY;
const PORT = process.env.REACT_APP_PORT || '3000';
const DEBUG = process.env.REACT_APP_DEBUG === 'true';
// Repetitive, verbose, and error-prone! 😤
```
### The Solution
```tsx
// Clean, simple, and powerful:
const { API_URL, API_KEY, PORT, DEBUG } = useEnv({
fallbacks: { PORT: '3000' }
});
// That's it! 🚀
```
## 🔒 Security Features
- **Client-Safe**: Only exposes prefixed environment variables on the client
- **Server-Compatible**: Works seamlessly in server-side rendering
- **Development Warnings**: Helpful error messages when variables are missing
- **Type Safety**: Catch environment variable issues at compile time
## 🏗️ Framework Support
Works perfectly with:
- ✅ **Create React App**
- ✅ **Next.js**
- ✅ **Vite**
- ✅ **Remix**
- ✅ **Gatsby**
- ✅ **Any React framework**
## 🧪 Testing
```tsx
import { clearEnvCache, listEnvVars } from 'react-env-secrets';
// Clear cache between tests
beforeEach(() => {
clearEnvCache();
});
// See available variables in development
console.log(listEnvVars());
```
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
## 📄 License
MIT © [Rayyan Waseem](https://github.com/SkullCrawler)
## 🆘 Support
- 📖 [Documentation](https://github.com/SkullCrawler/react-env-secrets#readme)
- 🐛 [Issue Tracker](https://github.com/SkullCrawler/react-env-secrets/issues)
- 💬 [Discussions](https://github.com/SkullCrawler/react-env-secrets/discussions)
---
**Made with ❤️ for React developers who are tired of `process.env.REACT_APP_EVERYTHING`**