or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

browser-compatibility.mdbuffer-operations.mdform-construction.mdheaders-boundaries.mdhttp-submission.mdindex.mdlength-calculation.md
tile.json

browser-compatibility.mddocs/

Browser Compatibility

Browser compatibility layer that provides fallback to native FormData in browser environments, allowing the same import syntax to work across Node.js and browser contexts.

Capabilities

Browser Module Export

The browser entry point exports the native browser FormData implementation instead of the Node.js version.

/**
 * Browser compatibility export (lib/browser.js)
 * In browser environments, exports native FormData
 * Falls back to window.FormData if self is not available
 */
module.exports = typeof self === 'object' ? self.FormData : window.FormData;

Usage Examples:

// Same import works in both environments
const FormData = require('form-data');

// In Node.js: Gets the custom form-data implementation
// In Browser: Gets native window.FormData or self.FormData

const form = new FormData();

// In browsers, this uses native FormData API:
form.append('file', fileInput.files[0]);
form.append('text', 'value');

// Can use with fetch() directly in browsers
fetch('/upload', {
  method: 'POST',
  body: form // Native FormData, no additional headers needed
});

Package Configuration

The browser field in package.json automatically routes browser bundlers to use the browser-specific implementation:

{
  "main": "./lib/form_data",
  "browser": "./lib/browser",
  "typings": "./index.d.ts"
}

Environment Detection

The browser module uses environment detection to provide the appropriate FormData implementation:

// Checks for 'self' first (Web Workers, Service Workers)
typeof self === 'object' ? self.FormData : 
// Falls back to 'window' (main browser thread)
window.FormData

Environment Support:

  • Main Browser Thread: Uses window.FormData
  • Web Workers: Uses self.FormData
  • Service Workers: Uses self.FormData
  • Node.js: Uses the full form-data implementation from ./lib/form_data

Bundler Integration

Modern bundlers automatically use the browser field:

Webpack:

// Webpack automatically resolves to lib/browser.js in browser builds
import FormData from 'form-data';

Browserify:

// Use browser transform for automatic resolution
const FormData = require('form-data');

Rollup:

// Configure browser field resolution
export default {
  input: 'src/main.js',
  output: { file: 'bundle.js', format: 'iife' },
  plugins: [
    resolve({ browser: true }),
    commonjs()
  ]
};

Native vs Custom Implementation

In Browser Environments:

  • Uses native browser FormData API
  • Automatic content-type handling by fetch/XMLHttpRequest
  • No need for manual boundary or header management
  • Direct file upload support from <input type="file">
  • Streaming not applicable (browsers handle this internally)

In Node.js Environments:

  • Uses custom form-data implementation
  • Full control over boundaries, headers, and streaming
  • Manual content-type and content-length management
  • Support for file streams, HTTP responses, and custom streams
  • Advanced features like length calculation and custom boundaries

Cross-Environment Usage

const FormData = require('form-data');

function createUploadForm(fileData, metadata) {
  const form = new FormData();
  
  if (typeof window !== 'undefined') {
    // Browser environment - fileData is likely a File object
    form.append('file', fileData);
    form.append('metadata', JSON.stringify(metadata));
    
    // Use with fetch (headers handled automatically)
    return fetch('/upload', {
      method: 'POST',
      body: form
    });
  } else {
    // Node.js environment - fileData might be a stream
    form.append('file', fileData);
    form.append('metadata', JSON.stringify(metadata));
    
    // Need to handle headers manually
    return form.submit({
      host: 'api.example.com',
      path: '/upload',
      headers: form.getHeaders()
    });
  }
}

TypeScript Compatibility

The TypeScript definitions work across both environments:

import FormData from 'form-data';

// Type definitions cover both native and custom implementations
const form = new FormData();
form.append('field', 'value');

// In browsers: uses native FormData types
// In Node.js: uses custom form-data types

Limitations in Browser Mode

When using the browser compatibility layer, certain Node.js-specific features are not available:

const FormData = require('form-data');

if (typeof window !== 'undefined') {
  // These methods won't be available in browser mode:
  // form.submit() - Use fetch() instead
  // form.getHeaders() - Headers handled automatically  
  // form.getLength() - Not needed in browsers
  // form.setBoundary() - Handled by browser
  // form.pipe() - Not applicable in browsers
}