Environment Variables

Confect provides type-safe access to environment variables using Effect’s Config API. Environment variables are available in all function types and integrate seamlessly with Convex’s deployment system.

Overview

Type-Safe

Define schemas for environment variables

Effect Config

Use Effect’s Config API for validation

Convex Integration

Works with Convex environment variables

Default Values

Provide fallbacks for optional variables

Accessing Environment Variables

Use Effect’s Config API to access environment variables:

import { Config, Effect } from "effect";

const getAPIKey = Effect.gen(function* () {
  const apiKey = yield* Config.string("API_KEY");
  
  return apiKey;
});

Environment variables are accessed through process.env in Convex, just like in Node.js.

Config Types

Effect provides typed config accessors:

String Config

import { Config } from "effect";

const getDatabaseUrl = Effect.gen(function* () {
  const url = yield* Config.string("DATABASE_URL");
  return url;
});

Number Config

const getPort = Effect.gen(function* () {
  const port = yield* Config.number("PORT");
  return port;
});

Boolean Config

const isProduction = Effect.gen(function* () {
  const prod = yield* Config.boolean("IS_PRODUCTION");
  return prod;
});

Optional Config

const getOptionalKey = Effect.gen(function* () {
  const key = yield* Config.option(Config.string("OPTIONAL_KEY"));
  
  if (Option.isSome(key)) {
    console.log("Key found:", key.value);
  } else {
    console.log("Key not set");
  }
});

Config with Default

const getTimeout = Effect.gen(function* () {
  const timeout = yield* Config.withDefault(
    Config.number("TIMEOUT_MS"),
    5000
  );
  
  return timeout;
});

Setting Environment Variables

Set environment variables in your Convex deployment:

# Development
npx convex env set API_KEY "your-api-key"

# Production
npx convex env set --prod API_KEY "your-prod-api-key"

Environment variables are encrypted at rest and in transit by Convex.

Using in Functions

Access environment variables in your Confect functions:

confect/external.ts

import { FunctionImpl } from "@confect/server";
import { Effect, Config } from "effect";

const callExternalAPI = FunctionImpl.make(
  api,
  "external",
  "fetch",
  ({ endpoint }) =>
    Effect.gen(function* () {
      // Get API key from environment
      const apiKey = yield* Config.string("EXTERNAL_API_KEY");
      
      const response = yield* Effect.tryPromise(() =>
        fetch(`https://api.example.com/${endpoint}`, {
          headers: {
            "Authorization": `Bearer ${apiKey}`,
          },
        })
      );
      
      const data = yield* Effect.tryPromise(() => response.json());
      
      return data;
    }).pipe(Effect.orDie)
);

Structured Configuration

Create structured configuration objects:

config.ts

import { Config, Effect, Schema } from "effect";

const DatabaseConfig = Schema.Struct({
  host: Schema.String,
  port: Schema.Number,
  database: Schema.String,
  user: Schema.String,
  password: Schema.String,
});

const getDatabaseConfig = Effect.gen(function* () {
  const host = yield* Config.string("DB_HOST");
  const port = yield* Config.number("DB_PORT");
  const database = yield* Config.string("DB_NAME");
  const user = yield* Config.string("DB_USER");
  const password = yield* Config.string("DB_PASSWORD");
  
  return {
    host,
    port,
    database,
    user,
    password,
  };
});

Config Validation

Validate environment variables:

import { Config, Effect, Schema } from "effect";

const getEmailConfig = Effect.gen(function* () {
  const apiKey = yield* Config.string("EMAIL_API_KEY");
  
  // Validate API key format
  const validated = yield* Schema.decode(
    Schema.String.pipe(Schema.minLength(32)),
    apiKey
  );
  
  return validated;
});

Environment-Specific Config

const getEnvironment = Effect.gen(function* () {
  const env = yield* Config.withDefault(
    Config.string("ENVIRONMENT"),
    "development"
  );
  
  return env;
});

const getAPIUrl = Effect.gen(function* () {
  const env = yield* getEnvironment;
  
  const url = env === "production"
    ? yield* Config.string("PROD_API_URL")
    : yield* Config.string("DEV_API_URL");
  
  return url;
});

Common Patterns

API Keys

const callThirdPartyAPI = FunctionImpl.make(
  api,
  "integrations",
  "call",
  ({ data }) =>
    Effect.gen(function* () {
      const apiKey = yield* Config.string("THIRD_PARTY_API_KEY");
      
      const response = yield* Effect.tryPromise(() =>
        fetch("https://api.thirdparty.com/endpoint", {
          method: "POST",
          headers: {
            "Authorization": `Bearer ${apiKey}`,
            "Content-Type": "application/json",
          },
          body: JSON.stringify(data),
        })
      );
      
      return yield* Effect.tryPromise(() => response.json());
    }).pipe(Effect.orDie)
);

Database Connections

const connectToExternalDB = Effect.gen(function* () {
  const host = yield* Config.string("POSTGRES_HOST");
  const port = yield* Config.number("POSTGRES_PORT");
  const database = yield* Config.string("POSTGRES_DB");
  const user = yield* Config.string("POSTGRES_USER");
  const password = yield* Config.string("POSTGRES_PASSWORD");
  
  const pool = new Pool({
    host,
    port,
    database,
    user,
    password,
  });
  
  return pool;
});

Feature Flags

