Support TypeScript declarations with @nx/esbuild:esbuild

[castleadmin]

• [X ] I'd be willing to implement this feature (contributing guide)

Description

esbuild doesn't support the creation of declaration files (*.d.ts) and probably never will (see evanw/esbuild#95).
Since declaration files are essential for published libraries,
it would be great if @nx/esbuild:esbuild would provide an option to output them.

Motivation

Declaration files (*.d.ts) are essential for published libraries.

Suggested Implementation

The commonly accepted workaround is to run a tsc build before the esbuild build that only outputs the declaration files.
This additional build step could be provided as a @nx/esbuild:esbuild option.

Alternate Implementations

Implement the additional build step in the @nx/js:library generator for publishable libraries.

[jaysoo]

@castleadmin Hey, thanks for expressing interest on this, do you have any suggestions on how you'd want to do this?

[castleadmin]

Hi @jaysoo, for the suggested case I would do the following

• Introduce a new boolean valued --declaration option
• If --declaration or the tsconfig option declaration is true,
  then the TypeScript compiler will be used before the esbuild build call to generate the declarations
• The TypeScript compiler could be called via the command line or the @nx/js:tsc executor
• The same tsconfig options should be used for the esbuild and declarations build with one exception
  • The declaration build will always set the emitDeclarationOnly tsconfig option

[castleadmin]

@jaysoo What do you think about the new feature? Should I start implementing a concrete solution?

[GideonMax]

When can we expect this feature?

[castleadmin]

I should be able to implement the feature within the next 2 weeks.

[ChristopherPHolder]

What is missing to complete this feature? It seems the MR is open and ready for review.

I am happy to contribute if there is anything needed to complete the feature 👍

[ThePlenkov]

Here is the way I have fixed it:

    "dts": {
      "executor": "@nx/js:tsc",
      "outputs": [
        "{options.outputPath}"
      ],
      "options": {
        "outputPath": "dist/packages/prosemirror-markdown-es",
        "main": "packages/prosemirror-markdown-es/src/index.ts",
        "tsConfig": "packages/prosemirror-markdown-es/tsconfig.dts.json",
        "clean": true
      }
    },
    "build": {
      "executor": "@nx/esbuild:esbuild",
      "outputs": [
        "{options.outputPath}"
      ],
      "options": {
        "outputPath": "dist/packages/prosemirror-markdown-es",
        "main": "packages/prosemirror-markdown-es/src/index.ts",
        "tsConfig": "packages/prosemirror-markdown-es/tsconfig.lib.json",
        "assets": [
          "packages/prosemirror-markdown-es/*.md",
        ],
        "generatePackageJson": true,
        "format": [
          "cjs"
        ],
        "deleteOutputPath": false
      },
      "dependsOn": [
        "dts"
      ]
    },

so I create first dts with clean:true and then build esbuild with "deleteOutputPath": false. I know it's ugly but it works =)

Addititionally I had to create a dedicated tsconfig too to use: "declaration": true and "emitDeclarationOnly": true,

[danielsharvey]

This has been done in #21084. I have experienced and issue with referencing buildable libraries - see #26376.

[MaxKless]

Hello! Looks like this has been resolved in #21084 so I will close this issue.
Please create new issues or comment on the one linked above if you're running into problems with this feature.

[github-actions]

This issue has been closed for more than 30 days. If this issue is still occuring, please open a new issue with more recent context.