🌐 RemoteVars

RemoteVars is a modern Node.js library and CLI tool that lets you manage environment variables from remote sources — like GitHub, HTTP endpoints, or local JSON files — eliminating the need for .env files in your projects.

🚀 Features

• 🔒 Load configuration securely from:
  • GitHub repositories (private or public)
  • HTTP(S) endpoints
  • Local JSON files
• 🧠 Optional local cache for offline resilience
• ⚙️ CLI tool for pulling, printing, and loading variables
• 💻 Works with Node.js, Express, React, or any framework
• ☁️ Perfect for distributed teams and CI/CD setups

📦 Installation

Requires Node.js 18 or newer.

npm install -g remotevars

or for local development:

npm install remotevars --save-dev

Usage

CLI

Pull environment variables and save them to .env.local:

npx remotevars pull --provider=github --repo=myorg/configs --path=envs/dev.json

Run a command with remote variables

npx remotevars run production -- node server.js

The variables are passed only to the child process. RemoteVars does not write a .env file. The old load command cannot change its parent shell and is deprecated.

Print variable names

npx remotevars print --provider=local --filePath=./envs/dev.json

Values are replaced with [REDACTED]. Add --show-values to reveal them.

Clear local cache:

npx remotevars clear-cache

.remotevars.json

Define environments in .remotevars.json:

{
  "defaultEnv": "dev",
  "useCache": true,
  "cacheTtl": 300,
  "environments": {
    "dev": {
      "provider": "local",
      "filePath": "./envs/dev.json"
    },
    "production": {
      "provider": "github",
      "repo": "myorg/myconfigs",
      "path": "envs/production.json",
      "branch": "main",
      "tokenEnv": "GITHUB_TOKEN"
    }
  }
}

Cache

You can disable the caching system globally or per command.

Option 1: In the .remotevars.json

{
  "useCache": false
}

Option 2: CLI flag

npx remotevars pull --no-cache

When cache is disabled, RemoteVars always fetches fresh data from the provider and never stores or reads from the cache.

cacheTtl is the maximum cache age in seconds. Expired entries are ignored unless the command includes --allow-stale.

Supported providers

| Provider | Description | Required Options | |-----------|--------------|------------------| | github | Fetch from a GitHub repository | repo, path, optional branch, tokenEnv | | http | Fetch from an HTTP endpoint returning JSON | url, optional tokenEnv | | local | Load from a local JSON file | filePath |

Programmatic usage

You can also use RemoteVars directly in your code:

import { loadRemoteVars } from "remotevars";

await loadRemoteVars({
  provider: "github",
  repo: "myorg/myconfigs",
  path: "envs/dev.json",
  tokenEnv: "GITHUB_TOKEN",
  useCache: false
});

console.log(process.env.API_KEY);

🥪 Testing

Run unit tests:

npm test

🗺️ Roadmap

See ROADMAP.md for planned releases and priorities.

🧑‍💻 Author

Created by Jose R. Garcia
📦 GitHub: @jrgf

🪪 License

MIT License — feel free to use, modify, and distribute.

RemoteVars — Your environment, remotely controlled.