[Feature] Esbuild support/option about ng-doc

[skoropadas]

@R-Bower yep, that should be the problem, thank you, I'll check and fix it tomorrow! But it's still interesting why it doesn't work only for esbuild 🤔

[skoropadas]

I have been thinking about this, but currently esbuild only works for the ng build command and not for ng serve. However, the Angular team is planning to add Vite support in Angular 16, which would make it possible to use the combination of Vite + esbuild, and thus make esbuild work for the ng serve command as well. For NgDoc 16 I plan to test the new builder, and if there are no issues with it, I will start using it by default to build the application. This means that all you will need to do is update to Angular and NgDoc 16 versions.

As for the complexity, everything should be very easy. All I will need to do is replace a couple of lines of code.

[skoropadas]

@R-Bower I added support for esbuild, and it wasn't as easy as I thought. 🤣 It seems that the builder is still quite raw, but I managed to get it working with NgDoc. I will release 16.1.0 version soon, so feel free to give it a try. You will be able to find instructions on how to run it here.

[skoropadas]

🎉 This issue has been resolved in version 16.1.0 🎉

The release is available on:

• v16.1.0
• GitHub release

Your semantic-release bot 📦🚀

[R-Bower]

@R-Bower I added support for esbuild, and it wasn't as easy as I thought. 🤣 It seems that the builder is still quite raw, but I managed to get it working with NgDoc. I will release 16.1.0 version soon, so feel free to give it a try. You will be able to find instructions on how to run it here.

Not sure why, but I'm getting a ton of TypeScript compilation errors. I upgraded everything to Angular 16 and am using the latest 16.1.1 version of ng-doc. For whatever reason, it seems to be trying to compile the .ng-doc files and is throwing errors. It seems to be ignoring the // @ts-nocheck at the top of each file.

[skoropadas]

@R-Bower I added support for esbuild, and it wasn't as easy as I thought. 🤣 It seems that the builder is still quite raw, but I managed to get it working with NgDoc. I will release 16.1.0 version soon, so feel free to give it a try. You will be able to find instructions on how to run it here.

Not sure why, but I'm getting a ton of TypeScript compilation errors. I upgraded everything to Angular 16 and am using the latest 16.1.1 version of ng-doc. For whatever reason, it seems to be trying to compile the .ng-doc files and is throwing errors. It seems to be ignoring the // @ts-nocheck at the top of each file.

Hmm, it's interesting, could you send me the list of errors you have and your tsconfig.json? I just need to reproduce it first

[R-Bower]

There are so many errors it's difficult to list. Here are a few:

 ✘ [ERROR] TS1128: Declaration or statement expected. [plugin angular-compiler]
@qui/angular-docs:dev: 
@qui/angular-docs:dev:     .ng-doc/app/guides/components/text-input/component-assets.ts:262:2:
@qui/angular-docs:dev:       262 │   }
@qui/angular-docs:dev:           ╵   ^
@qui/angular-docs:dev: 
@qui/angular-docs:dev: 
@qui/angular-docs:dev: ✘ [ERROR] TS1128: Declaration or statement expected. [plugin angular-compiler]
@qui/angular-docs:dev: 
@qui/angular-docs:dev:     .ng-doc/app/guides/components/text-input/component-assets.ts:263:0:
@qui/angular-docs:dev:       263 │ }
@qui/angular-docs:dev:           ╵ ^

tsconfig:

"compileOnSave": false,
  "compilerOptions": {
    "baseUrl": "./",
    "outDir": "./dist/out-tsc",
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "strictPropertyInitialization": false,
    "noImplicitOverride": true,
    "noPropertyAccessFromIndexSignature": false,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "sourceMap": true,
    "declaration": false,
    "downlevelIteration": true,
    "experimentalDecorators": true,
    "moduleResolution": "node",
    "allowSyntheticDefaultImports": true,
    "resolveJsonModule": true,
    "skipLibCheck": true,
    "importHelpers": true,
    "target": "ESNext",
    "module": "ESNext",
    "lib": [
      "ESNext",
      "DOM"
    ],
    "paths": {
      "~ng-doc/generated": [
        ".ng-doc/app/index.ts"
      ],
      "~ng-doc/generated/*": [
        ".ng-doc/app/*"
      ],
      "~components/*": ["src/app/components/*"],
      "~pages/*": ["src/app/pages/*"],
      "~shared/*": ["src/app/shared/*"],
      "~shared": ["src/app/shared/index.ts"]
    }
  },
  "files": [
    "src/main.ts",
    "src/polyfills.ts"
  ],
  "angularCompilerOptions": {
    "allowSyntheticDefaultImports": true,
    "enableI18nLegacyMessageIdFormat": false,
    "noPropertyAccessFromIndexSignature": false,
    "strictInjectionParameters": true,
    "strictInputAccessModifiers": true,
    "strictTemplates": true
  }

