motoko-env (Beta)

A simple utility to make environment variables available in Motoko. This library generates a Motoko module (env.mo) from your .env file, allowing you to easily access environment variables in your Motoko projects.

⚠️ This package is currently in beta. API may change in future releases.

Installation

# Install globally
npm install -g motoko-env

# Or run directly with npx
npx motoko-env generate

Usage

1. Create a .env file in your project root:

API_URL=https://example.com/api
CANISTER_ID=rrkah-fqaaa-aaaaa-aaaaq-cai

2. Run the generate command:

npx motoko-env generate

3. Import the generated module in your Motoko code:

import Env "../env";

actor {
  public func getApiUrl() : async Text {
    return Env.API_URL;
  };
}

Features

• Automatically generates a type-safe Motoko module from your .env file
• Updates .gitignore to prevent committing sensitive environment variables
• Detects and handles existing env.mo files

Best Practices

• NEVER commit your env.mo file to version control
• Use different .env files for different environments (development, staging, production)
• Keep sensitive information like API keys and secrets in environment variables

File Structure

After running motoko-env generate, the tool will:

1. Read your .env file in the project root
2. Generate an env.mo file directly in the src directory
3. Update .gitignore to protect sensitive files

your-project/
├── .env              # Your environment variables (DO NOT COMMIT)
├── .gitignore        # Updated to ignore env.mo and .env
├── dfx.json          # Your dfx project configuration
└── src/
    ├── env.mo        # Generated Motoko module (DO NOT COMMIT)
    ├── your_canister/
    └── another_canister/

Canisters can then import it directly with import Env "../env";

Security Considerations

This package does not encrypt or protect your environment variables in any way. The generated env.mo file contains your environment variables in plain text and should be treated as sensitive.

Environment variables in Motoko canister actors will be stored in the Wasm module and can be inspected by querying the canister's module. Do not include sensitive API keys or secrets that should remain private.