🔐 EnvSync – Smart Environment File Manager

EnvSync is a lightweight utility for managing .env files across multiple environments. It validates, auto-syncs, and securely encrypts your environment variables — ensuring every project has consistent and safe configuration.

🚀 Features

✅ Validate .env files against a schema ✅ Enforce required environment variables ✅ Apply default values automatically ✅ Auto-create .sample.env files ✅ Encrypt and decrypt sensitive values ✅ Sync missing variables between .env and .sample.env ✅ Developer-friendly error messages

📦 Installation

npm install envsync-manager

or

yarn add envsync-manager

🧠 Quick Start

import { mainfunction } from "envsync-manager";

mainfunction(
  "development",
  ".env",
  {
    DB_HOST: { required: true },
    DB_USER: { required: true },
    DB_PASS: { required: true },
    PORT: { required: false, default: 3000 },
  },
  {
    validationError: true,
    encrypt: true,
    passkey: "secureKey123",
    sync: true,
    createSampleEnv: true,
  }
);

⚙️ Function Signature

mainfunction(environment, path, schema, options)

| Parameter | Type | Description | | --------------- | -------- | ------------------------------------------------------------ | | environment | string | The environment name (e.g., "development", "production") | | path | string | Path to your .env file | | schema | object | Schema defining required and optional environment variables | | options | object | Behavior configuration (validation, encryption, syncing) |

🧩 Schema Definition

Define rules for your environment variables.

{
  VARIABLE_NAME: {
    required?: boolean,         // Whether variable must exist
    default?: string | number   // Default value if missing
  }
}

✅ Example

{
  DB_HOST: { required: true },
  DB_USER: { required: true },
  DB_PASS: { required: true },
  PORT: { required: false, default: 3000 }
}

🔧 Options

| Option | Type | Default | Description | | ------------------- | --------- | ------- | -------------------------------------------------------- | | validationError | boolean | false | If true, throws structured error when validation fails | | encrypt | boolean | false | Enables encryption/decryption for .env values | | passkey | string | "" | Secret key used for encryption | | sync | boolean | false | Syncs missing variables between .env and .sample.env | | createSampleEnv | boolean | false | Creates .sample.env file if it doesn’t exist |

🔒 Encryption Example

If encrypt: true and passkey: "secureKey123" are provided, sensitive fields like passwords or API keys will be stored encrypted.

Before Encryption

DB_PASS=mysecret

After Encryption

DB_PASS=enc:3f9ab29e1a8f...

When your app runs, EnvSync automatically decrypts them internally.

⚠️ Error Handling

If validationError: true, EnvSync throws a structured error object whenever the .env file fails validation.

Example Error

❌ Error syncing .env files: Error: ValidationError
    at error (/src/components/error.ts:9:15)
    at validation (/src/components/validation.ts:27:10)

Error Data Object

{
  "missingInEnv": [],
  "extraInEnv": [],
  "missingRequired": ["DB_PASS"],
  "name": "ValidationError"
}

📘 Explanation

• missingRequired → Required variables not present in .env
• extraInEnv → Variables present in .env but not in schema
• missingInEnv → Schema variables missing from .env but not required

🧾 Example Output

❌ ValidationError:
Missing required variables: [ "DB_PASS" ]
Extra variables found: [ "OLD_API_KEY" ]

🧰 Typical Project Structure

npmfolder/
│
├── dist/
│
├── envExamples/
│   └── development-env
│
├── node_modules/
│
├── src/
│   ├── components/
│   │   ├── configenv.ts
│   │   ├── encrypt.ts
│   │   ├── error.ts
│   │   ├── sync.ts
│   │   ├── validation.ts
│   │   └── createfile.ts
│   │
│   ├── interfaces/
│   │   └── schema.ts
│   │
│   ├── options.ts
│   ├── index.ts
│   └── schema.ts
│
├── .env
├── .gitignore
├── package.json
├── package-lock.json
├── tsconfig.json
└── README.md

🤝 Contribution

We welcome contributions to EnvSync from the community!

🧩 How to Contribute

1. Fork the repository

2. Clone your fork locally

   git clone https://github.com/<your-username>/envsync-manager.git

3. Create a feature branch

   git checkout -b feature/your-feature-name

4. Make your changes and test locally

   npm run dev

5. Commit and push

   git commit -m "Added new feature or fixed issue"
   git push origin feature/your-feature-name

6. Open a Pull Request (PR)

   • Clearly describe your changes
   • Link any related issues
   • Ensure all tests pass before submission

🧪 Development Guidelines

• Follow TypeScript best practices
• Keep code modular and well-documented
• Use meaningful variable names
• Maintain consistent formatting (prettier / eslint)
• Write descriptive commit messages

🧠 Suggestions and Feedback

If you have ideas, bug reports, or feature requests — feel free to open an issue or start a discussion on GitHub!

🧑‍💻 Author

Raghavan P Software Developer Specialist GitHub • NPM

🪪 License

MIT License © 2025 Raghavan P