tessl/npm-parcel--types

TypeScript type definitions for the Parcel bundler providing comprehensive interfaces for build configuration, plugins, assets, and bundle management

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Environment System

Name: tessl/npm-parcel--types
Author: tessl

Target environment configuration, engine requirements, and feature detection for different runtime contexts and optimization settings.

Capabilities

Environment Interface

Complete environment configuration with context detection and feature support.

/**
 * Build environment interface defining target runtime context
 */
interface Environment {
  /** Unique environment identifier */
  readonly id: string;
  /** Runtime context (browser, node, worker, etc.) */
  readonly context: EnvironmentContext;
  /** Engine version requirements */
  readonly engines: Engines;
  /** Node modules inclusion strategy */
  readonly includeNodeModules: 
    | boolean 
    | Array<PackageName> 
    | {[PackageName]: boolean};
  /** Output module format */
  readonly outputFormat: OutputFormat;
  /** Source type (script or module) */
  readonly sourceType: SourceType;
  /** Whether this is a library build */
  readonly isLibrary: boolean;
  /** Whether output should be optimized */
  readonly shouldOptimize: boolean;
  /** Whether scope hoisting is enabled */
  readonly shouldScopeHoist: boolean;
  /** Source map configuration */
  readonly sourceMap: ?TargetSourceMapOptions;
  /** Location that created this environment */
  readonly loc: ?SourceLocation;
  
  /** Check if context is browser-based */
  isBrowser(): boolean;
  /** Check if context is Node.js-based */
  isNode(): boolean;
  /** Check if context is server-side */
  isServer(): boolean;
  /** Check if context is Electron-based */
  isElectron(): boolean;
  /** Check if context is a worker */
  isWorker(): boolean;
  /** Check if context is a worklet */
  isWorklet(): boolean;
  /** Check if context is isolated (can't access parent bundles) */
  isIsolated(): boolean;
  /** Check if engines meet minimum version requirements */
  matchesEngines(minVersions: VersionMap, defaultValue?: boolean): boolean;
  /** Check if environment supports a specific feature */
  supports(feature: EnvironmentFeature, defaultValue?: boolean): boolean;
}

Environment Context

Runtime context types for different execution environments.

/**
 * Runtime context types
 */
type EnvironmentContext =
  | 'browser'           // Web browser main thread
  | 'web-worker'        // Web Worker
  | 'service-worker'    // Service Worker
  | 'worklet'           // Worklet (Audio, CSS, etc.)
  | 'node'              // Node.js runtime
  | 'electron-main'     // Electron main process
  | 'electron-renderer' // Electron renderer process
  | 'react-client'      // React client-side rendering
  | 'react-server';     // React server-side rendering

Output Format

Module format for bundle output.

/**
 * JavaScript module format for bundle output
 */
type OutputFormat = 
  | 'esmodule'    // ES modules (import/export)
  | 'commonjs'    // CommonJS (require/module.exports)
  | 'global';     // Global variable assignment

Source Type

Source code interpretation mode.

/**
 * Source code type for parsing and execution
 */
type SourceType = 
  | 'script'    // Script mode (no import/export)
  | 'module';   // Module mode (import/export allowed)

Environment Options

Options for creating environment instances.

/**
 * Options for creating an Environment instance
 */
interface EnvironmentOptions {
  /** Runtime context */
  context?: EnvironmentContext;
  /** Engine version requirements */
  engines?: Engines;
  /** Node modules inclusion strategy */
  includeNodeModules?: 
    | boolean 
    | Array<PackageName> 
    | {[PackageName]: boolean};
  /** Output module format */
  outputFormat?: OutputFormat;
  /** Source type */
  sourceType?: SourceType;
  /** Whether this is a library build */
  isLibrary?: boolean;
  /** Whether to optimize output */
  shouldOptimize?: boolean;
  /** Whether to enable scope hoisting */
  shouldScopeHoist?: boolean;
  /** Source map configuration */
  sourceMap?: ?TargetSourceMapOptions;
  /** Location information */
  loc?: ?SourceLocation;
}

Engine Requirements

Browser and runtime version requirements.

/**
 * Engine version requirements for different runtimes
 */
interface Engines {
  /** Browser version requirements (browserslist format) */
  browsers?: string | Array<string>;
  /** Electron version requirement */
  electron?: SemverRange;
  /** Node.js version requirement */
  node?: SemverRange;
  /** Parcel version requirement */
  parcel?: SemverRange;
}

