or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-main-bower-files

Get main files from your installed bower packages.

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/main-bower-files@2.13.x

To install, run

npx @tessl/cli install tessl/npm-main-bower-files@2.13.0

main-bower-files

A utility library that extracts main files from installed Bower packages by reading bower.json configurations. It provides flexible filtering mechanisms and comprehensive integration with build systems like Gulp and Grunt, making it essential for front-end build processes that need to programmatically identify and process primary files from Bower dependencies.

Package Information

Package Name: main-bower-files
Package Type: npm
Language: JavaScript
Installation: npm install main-bower-files

Core Imports

const mainBowerFiles = require('main-bower-files');

Basic Usage

const mainBowerFiles = require('main-bower-files');

// Get all main files from bower packages
const files = mainBowerFiles();

// Filter files with glob patterns
const jsFiles = mainBowerFiles('**/*.js');

// Use with options
const files = mainBowerFiles({
  debugging: true,
  checkExistence: true,
  includeDev: true
});

// Async with callback
mainBowerFiles((err, files) => {
  if (err) throw err;
  console.log(files);
});

Architecture

The main-bower-files package is built around several key internal components:

Main Module: The primary export function with flexible parameter overloading
PackageCollection: Manages the collection of bower packages and their dependencies
Package: Represents individual bower packages with their metadata and file resolution
Logger: Provides colored debug output for troubleshooting
Grunt Task: Integrated Grunt multitask for build system workflows

The architecture follows a hierarchical pattern where the main function creates a PackageCollection, which manages multiple Package instances that handle individual bower package resolution and dependency tracking.

Capabilities

Main Module Export

The primary module export function that extracts main files from installed Bower packages with flexible parameter overloading.

/**
 * Main module export - extracts main files from installed Bower packages
 * @param {string|Array<string>|RegExp|Function} [filter] - File filtering (glob patterns, regex, function, or array)
 * @param {Options} [options] - Configuration options
 * @param {Function} [callback] - Optional callback function (error, files) => void
 * @returns {Array<string>} Array of absolute file paths from Bower packages
 */
module.exports = function(filter, options, callback) { ... };

Filter Parameter

The filter parameter supports multiple formats for file selection:

String: Glob pattern (e.g., '**/*.js', '**/*.css')
Array: Multiple glob patterns (e.g., ['**/*.js', '**/*.css'])
RegExp: Regular expression for file matching
Function: Custom filter function (filepath) => boolean

Options Object

/**
 * Configuration options for main-bower-files
 * @typedef {Object} Options
 * @property {boolean} [debugging=false] - Enable debug output
 * @property {string|Array<string>|Object} [main] - Default main property for packages without one
 * @property {string} [env=process.env.NODE_ENV] - Environment for conditional main files
 * @property {PathsConfig|string} [paths] - Custom paths configuration
 * @property {boolean} [checkExistence=false] - Validate file existence
 * @property {boolean|string} [includeDev=false] - Include devDependencies ('inclusive', 'exclusive', true, false)
 * @property {boolean} [includeSelf=false] - Include current package main files
 * @property {string|Array<string>|RegExp|Function} [filter] - File filtering
 * @property {Object} [overrides={}] - Default package overrides
 * @property {string|Array<string>} [group] - Select specific dependency groups
 * @property {string} [base] - Base path for file resolution
 */

/**
 * Path configuration options
 * @typedef {Object} PathsConfig
 * @property {string} [bowerDirectory] - Path to bower_components directory
 * @property {string} [bowerrc] - Path to .bowerrc file
 * @property {string} [bowerJson] - Path to bower.json file
 */

Build System Integration

Gulp Integration

const gulp = require('gulp');
const mainBowerFiles = require('main-bower-files');

gulp.task('bower', function() {
  return gulp.src(mainBowerFiles())
    .pipe(/* processing */)
    .pipe(gulp.dest('dist/'));
});

// With base path for proper file structure
gulp.task('bower-structured', function() {
  return gulp.src(mainBowerFiles(), { base: 'bower_components' })
    .pipe(gulp.dest('dist/lib/'));
});

Grunt Integration

Basic Grunt usage with the main function:

const mainBowerFiles = require('main-bower-files');

grunt.registerTask('copy-bower', function() {
  const files = mainBowerFiles();
  // Process files with grunt
});

Grunt Multitask

The package provides a dedicated Grunt multitask for automatically copying Bower files using vinyl-fs.

/**
 * Grunt multitask for copying Bower packages to destination folders
 * Task name: 'bower'
 * @param {Object} options - Same options as main function
 * @param {string} target.base - Base path for maintaining directory structure  
 * @param {string} target.dest - Destination directory for copied files
 */
grunt.registerMultiTask('bower', 'Copy Bower packages to the destination folder.');

Task Configuration:

