globload

This is a small yet powerful Node.js module loader that allows you to dynamically import multiple files using glob patterns. It supports importing entire modules, specific named or default exports, and can directly parse and import YAML files as JavaScript objects.

Features

In Node.js projects, you sometimes need to import all modules within a directory (e.g., a series of services, plugins, or configuration files). Manually writing import statements for each file is tedious and error-prone, especially when files change frequently.

globload solves this problem by providing a concise glob syntax, allowing you to:

• Dynamic Import: Import modules based on file pattern matching.
• Stay Clean: Reduce redundant import statements.
• Flexible Control: Supports lazy loading and eager loading.
• No Build Tools Needed: Unlike similar features provided by some bundlers, globload works directly in the Node.js runtime via module hooks, requiring no extra build steps.

Installation

1# pnpm
2pnpm add globload
3
4# npm
5npm install globload
6
7# yarn
8yarn add globload

How to Use

globload utilizes Node.js module hooks. To enable it, you need to preload globload's registration script via the --import flag when starting your Node.js application.

1node --import globload your-app.js

Import Syntax Examples

To use globload, you need to append the ?glob query parameter to the end of your import path string. This will instruct globload to process the import.

Assume your project structure is as follows:

your-project/
├── src/
│   ├── app.js
│   └── services/
│       ├── user.js
│       └── product.js
└── package.json

Lazy Loading (Default)

When only ?glob is used, modules are imported lazily. This means globload exports an object where the values are functions that return dynamic import() calls.

1// src/app.js
2import services from "./services/*.js?glob";
3
4// services will be an object like this:
5// {
6//   'src/services/product.js': () => import('file:///path/to/your-project/src/services/product.js'),
7//   'src/services/user.js': () => import('file:///path/to/your-project/src/services/user.js')
8// }
9// Note: Keys are paths relative to process.cwd().
10
11for (const pathKey in services) {
12	const service = await services[pathKey](); // Call the function to load the module
13	// Assuming user.js exports a function named 'getUser'
14	if (service.getUser) {
15	  console.log('Module content (getUser):', service.getUser());
16	}
17}

Eager Loading

To eagerly load modules (i.e., load all matching modules immediately), append the eager parameter after ?glob (e.g., ?glob&eager).

1// src/app.js
2import services from './services/*.js?glob&eager';
3
4// services will be an object like this (modules are already loaded):
5// {
6//   'src/services/product.js': { /* product exports */ },
7//   'src/services/user.js': { /* user exports */ }
8// }
9// Note: Keys are paths relative to process.cwd().
10
11for (const pathKey in services) {
12  const service = services[pathKey]; // Module is already loaded, access directly
13  // Assuming user.js exports a function named 'getUser'
14  if (service.getUser) {
15    console.log('Module content (getUser):', service.getUser());
16  }
17}

Importing Specific Exports

globload allows you to import only specific named or default exports from the matched modules by using the &import= query parameter.

Syntax:

• ?glob&import=default: Imports the default export from each module.
• ?glob&import=namedExport: Imports the export named namedExport from each module.

Lazy Loading with &import=default:

1// src/app.js
2// Assuming each service file has a default export
3import serviceDefaults from "./services/*.js?glob&import=default";
4
5// serviceDefaults will be an object like this:
6// {
7//   'src/services/product.js': () => import('file:///path/to/your-project/src/services/product.js').then(m => m.default),
8//   'src/services/user.js': () => import('file:///path/to/your-project/src/services/user.js').then(m => m.default)
9// }
10
11for (const pathKey in serviceDefaults) {
12	const defaultExportContent = await serviceDefaults[pathKey]();
13	// defaultExportContent is now the actual default export of the module
14	console.log(defaultExportContent);
15}

Eager Loading with &import=setup (a named export):

1// src/app.js
2// Assuming each service file has a named export 'setup'
3import serviceSetups from './services/*.js?glob&eager&import=setup';
4
5// serviceSetups will be an object like this:
6// {
7//   'src/services/product.js': /* content of product.js's 'setup' export */,
8//   'src/services/user.js': /* content of user.js's 'setup' export */
9// }
10
11for (const pathKey in serviceSetups) {
12  const setupFunction = serviceSetups[pathKey];
13  // setupFunction is now the actual 'setup' export from the module
14  if (typeof setupFunction === 'function') {
15    setupFunction();
16  }
17}

