or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

environment-loading.md environment-population.md file-parsing.md index.md vault-decryption.md

tile.json

File Parsing

Low-level parsing functionality for converting .env file contents into JavaScript objects without modifying process.env. Ideal for custom processing workflows and when you need to inspect .env contents before loading.

Capabilities

Parse Function

Parses a string or buffer in .env file format into a JavaScript object without modifying process.env.

/**
 * Parses a string or buffer in .env file format into a JavaScript object
 * @param src - Contents to be parsed (string or Buffer)
 * @returns Object with keys and values based on src
 */
function parse<T extends DotenvParseOutput = DotenvParseOutput>(
  src: string | Buffer
): T;

Usage Examples:

const dotenv = require('dotenv');
const fs = require('fs');

// Parse file contents manually
const envContents = fs.readFileSync('.env', 'utf8');
const parsed = dotenv.parse(envContents);
console.log(parsed);
// { DATABASE_URL: 'postgres://...', API_KEY: 'secret123' }

// Parse Buffer
const buffer = fs.readFileSync('.env'); // Returns Buffer
const parsedBuffer = dotenv.parse(buffer);

// Parse string directly
const envString = 'DB_HOST=localhost\nDB_PORT=5432\nDEBUG=true';
const parsedString = dotenv.parse(envString);
console.log(parsedString);
// { DB_HOST: 'localhost', DB_PORT: '5432', DEBUG: 'true' }

// Custom processing before loading
const envData = dotenv.parse(fs.readFileSync('.env', 'utf8'));
// Transform values before setting in process.env
Object.keys(envData).forEach(key => {
  process.env[key] = envData[key].toUpperCase();
});

Parsing Rules

Variable Assignment

Supports various assignment formats:

# Standard assignment
DATABASE_URL=postgres://localhost/mydb
API_KEY=secret123

# With export (ignored)
export NODE_ENV=production

# Colon syntax
REDIS_URL: redis://localhost:6379

# With spaces around equals
DB_NAME = myapp

Quote Handling

Handles single, double, and backtick quotes:

const envContent = `
SINGLE_QUOTED='single value'
DOUBLE_QUOTED="double value"
BACKTICK_QUOTED=\`backtick value\`
UNQUOTED=unquoted value
`;

const parsed = dotenv.parse(envContent);
console.log(parsed);
// {
//   SINGLE_QUOTED: 'single value',
//   DOUBLE_QUOTED: 'double value', 
//   BACKTICK_QUOTED: 'backtick value',
//   UNQUOTED: 'unquoted value'
// }

Escape Sequences

Double-quoted values support escape sequences:

const envContent = `
BASIC="hello world"
NEWLINES="line 1\\nline 2\\nline 3"
RETURNS="line 1\\rline 2"
MIXED="quotes: \\"hello\\" and newlines: \\n"
`;

const parsed = dotenv.parse(envContent);
console.log(parsed.NEWLINES);
// "line 1
// line 2
// line 3"

Comments

Lines starting with # are treated as comments:

const envContent = `
# Database configuration
DATABASE_URL=postgres://localhost/mydb
# API_KEY=disabled_key
API_SECRET=abc123
`;

const parsed = dotenv.parse(envContent);
console.log(parsed);
// { DATABASE_URL: 'postgres://localhost/mydb', API_SECRET: 'abc123' }

Empty Values

Handles empty and undefined values:

const envContent = `
EMPTY_VALUE=
NULL_VALUE=
UNDEFINED_VALUE
WHITESPACE_VALUE=   
`;

const parsed = dotenv.parse(envContent);
console.log(parsed);
// {
//   EMPTY_VALUE: '',
//   NULL_VALUE: '',
//   UNDEFINED_VALUE: '',
//   WHITESPACE_VALUE: '   '
// }

Advanced Usage

Multi-line Processing

Parse multiple .env files and merge results:

const dotenv = require('dotenv');
const fs = require('fs');

function parseMultipleFiles(filePaths) {
  const merged = {};
  
  filePaths.forEach(filePath => {
    try {
      const content = fs.readFileSync(filePath, 'utf8');
      const parsed = dotenv.parse(content);
      Object.assign(merged, parsed);
    } catch (error) {
      console.warn(`Could not parse ${filePath}:`, error.message);
    }
  });
  
  return merged;
}

const config = parseMultipleFiles(['.env.local', '.env']);

Validation and Transformation

Validate and transform parsed values:

const dotenv = require('dotenv');
const fs = require('fs');

function parseAndValidate(filePath, schema) {
  const content = fs.readFileSync(filePath, 'utf8');
  const parsed = dotenv.parse(content);
  const validated = {};
  
  Object.keys(schema).forEach(key => {
    const value = parsed[key];
    const validator = schema[key];
    
    if (!value && validator.required) {
      throw new Error(`Missing required environment variable: ${key}`);
    }
    
    validated[key] = validator.transform ? validator.transform(value) : value;
  });
  
  return validated;
}

// Usage
const schema = {
  PORT: { 
    required: true, 
    transform: (val) => parseInt(val, 10) 
  },
  DEBUG: { 
    transform: (val) => val === 'true' 
  },
  DATABASE_URL: { 
    required: true 
  }
};

const config = parseAndValidate('.env', schema);

Custom File Reading

Parse from different sources:

const dotenv = require('dotenv');
const https = require('https');

// Parse from HTTP response
function parseFromUrl(url) {
  return new Promise((resolve, reject) => {
    https.get(url, (res) => {
      let data = '';
      res.on('data', (chunk) => data += chunk);
      res.on('end', () => {
        try {
          const parsed = dotenv.parse(data);
          resolve(parsed);
        } catch (error) {
          reject(error);
        }
      });
    }).on('error', reject);
  });
}

// Parse from environment variable
const envFromVar = dotenv.parse(process.env.DOTENV_CONFIG || '');

Return Types

interface DotenvParseOutput {
  [name: string]: string;
}

All parsed values are strings. Type conversion must be handled separately:

const parsed = dotenv.parse('PORT=3000\nDEBUG=true');

// Manual type conversion
const config = {
  port: parseInt(parsed.PORT, 10),
  debug: parsed.DEBUG === 'true',
  host: parsed.HOST || 'localhost'
};