tessl/npm-parcel-bundler

Blazing fast, zero configuration web application bundler

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Asset System

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

The Parcel Asset System is an extensible framework for processing different file types during the build process. Each asset type handles parsing, dependency collection, transformation, and code generation for specific file formats.

Capabilities

Base Asset Class

The foundation class that all asset types extend, providing common functionality for file processing.

/**
 * Base Asset class for all file types
 * @param name - Absolute file path
 * @param options - Asset processing options
 */
class Asset {
  constructor(name, options);
  
  /** Load file contents from disk */
  load();
  
  /** Parse file contents into AST or structured data */
  parse(code);
  
  /** Extract dependencies from parsed content */
  collectDependencies();
  
  /** Apply transformations to the asset */
  transform();
  
  /** Generate output code for different targets */
  generate();
  
  /** Add a dependency to this asset */
  addDependency(name, opts);
  
  /** Check if asset might have dependencies */
  mightHaveDependencies();
  
  /** Determine if asset should be invalidated */
  shouldInvalidate(cacheData);
}

Usage Examples:

// Create custom asset type
class CustomAsset extends Asset {
  async parse(code) {
    // Parse the file contents
    return customParser(code);
  }
  
  collectDependencies() {
    // Extract dependencies from AST
    this.addDependency('./helper.js');
  }
  
  generate() {
    // Generate output code
    return { js: this.generateJS() };
  }
}

// Register custom asset type
bundler.addAssetType('.custom', CustomAsset);

Asset Properties

Core properties available on all Asset instances:

interface AssetProperties {
  /** Unique asset identifier */
  id: string | null;
  
  /** Absolute file path */
  name: string;
  
  /** Base filename */
  basename: string;
  
  /** Path relative to project root */
  relativeName: string;
  
  /** File extension without dot */
  type: string;
  
  /** Raw file contents */
  contents: string | Buffer | null;
  
  /** Parsed AST or structured data */
  ast: any;
  
  /** Generated outputs by type */
  generated: { [type: string]: any } | null;
  
  /** Content hash for caching */
  hash: string | null;
  
  /** Source maps */
  sourceMaps: any;
  
  /** Asset dependencies */
  dependencies: Map<string, any>;
  
  /** Resolved dependency assets */
  depAssets: Map<string, Asset>;
  
  /** Bundle containing this asset */
  parentBundle: Bundle | null;
  
  /** All bundles containing this asset */
  bundles: Set<Bundle>;
  
  /** Build timing information */
  startTime: number;
  endTime: number;
  buildTime: number;
  
  /** Bundle size information */
  bundledSize: number;
}

JavaScript Assets

JSAsset Class

Processes JavaScript files with Babel transformations, dependency extraction, and code generation.

/**
 * JavaScript asset processor with Babel support
 * Handles: .js, .jsx, .es6, .jsm, .mjs files
 */
class JSAsset extends Asset {
  /** Parse JavaScript code into Babel AST */
  parse(code);
  
  /** Extract imports, requires, and dynamic imports */
  collectDependencies();
  
  /** Apply Babel transforms and optimizations */
  transform();
  
  /** Generate JavaScript output with source maps */
  generate();
  
  /** Check if code might contain dependencies */
  mightHaveDependencies();
}

Features:

ES6+ syntax transformation via Babel
CommonJS and ES modules support
Dynamic import code splitting
Environment variable injection
Global variable handling
Tree shaking preparation

TypeScriptAsset Class

Processes TypeScript files with type checking and compilation.

/**
 * TypeScript asset processor
 * Handles: .ts, .tsx files
 */
class TypeScriptAsset extends Asset {
  /** Parse TypeScript code with type information */
  parse(code);
  
  /** Apply TypeScript compiler transformations */
  transform();
  
  /** Generate JavaScript output from TypeScript */
  generate();
}

Features:

TypeScript compilation to JavaScript
Type checking (configurable)
JSX support in .tsx files
Source map generation
tsconfig.json configuration support

Other JavaScript Variants

/** CoffeeScript asset processor (.coffee) */
class CoffeeScriptAsset extends Asset;

/** Vue Single File Component processor (.vue) */
class VueAsset extends Asset;

/** ReasonML asset processor (.ml, .re) */
class ReasonAsset extends Asset;

