esbuild-deno-loader

The Deno integration is composed of two primary plugins that work together to handle Deno's unique module resolution and loading logic:

1. The Resolver: Handles absolutization of specifiers (making relative paths absolute) and processes import maps (including those embedded in deno.json).
2. The Loader: Takes fully resolved specifiers and handles the actual loading of the module, including processing redirects until a final module is found.

Most users should use denoPlugins() to instantiate both plugins automatically in the correct order.

If you need to add custom plugins that handle specific file extensions or URL schemes, you should manually instantiate the Deno plugins instead of using denoPlugins().

To ensure correct behavior, the denoResolverPlugin should be the first plugin in your plugin array. If you have a custom loader plugin, insert it between the Deno resolver and the Deno loader.

Plugin Order for Custom Schemes:

1. denoResolverPlugin (Resolves relative paths/import maps to absolute URLs)
2. Your Custom Plugin (Handles specific schemes/extensions)
3. denoLoaderPlugin (Handles http, https, data, and file schemes)

To correctly resolve and load Deno modules in esbuild, you must follow a specific plugin order. The denoResolverPlugin handles the logic of turning relative paths and import map specifiers into absolute URLs. The denoLoaderPlugin then handles the actual loading of those files.

Crucial Requirement: The denoResolverPlugin must appear in your plugins array before the denoLoaderPlugin.

Mental Model:

1. denoResolverPlugin intercepts the resolution request.
2. It resolves the specifier (e.g., ./utils.ts or an import map alias) to a fully qualified absolute URL.
3. It passes that resolved URL back to esbuild, which then triggers the next plugin in the chain (the loader) to handle the file content.

When instantiating InfoCache, you can provide an InfoOptions object to control how deno info is executed. Supported options include:

• cwd: The current working directory for the command.
• config: Path to a Deno configuration file.
• importMap: Path to an import map file.
• lock: Path to a Deno lock file.
• nodeModulesDir: Controls how node_modules are handled. Supported values are 'auto', 'manual', or 'none'. Note that behavior for 'auto' and 'manual' varies depending on whether the Deno version starts with 1..

const options: InfoOptions = {
  cwd: '/path/to/project',
  importMap: '/path/to/import_map.json',
  nodeModulesDir: 'auto'
};
const cache = new InfoCache(options);

The "portable" loader mode has specific constraints compared to the native loader:

• No Cache: It does not use the Deno module cache; all remote specifiers are downloaded on every run.
• npm Dependencies: All npm: dependencies must be pre-downloaded into a local node_modules/ directory.
• jsr Dependencies: When using jsr: specifiers, a lockfile must be present and passed to the loader via configPath or lockPath.
• Wasm Restriction: npm: specifiers are not supported when using the Wasm build of esbuild due to filesystem access limitations.

Depending on your usage, you may need to grant the following permissions to your Deno process:

• --allow-read: Required if you need to resolve local files.
• --allow-net: Required if you need to resolve remote files.
• --allow-run: If provided, the plugin uses the deno binary to resolve remote files, allowing it to re-use the Deno module cache.

The InfoCache class provides an efficient way to resolve Deno module specifiers into detailed ModuleEntry objects. It uses deno info --json under the hood to fetch module metadata and caches the results to avoid redundant CLI calls. It also handles module redirects and provides access to npmPackage metadata.

To use it, instantiate InfoCache with optional InfoOptions and call .get(specifier) to retrieve the module information.

import { InfoCache } from './deno.ts';

const cache = new InfoCache({
  cwd: './',
  importMap: './import_map.json'
});

// Get module entry details
const moduleEntry = await cache.get('https://deno.land/std/http/server.ts');

// If it's an npm module, you can get package details
if (moduleEntry.kind === 'npm') {
  const pkg = cache.getNpmPackage(moduleEntry.npmPackage);
  console.log(pkg?.version);
}

The denoLoaderPlugin is an esbuild plugin designed to load fully qualified file, http, https, and data URLs.

Important Requirement: This plugin does not handle relative-to-absolute resolution or import map resolution. You must use the denoResolverPlugin before the denoLoaderPlugin in your esbuild configuration to ensure specifiers are correctly resolved to absolute URLs.

import { denoLoaderPlugin } from "./path/to/plugin";

// In your esbuild configuration:
// plugins: [denoResolverPlugin(), denoLoaderPlugin()]