/**
 * Resolved browser versions
 * Example: { chrome: '91', firefox: '89', safari: '14.1' }
 */
interface VersionMap {
  [browserName: string]: string;
}

Environment Features

Feature detection for environment capabilities.

/**
 * Environment feature capabilities
 */
type EnvironmentFeature =
  | 'esmodules'           // ES module support
  | 'dynamic-import'      // Dynamic import() support
  | 'worker-module'       // Worker modules support
  | 'service-worker-module' // Service worker modules
  | 'import-meta-url'     // import.meta.url support
  | 'import-meta-resolve' // import.meta.resolve support
  | 'arrow-functions'     // Arrow function support
  | 'global-this';        // globalThis support

Target Interface

Build target combining environment with output configuration.

/**
 * Build target representing output configuration
 */
interface Target {
  /** Output entry file name */
  readonly distEntry: ?FilePath;
  /** Output directory */
  readonly distDir: FilePath;
  /** Target environment */
  readonly env: Environment;
  /** Target name */
  readonly name: string;
  /** Public URL for assets */
  readonly publicUrl: string;
  /** Location that created this target */
  readonly loc: ?SourceLocation;
}

Usage Examples:

import type { 
  Environment, 
  EnvironmentOptions, 
  EnvironmentContext, 
  OutputFormat 
} from '@parcel/types';

// Create environment for different contexts
const browserEnv: EnvironmentOptions = {
  context: 'browser',
  outputFormat: 'esmodule',
  engines: {
    browsers: ['> 1%', 'last 2 versions']
  },
  shouldOptimize: true,
  shouldScopeHoist: true
};

const nodeEnv: EnvironmentOptions = {
  context: 'node',
  outputFormat: 'commonjs',
  engines: {
    node: '>= 14'
  },
  includeNodeModules: false,
  isLibrary: true
};

const workerEnv: EnvironmentOptions = {
  context: 'web-worker',
  outputFormat: 'esmodule',
  engines: {
    browsers: ['Chrome >= 80', 'Firefox >= 72']
  },
  sourceType: 'module'
};

// Check environment capabilities
function checkEnvironmentCapabilities(env: Environment) {
  if (env.isBrowser()) {
    console.log('Browser environment detected');
    
    if (env.supports('esmodules')) {
      console.log('ES modules supported');
    }
    
    if (env.supports('dynamic-import')) {
      console.log('Dynamic imports supported');
    }
  }
  
  if (env.isNode()) {
    console.log('Node.js environment detected');
    
    if (env.matchesEngines({ node: '16' })) {
      console.log('Node.js 16+ detected');
    }
  }
  
  if (env.isWorker()) {
    console.log('Worker environment detected');
    
    if (env.supports('worker-module')) {
      console.log('Worker modules supported');
    }
  }
}

// Environment-specific optimization
function optimizeForEnvironment(env: Environment) {
  if (env.shouldOptimize) {
    if (env.isBrowser()) {
      // Browser optimizations
      if (env.shouldScopeHoist) {
        console.log('Enabling scope hoisting for browser');
      }
      
      if (env.supports('esmodules')) {
        console.log('Using ES modules for modern browsers');
      }
    }
    
    if (env.isNode()) {
      // Node.js optimizations
      console.log('Optimizing for Node.js runtime');
      
      if (env.outputFormat === 'commonjs') {
        console.log('Using CommonJS format');
      }
    }
  }
}

// Engine version checking
function checkEngineSupport(env: Environment) {
  const modernBrowsers = {
    chrome: '80',
    firefox: '72',
    safari: '13'
  };
  
  if (env.matchesEngines(modernBrowsers)) {
    console.log('Modern browser features available');
    return true;
  }
  
  console.log('Legacy browser support needed');
  return false;
}

// Context-specific feature detection
function getContextCapabilities(context: EnvironmentContext) {
  switch (context) {
    case 'browser':
      return ['esmodules', 'dynamic-import', 'import-meta-url'];
    
    case 'web-worker':
      return ['esmodules', 'worker-module', 'import-meta-url'];
    
    case 'service-worker':
      return ['esmodules', 'service-worker-module'];
    
    case 'node':
      return ['esmodules', 'dynamic-import', 'global-this'];
    
    case 'electron-renderer':
      return ['esmodules', 'dynamic-import', 'import-meta-url'];
    
    default:
      return [];
  }
}

Install with Tessl CLI