grunt.initConfig({
  bower: {
    dev: {
      base: 'bower_components',
      dest: 'web/bower_components',
      options: {
        checkExistence: true,
        debugging: true,
        paths: {
          bowerDirectory: 'bower_components',
          bowerrc: '.bowerrc',
          bowerJson: 'bower.json'
        }
      }
    },
    flat: {
      dest: 'public/vendor',
      options: {
        debugging: true
      }
    }
  }
});

grunt.loadNpmTasks('main-bower-files');

Target Properties:

base: Base path for maintaining directory structure during copy
dest: Destination directory where files will be copied
options: Same configuration options as the main function

Advanced Filtering Options

Environment-Based File Selection

Configure different files for different environments in bower.json overrides:

{
  "overrides": {
    "jquery": {
      "main": {
        "development": "dist/jquery.js",
        "production": "dist/jquery.min.js"
      }
    }
  }
}

Dependency Groups

Organize dependencies into groups for selective inclusion:

{
  "dependencies": {
    "jquery": "*",
    "backbone": "*",
    "underscore": "*"
  },
  "group": {
    "home": ["jquery"],
    "admin": ["jquery", "backbone", "underscore"]
  }
}

// Include only home group dependencies
const homeFiles = mainBowerFiles({ group: 'home' });

// Include multiple groups
const multiFiles = mainBowerFiles({ group: ['home', 'admin'] });

// Exclude specific group
const excludeHome = mainBowerFiles({ group: '!home' });

Package Overrides

Override package behavior through bower.json overrides section:

/**
 * Package override configuration
 * @typedef {Object} PackageOverride
 * @property {string|Array<string>|Object} [main] - Override main files
 * @property {boolean} [ignore] - Ignore this package completely
 * @property {Object|null} [dependencies] - Override package dependencies
 */

Example override configuration:

{
  "overrides": {
    "bootstrap": {
      "main": [
        "less/bootstrap.less",
        "dist/js/bootstrap.js"
      ]
    },
    "font-awesome": {
      "main": [
        "css/font-awesome.css",
        "fonts/*"
      ]
    },
    "unwanted-package": {
      "ignore": true
    }
  }
}

Error Handling

The function throws errors in the following situations:

bower.json file doesn't exist
bower_components directory doesn't exist
checkExistence is enabled and files don't exist
Absolute paths found in bower main property
Invalid dependency group specified

When using the callback pattern, errors are passed as the first argument:

mainBowerFiles((err, files) => {
  if (err) {
    console.error('Error:', err.message);
    return;
  }
  // Process files
});

Path Resolution

The library resolves paths in the following order:

Custom paths option if provided
.bowerrc configuration if exists
Default bower_components location
Current working directory as fallback

All returned file paths are absolute paths ready for use with build tools.

Dependencies

The package relies on these core dependencies:

chalk: Terminal styling for debug output
extend: Object merging utilities
globby: Glob matching for file patterns
multimatch: Multiple glob pattern matching
path-exists: File existence validation
strip-json-comments: JSON comment parsing
vinyl-fs: Virtual file system for Grunt integration

Internal Architecture

PackageCollection Class

Internal class that manages the collection of bower packages and their dependencies.

/**
 * Collection for bower packages - manages dependency resolution and file collection
 * @class PackageCollection
 * @param {Options} opts - Configuration options
 */
function PackageCollection(opts) {
  this.opts = opts;
  this.debugging = opts.debugging || false;
  this.overrides = opts.overrides || {};
  this._packages = {};
  this._processed = {};
}

PackageCollection.prototype = {
  /**
   * Adds a package to the collection
   * @param {string} name - Name of the package
   * @param {string} path - Path to the package files
   * @param {string|Array<string>} [main] - Override main files
   */
  add: function(name, path, main) { ... },
  
  /**
   * Gets all main files from collected packages
   * @returns {Array<string>} Array of absolute file paths
   */
  getFiles: function() { ... },
  
  /**
   * Collects all packages from bower.json dependencies
   */
  collectPackages: function() { ... }
};

Package Class

Internal class representing individual bower packages with metadata and file resolution.

/**
 * Represents a single bower package with its metadata and file resolution
 * @class Package  
 * @param {Object} opts - Package options
 * @param {PackageCollection} collection - Parent collection reference
 */
function Package(opts, collection) {
  this.collection = collection;
  this.name = opts.name || null;
  this.path = opts.path || null;
  this.main = opts.main || null;
  this.dependencies = opts.dependencies;
  this.ignore = opts.ignore || false;
}

Package.prototype = {
  /**
   * Gets main files of the package with dependency resolution
   * @param {boolean} [force=false] - Force processing without waiting for dependencies
   * @returns {Array<string>|false} Array of file paths or false if dependencies not ready
   */
  getFiles: function(force) { ... },
  
  /**
   * Collects package data from bower.json, package.json, or component.json
   */
  collectData: function() { ... }
};

Logger Function

Internal logging utility for debug output with colored formatting.

/**
 * Logger function for debug output with colored formatting
 * @param {...*} args - Arguments to log with colored formatting
 */
function logger(...args) { ... };