@hairy/lnv

Loading environment variables in Next.js and other frameworks can be quite cumbersome, and using dotenv or vault at runtime is also inconvenient. That's why my created this tool

I think it can solve some of the problems you encounter in next.js or dotenv or more. 🛠️

✅ Features

• 🔄 Multi-mode support, allowing you to load .env|.env.prod|.env.local simultaneously
• 🔐 Support for vault.dotenv remote environment variable loading and multi-environment switching
• 🛡️ Direct writing to process.env, no local storage, more secure and reliable
• 📁 Environment variables lookup, naturally supports monorepo architecture
• 🏃‍♂️ Run any JS and scripts with environment variables
• 📜 Define your integration config with lnv.config.ts

📦 Install

npm install @hairy/lnv
# or globally
npm install -g @hairy/lnv

🚀 Usage

Modify the scripts field in your package.json:

{
  "scripts": {
    "dev": "lnv staging -- next dev"
  }
}

This will launch next dev with the .env.staging environment variables. ✨

You can also include any run parameters, for example:

lnv prod -- next dev --turbopack

🌿 Default Environment Variables

You don't need any action, the .env.local and .env environment variables will be automatically loaded by default.

🔒 Vault Environment Variables

npx dotenv-vault@latest new
npx dotenv-vault@latest vlt_...

npx dotenv-vault@latest pull
npx dotenv-vault@latest build
```sh
# Create and connect to vault repository
npx dotenv-vault@latest new
# Connect to an existing vault repository
npx dotenv-vault@latest vlt_...

# And encrypt your environment variables:
npx dotenv-vault@latest pull
# or
npx dotenv-vault@latest build

Next, you need to create a .env.key or .env.keys file in your project root directory and write the DOTENV_KEY:

# .env.key
DOTENV_KEY = dotenv://...?environment=development

# or

# .env.keys
DOTENV_KEY_DEVELOPMENT = dotenv://...?environment=development
DOTENV_KEY_CI = dotenv://:...?environment=ci
DOTENV_KEY_STAGING = dotenv://:...?environment=staging
DOTENV_KEY_PRODUCTION = dotenv://:...?environment=production

Finally, you can use the lnv command to include vault environment variables:

# Load environment variables based on .env.vault and .env.key
lnv vault -- node index.js
# Load ci environment variables based on .env.vault and .env.keys
lnv vault:ci -- node index.js

🚢 Vercel with Vault

If you need to deploy on Vercel, you need to add environment variables in your Vercel project:

npx vercel@latest env add DOTENV_KEY

lnv vault will automatically load environment variables based on .env.vault. 🎉

✍️ Manual with environment variables

You can manual load environment variables with the -v|--value parameter:

lnv -v KEY1=value1 -v KEY2=value2 -- node index.js

By adding the $prefix, you can reference the value of an environment variable in the settings or command line:

lnv -v KEY1=value1 -v KEY2=value1 -v KEY3=$KEY1_$KEY2 -- node index.js
## or
lnv -v KEY1=value1 -- node -e 'console.log($KEY1)'

📝 Define Your integration Config

lnv.config.ts is used to add actionable command-line scripts and default injected environment variables.

import fs from 'node:fs/promises'
import { defineConfig } from '@hairy/lnv'

const config = defineConfig({
  /**
   * Environment variable injection, applied to all LNV scripts
   */
  injects: {
    /**
     * Inject before reading environment variables
     */
    before: {
      DB_TYPE: 'mysql',
      DB_HOST: 'localhost',
      DB_PORT: '3306',
      DB_USER: 'root',
    },

    /**
     * Default loaded environment variable entries
     */
    entries: ['local', 'vault', 'remote'],

    /**
     * Inject after reading environment variables
     */
    after: {
      DATABASE_URL: '$DB_TYPE://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME',
    },
  },
})

export default config

The 'scripts' field is used to define operable command-line scripts, which can be understood as scripts in package.json, but with more powerful capabilities.

const config = defineConfig({
  scripts: {
    // command: npm run lnv deploy
    deploy: {
      message: 'Deploy the application',
      prompts: [
        {
          key: 'network',
          type: 'select', // or 'text' or 'multiselect' or 'confirm' or 'password' or 'handler(custom function)'
          message: 'Select Your Network',
          options: [
            { value: 'moonchain', label: 'Moonchain' },
            { value: 'moonchainGeneva', label: 'Moonchain Geneva' },
          ],
        },
        {
          key: 'modulePath',
          type: 'select',
          message: 'Select the module you want to deploy',
          options: async () => {
            const files = await fs.readdir('./ignition/modules')
            return files.map(file => ({
              value: `./ignition/modules/${file}`,
              label: file.replace('.ts', ''),
            }))
          },
        },
      ],
      command: 'hardhat --build-profile production ignition deploy $modulePath --network $network',
    },
    // command: npm run lnv dev
    dev: {
      message: 'Run the development server',
      command: {
        message: 'Select the project you want to run',
        options: [
          {
            value: 'cd packages/project-1 && npm run dev',
            label: 'project-1',
          },
          {
            value: 'cd packages/project-2 && npm run dev',
            label: 'project-2',
          },
        ],
      },
    },
  },
})

export default config

🔍️ Options

lnv <entry|script> [args]

args:
      --version       show version                                               [boolean]
  -v, --value         set environment variables                                  [array]
  -e, --entry         Explicit loading of entry, same as lnv <entry>             [string]
  -r, --run           load runtime environment and run any scripts               [string]
      --write         expose and write environment variables                     [boolean]
  -d, --depth         depth find and merge environment variables                 [boolean]
  -h, --help          show help                                                  [boolean]

📄 License

MIT License © Hairyf