const isFeatureEnabled = (feature: string) =>
  Effect.gen(function* () {
    const enabled = yield* Config.withDefault(
      Config.boolean(`FEATURE_${feature.toUpperCase()}_ENABLED`),
      false
    );
    
    return enabled;
  });

const processData = FunctionImpl.make(
  api,
  "data",
  "process",
  ({ data }) =>
    Effect.gen(function* () {
      const useNewAlgorithm = yield* isFeatureEnabled("new_algorithm");
      
      if (useNewAlgorithm) {
        return yield* processWithNewAlgorithm(data);
      } else {
        return yield* processWithOldAlgorithm(data);
      }
    }).pipe(Effect.orDie)
);

Error Handling

Handle missing environment variables:

const getAPIKeyWithFallback = Effect.gen(function* () {
  const apiKey = yield* Config.string("API_KEY").pipe(
    Effect.catchAll(() =>
      Effect.gen(function* () {
        console.warn("API_KEY not set, using demo key");
        return "demo-api-key";
      })
    )
  );
  
  return apiKey;
});

Secrets Management

Never commit environment variables containing secrets to version control. Use Convex’s environment variable management instead.

# Set secrets via CLI
npx convex env set SECRET_KEY "your-secret"

# List environment variables (values are hidden)
npx convex env list

# Remove environment variable
npx convex env unset SECRET_KEY

Configuration Service

Create a reusable configuration service:

services/config.ts

import { Config, Effect, Context, Layer } from "effect";

interface AppConfig {
  readonly apiKey: string;
  readonly apiUrl: string;
  readonly timeout: number;
  readonly debug: boolean;
}

class AppConfig extends Context.Tag("AppConfig")<
  AppConfig,
  AppConfig
>() {}

const makeAppConfig = Effect.gen(function* () {
  const apiKey = yield* Config.string("API_KEY");
  const apiUrl = yield* Config.withDefault(
    Config.string("API_URL"),
    "https://api.example.com"
  );
  const timeout = yield* Config.withDefault(
    Config.number("TIMEOUT_MS"),
    5000
  );
  const debug = yield* Config.withDefault(
    Config.boolean("DEBUG"),
    false
  );
  
  return {
    apiKey,
    apiUrl,
    timeout,
    debug,
  };
});

export const AppConfigLive = Layer.effect(AppConfig, makeAppConfig);

// Usage
const useConfig = Effect.gen(function* () {
  const config = yield* AppConfig;
  
  console.log("API URL:", config.apiUrl);
  console.log("Timeout:", config.timeout);
});

Best Practices

Use Type-Safe Config

Always use Effect’s Config API instead of accessing process.env directly.

Provide Defaults

Use Config.withDefault for non-critical configuration.

Validate Early

Validate configuration at application startup, not at runtime.

Document Requirements

Document all required environment variables in your README.

Confect automatically provides a ConvexConfigProvider that reads from process.env. You don’t need to configure it manually.

Testing with Environment Variables

Mock environment variables in tests:

import { ConfigProvider, Effect, Layer } from "effect";

const testConfig = ConfigProvider.fromMap(
  new Map([
    ["API_KEY", "test-api-key"],
    ["API_URL", "http://localhost:3000"],
    ["DEBUG", "true"],
  ])
);

const testLayer = Layer.setConfigProvider(testConfig);

// Use in tests
const testEffect = Effect.gen(function* () {
  const apiKey = yield* Config.string("API_KEY");
  expect(apiKey).toBe("test-api-key");
}).pipe(Effect.provide(testLayer));

Next Steps

Functions

Use config in your functions

Node Actions

Access environment in Node actions

HTTP API

Configure HTTP endpoints

Effect Config

Learn more about Effect Config

Getting Started

Concepts

Server

Clients

Guides

API Reference

Environment Variables

Overview

Type-Safe

Effect Config

Convex Integration

Default Values

Accessing Environment Variables

Config Types

String Config

Number Config

Boolean Config

Optional Config

Config with Default

Setting Environment Variables

Using in Functions

Structured Configuration

Config Validation

Environment-Specific Config

Common Patterns

API Keys

Database Connections

Feature Flags

Error Handling

Secrets Management

Configuration Service

Best Practices

Testing with Environment Variables

Next Steps

Functions

Node Actions

HTTP API

Effect Config

Getting Started

Concepts

Server

Clients

Guides

API Reference

Documentation Index

​Overview

Type-Safe

Effect Config

Convex Integration

Default Values

​Accessing Environment Variables

​Config Types

​String Config

​Number Config

​Boolean Config

​Optional Config

​Config with Default

​Setting Environment Variables

​Using in Functions

​Structured Configuration

​Config Validation

​Environment-Specific Config

​Common Patterns

​API Keys

​Database Connections

​Feature Flags

​Error Handling

​Secrets Management

​Configuration Service

​Best Practices

​Testing with Environment Variables

​Next Steps

Functions

Node Actions

HTTP API

Effect Config

Overview

Accessing Environment Variables

Config Types

String Config

Number Config

Boolean Config

Optional Config

Config with Default

Setting Environment Variables

Using in Functions

Structured Configuration

Config Validation

Environment-Specific Config

Common Patterns

API Keys

Database Connections

Feature Flags

Error Handling

Secrets Management

Configuration Service

Best Practices

Testing with Environment Variables

Next Steps