<!-- Please make sure you have read the submission guidelines before
posting an PR -->
<!--
https://github.com/nrwl/nx/blob/master/CONTRIBUTING.md#-submitting-a-pr
-->
<!-- Please make sure that your commit message follows our format -->
<!-- Example: `fix(nx): must begin with lowercase` -->
## Current Behavior
esbuild doesn't support the creation of declaration files (*.d.ts) and
probably never will (see https://github.com/evanw/esbuild/issues/95).
Since declaration files are essential for published libraries,
it would be great if @nx/esbuild:esbuild would provide an option to
output them.
## Expected Behavior
- Introduced a new boolean valued `declaration` option for the `esbuild`
executor
- If `declaration` or the tsconfig option
[declaration](https://www.typescriptlang.org/tsconfig#declaration) is
true,
then the TypeScript compiler is used before esbuild to generate the
declarations
- The output directory structure of the declarations can be influenced
by setting the TypeScript rootDir via the `declarationRootDir` option
## Related Issue(s)
https://github.com/nrwl/nx/issues/20688
### Additional Comment
Please note that the generated declaration files directory structure is
affected by the tsconfig `rootDir` property.
For a library that doesn't reference other libraries inside the
monorepo, the `rootDir` property can be changed freely.
If a library inside the monorepo is referenced the `rootDir` property
must be set to the workspace root.
The `tsc` executor has a sophisticated check that automatically sets the
`rootDir` to the workspace root if a library is referenced.
https://github.com/nrwl/nx/blob/master/packages/js/src/executors/tsc/tsc.impl.ts#L104
This check is quite complex and specific to the `tsc` executor options.
Therefore, it hasn't been included inside the esbuild implementation.
The current implementation leaves it to the user to solve the edge case
by removing the `declarationRootDir` option or by setting the
`declarationRootDir` to `.`.
In the future, it might make sense to generalize and use the `tsc`
executor check.
