A powerful, framework-agnostic environment variable management toolkit for modern JavaScript applications.
EnvKit provides a seamless way to manage environment variables in your applications with built-in validation, UI fallbacks for missing variables, and cross-framework compatibility.
- Framework Agnostic: Core package works with any JavaScript framework
- Framework Integrations: Dedicated packages for Next.js, with more coming soon
- Type-Safe: Built-in TypeScript support and runtime validation
- Developer-Friendly: Customizable fallback UI for missing environment variables
- Client-Server Separation: Clean separation between client and server code
- Styled with Tailwind CSS: Beautiful, customizable UI components
npm install @envkit/core
# or
yarn add @envkit/core
# or
pnpm add @envkit/corenpm install @envkit/nextjs
# or
yarn add @envkit/nextjs
# or
pnpm add @envkit/nextjsCheckout the starterkit here
- First, set up your environment variables in your Next.js app's root layout:
// app/layout.tsximport{EnvKitProvider,DefaultFallbackUI}from'@envkit/nextjs';import'@envkit/nextjs/styles.css';// Import the stylesexportdefaultfunctionRootLayout({ children }){return(<htmllang="en"><body><EnvKitProviderfallbackPath="/onboarding"customFallbackUI={DefaultFallbackUI}maskAllEnvs={true}disableAddNew={true}logoUrl="https://yourcompany.com/logo.png"// Optional custom logotitle="Environment Setup Required"// Optional custom titledescription="Please provide the following variables to continue"// Optional custom description>{children}</EnvKitProvider></body></html>);}- Create an onboarding page that will serve as a fallback when env vars are missing:
// app/onboarding/page.tsxexportdefaultfunctionOnboardingPage(){returnnull;// EnvKit will handle the UI}- Create an API route handler:
// app/api/envkit/route.ts// Use the direct path to the compiled output for local developmentimport{createEnvApiHandler}from'@envkit/nextjs/server';import{NextRequest}from'next/server';// Using dynamic import for server-only code// This ensures proper separation of client and server codeconsthandlers=createEnvApiHandler({environments: {production: {// Specify required variables for productionrequiredVars: ['DATABASE_URL','API_KEY'],},local: {// Specify required variables for local developmenttargetEnvFile: '.env.local',requiredVars: ['DATABASE_URL','API_KEY','zyx'],},development: {// Specify required variables for developmenttargetEnvFile: '.env.development',requiredVars: ['DATABASE_URL','API_KEY'],},},// Optional: Allow access in production (defaults to false)allowInProduction: false,// Optional: Customize the directory for .env filesenvDir: process.cwd(),});// Export GET and POST handlers for Next.js App RouterexportasyncfunctionGET(request: NextRequest){returnhandlers.statusHandler(request);}exportasyncfunctionPOST(request: NextRequest){returnhandlers.updateHandler(request);}EnvKit provides several customization options for the fallback UI:
// Customize the appearance without creating a custom component<EnvKitProviderfallbackPath="/onboarding"logoUrl="https://yourcompany.com/logo.png"// Custom logo URLtitle="Environment Setup"// Custom titledescription="Please enter the required environment variables"// Custom descriptionmaskAllEnvs={true}// Mask all environment variables by defaultdisableAddNew={true}// Only allow configuration of required environment variables>{children}</EnvKitProvider>The disableAddNew property ensures that users can only configure the environment variables that you've specified as required, preventing them from adding any new variables:
<EnvKitProviderdisableAddNew={true}// Only show and allow configuration of required variables>{children}</EnvKitProvider>This is useful when you want to strictly control which environment variables are set in your application.
Create a custom fallback UI component:
import{FallbackUIProps}from'@envkit/nextjs';functionCustomFallbackUI({ missingVars, isLoading, onSubmit, logoUrl, title, description,
maskAllEnvs,
disableAddNew,}: FallbackUIProps){// Implementation...return<div>Your custom UI here</div>;}// Then in your layout:<EnvKitProviderfallbackPath="/onboarding"customFallbackUI={CustomFallbackUI}logoUrl="https://yourcompany.com/logo.png"// These props will be passed to your custom componenttitle="Environment Setup"maskAllEnvs={true}disableAddNew={true}description="Please enter the required environment variables">{children}</EnvKitProvider>For more detailed documentation, visit:
This project is licensed under the FSL-1.1-MIT License. See the LICENSE file for details.