feat(bundling): added support for declarations (*.d.ts)

[castleadmin]

Current Behavior

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.

Expected Behavior

• Introduced a new boolean valued declaration option for the esbuild executor
• If declaration or the tsconfig option 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)

#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.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
nx-dev	✅ Ready (Inspect)	Visit Preview	May 9, 2024 2:08pm

[nx-cloud]

☁️ Nx Cloud Report

CI is running/has finished running commands for commit 5136a13. As they complete they will appear below. Click to see the status, the terminal output, and the build insights.

📂 See all runs for this CI Pipeline Execution

---

✅ Successfully ran 6 targets

• nx affected --targets=e2e,e2e-ci --base=25574ae614afd3200508bbd77cc888d9e66d5055 --head=5136a13bb9aeeed35b57d13ba901a7f8223d9a78 --parallel=1
• nx affected --targets=lint,test,build --base=25574ae614afd3200508bbd77cc888d9e66d5055 --head=5136a13bb9aeeed35b57d13ba901a7f8223d9a78 --parallel=3
• nx run-many -t check-imports check-commit check-lock-files check-codeowners documentation --parallel=1 --no-dte
• nx-cloud record -- nx format:check --base=25574ae614afd3200508bbd77cc888d9e66d5055 --head=5136a13bb9aeeed35b57d13ba901a7f8223d9a78
• nx documentation --no-dte
• nx affected -t e2e-macos-ci --parallel=1 --base=25574ae614afd3200508bbd77cc888d9e66d5055 --head=5136a13bb9aeeed35b57d13ba901a7f8223d9a78

---

Sent with 💌 from NxCloud.

[Afellman]

Any progress on this? My team is waiting for it.

[mandarini]

Tested this locally, and the tests on CI seem to pass, so I am going to merge.

However, once esbuild is part of the crystal project, this functionality will go away, since we will be relying on the native features of esbuild.

[danielsharvey]

Tested this locally, and the tests on CI seem to pass, so I am going to merge.

Thank you

However, once esbuild is part of the crystal project, this functionality will go away, since we will be relying on the native features of esbuild.

What approach would you recommend in the context of Project Crystal?

[castleadmin]

An esbuild plugin could be a viable alternative to support declaration file builds.

esbuild-plugin-d.ts is listed on the esbuild plugin page and provides the needed functionality.

Another solution that doesn't rely on third-party plugins would be to split the current implementation into 2 commands.

• Build the declaration files with the help of tsc
• Build the project with esbuild

If the clearing of the output directory and caching doesn't interfere, then a solution that uses 2 commands should work fine.

[danielsharvey]

Another solution that doesn't rely on third-party plugins would be to split the current implementation into 2 commands.

• Build the declaration files with the help of tsc
• Build the project with esbuild

👍🏻 This is what I currently do (though an OOB integrated solution would be nice!)

[github-actions]

This pull request has already been merged/closed. If you experience issues related to these changes, please open a new issue referencing this pull request.