/** Elm asset processor (.elm) */
class ElmAsset extends Asset;

/** Kotlin asset processor (.kt) */
class KotlinAsset extends Asset;

/** Rust asset processor (.rs) */
class RustAsset extends Asset;

Stylesheet Assets

CSSAsset Class

Processes CSS files with PostCSS transformations and dependency resolution.

/**
 * CSS asset processor with PostCSS support
 * Handles: .css, .pcss, .postcss files
 */
class CSSAsset extends Asset {
  /** Parse CSS with PostCSS */
  parse(code);
  
  /** Extract @import and url() dependencies */
  collectDependencies();
  
  /** Apply PostCSS plugins and transformations */
  transform();
  
  /** Generate CSS output with source maps */
  generate();
}

Features:

PostCSS plugin system
CSS imports resolution
URL rewriting for assets
Source map support
CSS Modules support
Autoprefixer integration

Preprocessor Assets

/** Sass/SCSS asset processor (.sass, .scss) */
class SASSAsset extends Asset {
  /** Compile Sass to CSS using node-sass or Dart Sass */
  transform();
}

/** Less asset processor (.less) */
class LESSAsset extends Asset {
  /** Compile Less to CSS */
  transform();
}

/** Stylus asset processor (.styl, .stylus) */
class StylusAsset extends Asset {
  /** Compile Stylus to CSS */
  transform();
}

/** SugarSS asset processor (.sss) */
class SSSAsset extends Asset {
  /** Process SugarSS syntax to CSS */
  transform();
}

Markup Assets

HTMLAsset Class

Processes HTML files with dependency extraction and template processing.

/**
 * HTML asset processor
 * Handles: .html, .htm files
 */
class HTMLAsset extends Asset {
  /** Parse HTML using PostHTML */
  parse(code);
  
  /** Extract script, link, img, and other asset references */
  collectDependencies();
  
  /** Apply PostHTML transforms */
  transform();
  
  /** Generate HTML output */
  generate();
}

Features:

Script and stylesheet injection
Asset URL rewriting
Image optimization integration
Template variable substitution
PostHTML plugin support

Template Assets

/** Pug template processor (.jade, .pug) */
class PugAsset extends Asset {
  /** Compile Pug templates to HTML */
  transform();
}

Data Format Assets

JSON Assets

/** JSON asset processor (.json, .json5) */
class JSONAsset extends Asset {
  /** Parse JSON/JSON5 data */
  parse(code);
  
  /** Generate JavaScript module from JSON */
  generate();
}

/** JSON-LD asset processor (.jsonld) */
class JSONLDAsset extends Asset;

Configuration Assets

/** YAML asset processor (.yaml, .yml) */
class YAMLAsset extends Asset {
  /** Parse YAML and convert to JavaScript */
  parse(code);
}

/** TOML asset processor (.toml) */
class TOMLAsset extends Asset {
  /** Parse TOML and convert to JavaScript */
  parse(code);
}

Specialized Assets

GraphQL Assets

/** GraphQL asset processor (.gql, .graphql) */
class GraphqlAsset extends Asset {
  /** Parse GraphQL queries and schemas */
  parse(code);
  
  /** Generate JavaScript modules from GraphQL */
  generate();
}

Shader Assets

/** GLSL shader processor (.glsl, .vert, .frag) */
class GLSLAsset extends Asset {
  /** Process GLSL shaders */
  parse(code);
  
  /** Generate string modules for shaders */
  generate();
}

WebAssembly Assets

/** WebAssembly processor (.wasm) */
class WASMAsset extends Asset {
  /** Load and optimize WASM binary */
  load();
  
  /** Generate loader code for WASM */
  generate();
}

Raw Assets

/** Raw file processor (fallback for unknown types) */
class RawAsset extends Asset {
  /** Copy files without processing */
  generate();
}

/** Glob pattern processor */
class GlobAsset extends Asset {
  /** Resolve glob patterns to file dependencies */
  collectDependencies();
}

Asset Registration

Built-in Asset Types

Parcel includes built-in support for these file extensions:

// JavaScript and variants
'.js', '.jsx', '.es6', '.jsm', '.mjs'  // JSAsset
'.ts', '.tsx'                          // TypeScriptAsset
'.coffee'                              // CoffeeScriptAsset
'.vue'                                 // VueAsset
'.re', '.ml'                           // ReasonAsset
'.elm'                                 // ElmAsset
'.kt'                                  // KotlinAsset
'.rs'                                  // RustAsset

