How to avoid `Error: Expected a symbol for node with kind Identifier at path` when using `@ts-expect-error`

[aiktb]

Question

I'm upgrading from 0.25.4 to 0.27.2 and I get an error when I encounter the following code:

export type IframeContentScriptUiOptions<TMounted> =
  ContentScriptUiOptions<TMounted> & {
    /**
     * The path to the HTML page that will be shown in the iframe. This string is passed into
     * `browser.runtime.getURL`.
     */
    // @ts-expect-error: HtmlPublicPath is generated per-project
    page: import('wxt/browser').HtmlPublicPath;
  };

Error:

TypeDoc exiting with unexpected error:
Error: Expected a symbol for node with kind Identifier at /home/aiktb/Github/wxt/packages/wxt/src/client/content-scripts/ui/types.ts:87
    at Context.expectSymbolAtLocation (file:///home/aiktb/Github/wxt/node_modules/.pnpm/typedoc@0.27.2_typescript@5.6.3/node_modules/typedoc/dist/lib/converter/context.js:109:19)
    at Object.convert (file:///home/aiktb/Github/wxt/node_modules/.pnpm/typedoc@0.27.2_typescript@5.6.3/node_modules/typedoc/dist/lib/converter/types.js:234:32)
    at convertType (file:///home/aiktb/Github/wxt/node_modules/.pnpm/typedoc@0.27.2_typescript@5.6.3/node_modules/typedoc/dist/lib/converter/types.js:80:38)
    at Converter.convertType (file:///home/aiktb/Github/wxt/node_modules/.pnpm/typedoc@0.27.2_typescript@5.6.3/node_modules/typedoc/dist/lib/converter/converter.js:330:20)
    at Object.convertProperty (file:///home/aiktb/Github/wxt/node_modules/.pnpm/typedoc@0.27.2_typescript@5.6.3/node_modules/typedoc/dist/lib/converter/symbols.js:440:41)
    at convertSymbol (file:///home/aiktb/Github/wxt/node_modules/.pnpm/typedoc@0.27.2_typescript@5.6.3/node_modules/typedoc/dist/lib/converter/symbols.js:122:41)
    at Object.convert (file:///home/aiktb/Github/wxt/node_modules/.pnpm/typedoc@0.27.2_typescript@5.6.3/node_modules/typedoc/dist/lib/converter/types.js:367:13)
    at convertType (file:///home/aiktb/Github/wxt/node_modules/.pnpm/typedoc@0.27.2_typescript@5.6.3/node_modules/typedoc/dist/lib/converter/types.js:80:38)
    at file:///home/aiktb/Github/wxt/node_modules/.pnpm/typedoc@0.27.2_typescript@5.6.3/node_modules/typedoc/dist/lib/converter/types.js:264:62

The point is that this type is generated by other users of the library, and it is safely ignored here, but @ts-expect-error is only valid for the next line of code.

How do I use @ts-expect-error with typedoc?

Any help is appreciated.

[Gerrit0]

TypeDoc expects to work on projects whose public API does not contain type errors, including type errors ignored with ts-expect-error or ts-ignore. That's a horrendously large hammer which should not be necessary.

With a native tsc build system, the way I'd recommend handling this is adding a declaration file under client with:

export {}

declare module "wxt/browser" {
  export type HtmlPublicPath = string;
}

When compiling, tsc does not copy declaration files, so this file will be present only for internal use.

With whatever build system you're using, it appears that this doesn't work, the declaration file is being copied over to the dist directory, which isn't how it ought to work in my opinion.

I can add some special casing to handle this specific case, but in general TypeDoc cannot reasonably support code with type errors.

[aiktb]

@Gerrit0 Thanks! I tested locally with the latest commit and everything works fine. Feel free to close this issue.