Provide util for generating import paths from file paths

[aklinker1]

Feature Request

In some cases, simple string interpolation is not good enough when importing an absolute file path, as mentioned in the original issues mentioned below.

We should provide a util from wxt/module for converting file paths to import paths. It should support windows paths and unix paths, as well as escape ' and other characters in paths.

Proposed APIs:

import { formatImportPath } from 'wxt/modules'

Is your feature request related to a bug?

Follow up to #2143 and #1697.

What are the alternatives?

Use a package or existing API?

Additional context

Add any other context or screenshots about the feature request here.

[aklinker1]

We should use import { pathToFileURL } from 'node:url'; for absolute path. And we already provide a normalizePath function for relative paths.

Doesn't need to be shipped with WXT.

[aklinker1]

Or we could provide one that converts to a URL and returns the href:

import { pathToFileURL } from 'url';

const absolutePath = "/path/example'quote/module.js";
const safePath = pathToFileURL(absolutePath).href;

const code = `import _ from '${safePath}';`;
// Result: import _ from 'file:///path/example%27quote/module.js';

For absolute paths, and normalizes relative paths to /.

[aklinker1]

Had an AI provide an example implementation:

import path from 'node:path';
import { pathToFileURL } from 'node:url';

/**
 * Sanitizes a file path for use in a static import statement.
 * Works for absolute paths and relative paths.
 */
export function formatImportPath(filePath: string, isAbsolute = path.isAbsolute(filePath)): string {
  if (isAbsolute) return pathToFileURL(filePath).href;
  
  // For relative: fix slashes, add prefix, and encode URL delimiters
  let rel = normalizePath(filePath);
  if (!rel.startsWith('.')) rel = './' + rel;
  return rel.replace(/[?#]/g, encodeURIComponent);
}

// Example usage:
const absolute = formatImportPath("C:\\Users\\Project\\#config's?.js", true);
const relative = formatImportPath("src/modules/my file#1.ts", false);

console.log(`import _ from '${absolute}';`); 
// import _ from 'file:///C:/Users/Project/%23config%27s%3F.js';

console.log(`import _ from '${relative}';`); 
// import _ from './src/modules/my%20file%231.ts';

Seems like a good approach to me.

[Arktomson]

@aklinker1 Okay, this feature can be assigned to me, I will submit a PR later. Regarding this PR #2143, do you think we should merge it after improving the test code based on the current writing to resolve issue #1697 first, or should we wait until the general method here is completed before modifying and merging them together?

[aklinker1]

Let's create the util first, then update your current PR to use it. I'll wait to do a release until both PRs are merged anyways.

[aklinker1]

Thanks!