// Stylesheets
'.css', '.pcss', '.postcss'            // CSSAsset
'.sass', '.scss'                       // SASSAsset
'.less'                                // LESSAsset
'.styl', '.stylus'                     // StylusAsset
'.sss'                                 // SSSAsset

// Markup
'.html', '.htm'                        // HTMLAsset
'.pug', '.jade'                        // PugAsset

// Data formats
'.json', '.json5'                      // JSONAsset
'.jsonld'                              // JSONLDAsset
'.yaml', '.yml'                        // YAMLAsset
'.toml'                                // TOMLAsset

// Specialized
'.gql', '.graphql'                     // GraphqlAsset
'.glsl', '.vert', '.frag'             // GLSLAsset
'.webmanifest'                         // WebManifestAsset

// Binary and raw
'.wasm'                                // WASMAsset
// All other extensions               // RawAsset (fallback)

Custom Asset Registration

/**
 * Register custom asset type
 * @param extension - File extension including dot
 * @param AssetClass - Asset class or module path
 */
bundler.addAssetType(extension, AssetClass)

Usage Examples:

// Register custom asset class
class ProtobufAsset extends Asset {
  async parse(code) {
    return protobuf.parse(code);
  }
  
  generate() {
    return { js: this.generateProtobufModule() };
  }
}

bundler.addAssetType('.proto', ProtobufAsset);

// Register by module path
bundler.addAssetType('.custom', require.resolve('./CustomAsset'));

// Register multiple extensions
bundler.addAssetType('.data', DataAsset);
bundler.addAssetType('.config', DataAsset);

Asset Processing Pipeline

Processing Lifecycle

Load: Read file contents from disk
Parse: Convert contents to AST or structured data
Collect Dependencies: Extract import/require statements
Transform: Apply language-specific transformations
Generate: Produce output code for target environment

Dependency Types

Assets can declare different types of dependencies:

/**
 * Add dependency to asset
 * @param name - Module name or file path
 * @param opts - Dependency options
 */
addDependency(name, opts = {})

// Options:
interface DependencyOptions {
  /** Resolved dependency name */
  name?: string;
  
  /** Dynamic import (code splitting) */
  dynamic?: boolean;
  
  /** Optional dependency */
  optional?: boolean;
  
  /** Import location in source */
  loc?: SourceLocation;
  
  /** Parent asset */
  parent?: string;
  
  /** Environment-specific dependency */
  env?: string;
}

Usage Examples:

// Static import
this.addDependency('./module.js');

// Dynamic import (code splitting)
this.addDependency('./lazy-module.js', { dynamic: true });

// Optional dependency
this.addDependency('optional-plugin', { optional: true });

// Environment-specific
this.addDependency('node-specific', { env: 'node' });

Caching and Performance

Asset Caching

Assets implement caching for improved build performance:

interface AssetCaching {
  /** Cache invalidation check */
  shouldInvalidate(cacheData): boolean;
  
  /** Cache data for persistence */
  cacheData: { [key: string]: any };
  
  /** Content hash for change detection */
  hash: string | null;
}

Build Timing

Assets track build performance metrics:

interface AssetTiming {
  startTime: number;    // Build start timestamp
  endTime: number;      // Build end timestamp
  buildTime: number;    // Total build time in ms
  bundledSize: number;  // Final bundled size in bytes
}

Install with Tessl CLI

npx tessl i tessl/npm-parcel-bundler

docs

tessl/npm-parcel-bundler

asset-system.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Asset System

Capabilities

Base Asset Class

Asset Properties

JavaScript Assets

JSAsset Class

TypeScriptAsset Class

Other JavaScript Variants

Stylesheet Assets

CSSAsset Class

Preprocessor Assets

Markup Assets

HTMLAsset Class

Template Assets

Data Format Assets

JSON Assets

Configuration Assets

Specialized Assets

GraphQL Assets

Shader Assets

WebAssembly Assets

Raw Assets

Asset Registration

Built-in Asset Types

Custom Asset Registration

Asset Processing Pipeline

Processing Lifecycle

Dependency Types

Caching and Performance

Asset Caching

Build Timing

asset-system.mddocs/