Support URL in plugins options (#17166)

changelog_unreleased/api/17166.md

@@ -0,0 +1,47 @@
+#### Accept `URL` in `plugins` option (#17166 by @fisker)
+
+`plugins` option now accepts [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) with `file:` protocol or url string starts with `file:` in all public APIs.
+
+```js
+// `URL`
+await prettier.check("foo", {
+  parser: "my-cool-parser",
+  plugins: [new URL("./path/to/plugin.js", import.meta.url)],
+});
+await prettier.format("foo", {
+  parser: "my-cool-parser",
+  plugins: [new URL("./path/to/plugin.js", import.meta.url)],
+});
+await prettier.formatWithCursor("foo", {
+  parser: "my-cool-parser",
+  cursorOffset: 2,
+  plugins: [new URL("./path/to/plugin.js", import.meta.url)],
+});
+await prettier.getFileInfo("/path/to/file", {
+  plugins: [new URL("./path/to/plugin.js", import.meta.url)],
+});
+await prettier.getSupportInfo({
+  plugins: [new URL("./path/to/plugin.js", import.meta.url)],
+});
+
+// URL string
+await prettier.check("foo", {
+  parser: "my-cool-parser",
+  plugins: ["file:///path/to/plugin.js"],
+});
+await prettier.format("foo", {
+  parser: "my-cool-parser",
+  plugins: ["file:///path/to/plugin.js"],
+});
+await prettier.formatWithCursor("foo", {
+  parser: "my-cool-parser",
+  cursorOffset: 2,
+  plugins: ["file:///path/to/plugin.js"],
+});
+await prettier.getFileInfo("/path/to/file", {
+  plugins: ["file:///path/to/plugin.js"],
+});
+await prettier.getSupportInfo({
+  plugins: ["file:///path/to/plugin.js"],
+});
+```

docs/api.md

@@ -99,7 +99,7 @@ Setting `options.ignorePath` (`string | URL | (string | URL)[]`) and `options.wi
 
 If the given `fileUrlOrPath` is ignored, the `inferredParser` is always `null`.
 
-Providing [plugin](plugins.md) paths in `options.plugins` (`string[]`) helps extract `inferredParser` for files that are not supported by Prettier core.
+Providing [plugin](plugins.md) paths in `options.plugins` (`(string | URL | Plugin)[]`) helps extract `inferredParser` for files that are not supported by Prettier core.
 
 When setting `options.resolveConfig` (`boolean`, default `true`) to `false`, Prettier will not search for configuration file. This can be useful if this function is only used to check if file is ignored.
 

src/index.d.ts

@@ -398,7 +398,7 @@ export interface RequiredOptions extends doc.printer.Options {
   /**
    * Provide ability to support new languages to prettier.
    */
-  plugins: Array<string | Plugin>;
+  plugins: Array<string | URL | Plugin>;
   /**
    * How to handle whitespaces in HTML.
    * @default "css"
@@ -801,7 +801,7 @@ export interface SupportInfo {
 export interface FileInfoOptions {
   ignorePath?: string | URL | (string | URL)[] | undefined;
   withNodeModules?: boolean | undefined;
-  plugins?: Array<string | Plugin> | undefined;
+  plugins?: Array<string | URL | Plugin> | undefined;
   resolveConfig?: boolean | undefined;
 }
 
@@ -816,7 +816,7 @@ export function getFileInfo(
 ): Promise<FileInfoResult>;
 
 export interface SupportInfoOptions {
-  plugins?: Array<string | Plugin> | undefined;
+  plugins?: Array<string | URL | Plugin> | undefined;
   showDeprecated?: boolean | undefined;
 }
 

src/main/plugins/load-plugin.js

@@ -1,8 +1,18 @@
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { isUrl } from "url-or-path";
 import importFromDirectory from "../../utils/import-from-directory.js";
 
+/**
+@param {string | URL} name
+@param {string} cwd
+*/
 async function importPlugin(name, cwd) {
+  if (isUrl(name)) {
+    // @ts-expect-error -- Pass `URL` to `import()` works too
+    return import(name);
+  }
+
   if (path.isAbsolute(name)) {
     return import(pathToFileURL(name).href);
   }
@@ -23,7 +33,7 @@ async function loadPluginWithoutCache(plugin, cwd) {
 
 const cache = new Map();
 function loadPlugin(plugin) {
-  if (typeof plugin !== "string") {
+  if (typeof plugin !== "string" && !(plugin instanceof URL)) {
     return plugin;
   }
 

tests/integration/__tests__/plugins.js

@@ -0,0 +1,32 @@
+import url from "node:url";
+import prettier from "../../config/prettier-entry.js";
+
+const pluginUrl = new URL(
+  "../../config/prettier-plugins/prettier-plugin-uppercase-rocks/index.js",
+  import.meta.url,
+);
+
+test("plugins", async () => {
+  const input = "foo";
+  const expectedOutput = "FOO\n";
+
+  await expect(
+    prettier.format(input, {
+      parser: "uppercase-rocks",
+      plugins: [pluginUrl],
+    }),
+  ).resolves.toEqual(expectedOutput);
+
+  await expect(
+    prettier.format(input, {
+      parser: "uppercase-rocks",
+      plugins: [pluginUrl.href],
+    }),
+  ).resolves.toEqual(expectedOutput);
+  await expect(
+    prettier.format(input, {
+      parser: "uppercase-rocks",
+      plugins: [url.fileURLToPath(pluginUrl)],
+    }),
+  ).resolves.toEqual(expectedOutput);
+});