Importing YAML Files

globload also supports importing .yaml and .yml files directly. When a glob pattern matches YAML files, globload will parse their content into JavaScript objects.

Example:

Assume you have YAML files in a config/ directory:

config/database.yaml:

1host: localhost
2port: 5432
3user: admin

config/features.yaml:

1logging: true
2betaAccess: false

Lazy Loading YAML:

1// src/app.js
2import configs from "./config/*.yaml?glob";
3
4// configs will be an object like this:
5// {
6//   'src/config/database.yaml': async () => { /* function that returns parsed database.yaml */ },
7//   'src/config/features.yaml': async () => { /* function that returns parsed features.yaml */ }
8// }
9
10async function loadConfigs() {
11  const dbConfig = await configs['src/config/database.yaml']();
12  console.log(dbConfig.host); // Output: localhost
13
14  const featureFlags = await configs['src/config/features.yaml']();
15  console.log(featureFlags.logging); // Output: true
16}
17loadConfigs();

Eager Loading YAML:

1// src/app.js
2import configs from "./config/*.yaml?glob&eager";
3
4// configs will be an object like this (YAML content is already parsed):
5// {
6//   'src/config/database.yaml': { host: 'localhost', port: 5432, user: 'admin' },
7//   'src/config/features.yaml': { logging: true, betaAccess: false }
8// }
9
10console.log(configs['src/config/database.yaml'].port); // Output: 5432

Using &import= with YAML:

You can use the &import=keyName parameter to extract a specific top-level key from the parsed YAML object.

1// src/app.js
2// Get only the 'host' from database.yaml and 'logging' from features.yaml
3import dbHost from "./config/database.yaml?glob&eager&import=host";
4import loggingFlag from "./config/features.yaml?glob&eager&import=logging";
5
6// Note: When using &import with a glob that matches a single file,
7// the result 'dbHost' directly contains the value of 'host'.
8// If the glob matches multiple files, it would be an object similar to other glob imports.
9
10// For a single file match (simplified for clarity here, globload structure remains):
11// Assuming './config/database.yaml?glob&eager&import=host' effectively gives:
12// { 'src/config/database.yaml': 'localhost' }
13// Accessing it would be: const host = dbHost['src/config/database.yaml'];
14
15// A more typical usage with a glob matching one YAML for a specific key:
16import items from "./config/*.yaml?glob&eager&import=user";
17// items would be:
18// {
19//   'src/config/database.yaml': 'admin', // Assuming 'user' key exists
20// }
21

Using &import=default with YAML files behaves the same as not providing the &import parameter, returning the entire parsed object.

Regarding Import Attributes

If you use import attributes (e.g., with { type: "json" }) in your globload import statement, these attributes will be passed to each individual dynamic import generated by globload. This is useful for importing module types that require specific import attributes, such as JSON modules.

1// Assuming you have a data directory containing multiple JSON files
2// src/app.js
3import data from './data/*.json?glob&eager' with { type: 'json' };
4
5// data will be an object where each JSON file is already loaded as a module
6// {
7//   'src/data/config.json': { default: { /* parsed JSON content */ } },
8//   'src/data/userPreferences.json': { default: { /* parsed JSON content */ } }
9// }

Advanced Path Matching

This library uses tinyglobby internally to parse and match glob patterns. tinyglobby supports common glob patterns.

Differences from Bundlers

The functionality provided by globload is similar to features in some modern frontend bundlers.

For example, Vite's import.meta.glob feature allows importing multiple modules using glob patterns. However, import.meta.glob is a compile-time feature that relies on Vite's build process to analyze and transform code. In contrast, globload dynamically resolves and loads modules at runtime via Node.js module loader hooks, without needing any build or bundling tools. This makes globload well-suited for pure Node.js backend projects, scripts, or any scenario where you don't want to introduce a complex build process.

Other mainstream bundlers like Rollup and Webpack also support using partial glob patterns in the standard import() dynamic import syntax, then perform code splitting during the build.

Compatibility

• Node.js: Please refer to the engines field in package.json for specific declarations.