[R-Bower]

Should also note that the compiler works fine if I don't use esbuild as the angularBuilder.

[skoropadas]

Should also note that the compiler works fine if I don't use esbuild as the angularBuilder.

Sorry, again, but could you show me that generated file with the error?

[R-Bower]

Sorry, don't have time at the moment. I'll try to get you something tomorrow. Last I checked, every TS file within the generated ng-doc/app directory is causing compilation errors

[skoropadas]

@R-Bower no problem! I just can't reproduce it with your tsconfig, so I started thinking that the problem in the generated files, just they were changed a bit to start supporting webpack and esbuild together

[R-Bower]

@skoropadas

I think I've narrowed down the issue. I'm using dynamic HTML props for one of my components. It looks like ng-doc is attempting to escape or format the string contents of the property, but fails.

Here's an example source file:

import {Component} from "@angular/core"

import {QTooltipPlacement} from "@qui/base"

import {CssTableModel} from "~shared"

@Component({
  selector: "tooltip-css-table",
  template: `
    <css-table [model]="model"></css-table>
  `,
})
export class TooltipCssComponent {
  model: CssTableModel[] = [
    {
      classes: ["q-tooltip--bottom"],
      description: `Class applied to the root element when <code>qTooltipPlacement=${
        "bottom" satisfies QTooltipPlacement
      }</code>.`,
    },
  ]
}

The section of the css-table component that consumes this model:

    <tr *ngFor="let css of model">
      <td class="whitespace-nowrap font-mono">
        {{ this.formatClasses(css.classes) }}
      </td>
      <td class="q-body-m" [innerHTML]="css.description"></td>
    </tr>

The generated ng-doc code at .ng-doc/app/guides/components/tooltip/component-assets.ts

<span class="hljs-attr ngde">model</span>: <span class="hljs-title class_ ngde">CssTableModel</span>[] = [
    {
      <span class="hljs-attr ngde">classes</span>: [<span class="hljs-string ngde">"q-tooltip--bottom"</span>],
      <span class="hljs-attr ngde">description</span>: <span class="hljs-string ngde">\`Class applied to the root element when &#x3C;code>qTooltipPlacement=<span class="hljs-subst ngde">${
        <span class="hljs-string ngde">"bottom"</span> satisfies QTooltipPlacement
      }</span>&#x3C;/code>.\`</span>,
    },
]

[R-Bower]

I just verified and it's also failing for webpack. What's odd is that sometimes it compiles, but most of the time it fails.

[skoropadas]

@R-Bower Now it makes sense! 👍🏻 Yes, the problem is with the escape function I'm using to inject template code directly into TypeScript code. Previously, I used the raw-loader for webpack and imported the template file directly through import statements. However, for esbuild to work with this setup, another plugin needs to be added. Since esbuild's support for Angular is still in its early stages, I can't make that work. Therefore, I've decided to move the template code directly into the TypeScript code, eliminating the differences between esbuild and webpack.

Anyway, 16.2.1 has been released and should fix that errors, thank you for your help!

[skoropadas]

🎉 This issue has been resolved in version 16.3.0-beta.1 🎉

The release is available on:

• v16.3.0-beta.1
• GitHub release

Your semantic-release bot 📦🚀

[skoropadas]

🎉 This issue has been resolved in version 16.3.0 🎉

The release is available on:

• v16.3.0
• GitHub release

Your semantic-release bot 📦🚀