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

<!-- 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 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](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)
#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.

docs/generated/packages/esbuild/executors/esbuild.json

@@ -5,7 +5,7 @@
     "version": 2,
     "outputCapture": "direct-nodejs",
     "title": "esbuild (experimental)",
-    "description": "Bundle a package for different platforms. Note: declaration (*.d.ts) file are not currently generated.",
+    "description": "Bundle a package for different platforms.",
     "cli": "nx",
     "type": "object",
     "properties": {
@@ -52,6 +52,14 @@
         "items": { "type": "string", "enum": ["esm", "cjs"] },
         "default": ["esm"]
       },
+      "declaration": {
+        "type": "boolean",
+        "description": "Generate declaration (*.d.ts) files for every TypeScript or JavaScript file inside your project. Should be used for libraries that are published to an npm repository."
+      },
+      "declarationRootDir": {
+        "type": "string",
+        "description": "Sets the rootDir for the declaration (*.d.ts) files."
+      },
       "watch": {
         "type": "boolean",
         "description": "Enable re-building when files change.",

e2e/esbuild/src/esbuild.test.ts

@@ -2,6 +2,7 @@ import {
   checkFilesDoNotExist,
   checkFilesExist,
   cleanupProject,
+  createFile,
   detectPackageManager,
   newProject,
   packageInstall,
@@ -83,7 +84,9 @@ describe('EsBuild Plugin', () => {
     `
     );
     expect(() => runCLI(`build ${myPkg}`)).toThrow();
-    expect(() => runCLI(`build ${myPkg} --skipTypeCheck`)).not.toThrow();
+    expect(() =>
+      runCLI(`build ${myPkg} --skipTypeCheck --no-declaration`)
+    ).not.toThrow();
     expect(runCommand(`node dist/libs/${myPkg}/index.cjs`)).toMatch(/Bye/);
     // Reset file
     updateFile(
@@ -258,4 +261,40 @@ describe('EsBuild Plugin', () => {
     expect(output).not.toMatch(/secret/);
     expect(output).toMatch(/foobar/);
   });
+
+  it('should support declaration builds', () => {
+    const declarationPkg = uniq('declaration-pkg');
+    runCLI(`generate @nx/js:lib ${declarationPkg} --bundler=esbuild`);
+    createFile(
+      `libs/${declarationPkg}/src/lib/testDir/sub.ts`,
+      `
+        export function sub(): string {
+          return 'sub';
+        }
+      `
+    );
+    updateFile(
+      `libs/${declarationPkg}/src/lib/${declarationPkg}.ts`,
+      `
+        import { sub } from './testDir/sub';
+        
+        console.log('${declarationPkg}-' + sub());
+      `
+    );
+
+    runCLI(
+      `build ${declarationPkg} --declaration=true --declarationRootDir='libs/${declarationPkg}/src'`
+    );
+
+    checkFilesExist(
+      `dist/libs/${declarationPkg}/index.cjs`,
+      `dist/libs/${declarationPkg}/index.d.ts`,
+      `dist/libs/${declarationPkg}/lib/${declarationPkg}.d.ts`,
+      `dist/libs/${declarationPkg}/lib/testDir/sub.d.ts`
+    );
+
+    expect(runCommand(`node dist/libs/${declarationPkg}`)).toMatch(
+      new RegExp(`${declarationPkg}-sub`)
+    );
+  }, 300_000);
 });

packages/esbuild/src/executors/esbuild/esbuild.impl.ts

@@ -212,12 +212,17 @@ function getTypeCheckOptions(
   const { watch, tsConfig, outputPath } = options;
 
   const typeCheckOptions: TypeCheckOptions = {
-    // TODO(jack): Add support for d.ts declaration files -- once the `@nx/js:tsc` changes are in we can use the same logic.
-    mode: 'noEmit',
+    ...(options.declaration
+      ? {
+          mode: 'emitDeclarationOnly',
+          outDir: outputPath,
+        }
+      : {
+          mode: 'noEmit',
+        }),
     tsConfigPath: tsConfig,
-    // outDir: outputPath,
     workspaceRoot: context.root,
-    rootDir: context.root,
+    rootDir: options.declarationRootDir ?? context.root,
   };
 
   if (watch) {

packages/esbuild/src/executors/esbuild/lib/normalize.spec.ts

@@ -1,12 +1,34 @@
 import { normalizeOptions } from './normalize';
 import { ExecutorContext } from '@nx/devkit';
+import { readTsConfig } from '@nx/js';
+
+jest.mock<typeof import('@nx/js')>('@nx/js', () => {
+  const actualModule = jest.requireActual('@nx/js');
+
+  return {
+    ...actualModule,
+    readTsConfig: jest.fn(() => ({
+      fileNames: [],
+      errors: [],
+      options: {},
+    })),
+  };
+});
 
 describe('normalizeOptions', () => {
   const context: ExecutorContext = {
     root: '/',
     cwd: '/',
     isVerbose: false,
     projectName: 'myapp',
+    projectsConfigurations: {
+      version: 2,
+      projects: {
+        myapp: {
+          root: 'apps/myapp',
+        },
+      },
+    },
     projectGraph: {
       nodes: {
         myapp: {
@@ -142,6 +164,31 @@ describe('normalizeOptions', () => {
     });
   });
 
+  it("should use the tsconfig declaration option if the declaration option isn't defined", () => {
+    (
+      readTsConfig as jest.MockedFunction<typeof readTsConfig>
+    ).mockImplementationOnce(() => ({
+      fileNames: [],
+      errors: [],
+      options: {
+        declaration: true,
+      },
+    }));
+
+    expect(
+      normalizeOptions(
+        {
+          main: 'apps/myapp/src/index.ts',
+          outputPath: 'dist/apps/myapp',
+          tsConfig: 'apps/myapp/tsconfig.app.json',
+          generatePackageJson: true,
+          assets: [],
+        },
+        context
+      )
+    ).toEqual(expect.objectContaining({ declaration: true }));
+  });
+
   it('should override thirdParty if bundle:false', () => {
     expect(
       normalizeOptions(
@@ -158,4 +205,21 @@ describe('normalizeOptions', () => {
       )
     ).toEqual(expect.objectContaining({ thirdParty: false }));
   });
+
+  it('should override skipTypeCheck if declaration:true', () => {
+    expect(
+      normalizeOptions(
+        {
+          main: 'apps/myapp/src/index.ts',
+          outputPath: 'dist/apps/myapp',
+          tsConfig: 'apps/myapp/tsconfig.app.json',
+          generatePackageJson: true,
+          skipTypeCheck: true,
+          declaration: true,
+          assets: [],
+        },
+        context
+      )
+    ).toEqual(expect.objectContaining({ skipTypeCheck: false }));
+  });
 });

packages/esbuild/src/executors/esbuild/lib/normalize.ts

@@ -7,11 +7,14 @@ import {
 import { ExecutorContext, joinPathFragments, logger } from '@nx/devkit';
 import chalk = require('chalk');
 import * as esbuild from 'esbuild';
+import { readTsConfig } from '@nx/js';
 
 export function normalizeOptions(
   options: EsBuildExecutorOptions,
   context: ExecutorContext
 ): NormalizedEsBuildExecutorOptions {
+  const tsConfig = readTsConfig(options.tsConfig);
+
   // If we're not generating package.json file, then copy it as-is as an asset.
   const assets = options.generatePackageJson
     ? options.assets
@@ -39,6 +42,33 @@ export function normalizeOptions(
 
   const thirdParty = !options.bundle ? false : options.thirdParty;
 
+  const { root: projectRoot } =
+    context.projectsConfigurations.projects[context.projectName];
+  const declarationRootDir = options.declarationRootDir
+    ? path.join(context.root, options.declarationRootDir)
+    : undefined;
+
+  // if option declaration is defined, then it takes precedence over the tsconfig option
+  const declaration =
+    options.declaration ??
+    (tsConfig.options.declaration || tsConfig.options.composite);
+
+  if (options.skipTypeCheck && declaration) {
+    logger.info(
+      chalk.yellow(
+        `Your build has conflicting options, ${chalk.bold(
+          'skipTypeCheck:true'
+        )} and ${chalk.bold(
+          'declaration:true'
+        )}. Your declarations won't be generated so we added an update ${chalk.bold(
+          'skipTypeCheck:false'
+        )}`
+      )
+    );
+  }
+
+  const skipTypeCheck = declaration ? false : options.skipTypeCheck;
+
   let userDefinedBuildOptions: esbuild.BuildOptions;
   if (options.esbuildConfig) {
     const userDefinedConfig = path.resolve(context.root, options.esbuildConfig);
@@ -67,6 +97,9 @@ export function normalizeOptions(
       ...rest,
       thirdParty,
       assets,
+      declaration,
+      declarationRootDir,
+      skipTypeCheck,
       userDefinedBuildOptions,
       external: options.external ?? [],
       singleEntry: false,
@@ -80,6 +113,9 @@ export function normalizeOptions(
       ...options,
       thirdParty,
       assets,
+      declaration,
+      declarationRootDir,
+      skipTypeCheck,
       userDefinedBuildOptions,
       external: options.external ?? [],
       singleEntry: true,

packages/esbuild/src/executors/esbuild/schema.d.ts

@@ -7,6 +7,8 @@ export interface EsBuildExecutorOptions {
   additionalEntryPoints?: string[];
   assets: (AssetGlob | string)[];
   bundle?: boolean;
+  declaration?: boolean;
+  declarationRootDir?: string;
   deleteOutputPath?: boolean;
   esbuildOptions?: Record<string, any>;
   esbuildConfig?: string;

packages/esbuild/src/executors/esbuild/schema.json

@@ -2,7 +2,7 @@
   "version": 2,
   "outputCapture": "direct-nodejs",
   "title": "esbuild (experimental)",
-  "description": "Bundle a package for different platforms. Note: declaration (*.d.ts) file are not currently generated.",
+  "description": "Bundle a package for different platforms.",
   "cli": "nx",
   "type": "object",
   "properties": {
@@ -54,6 +54,14 @@
       },
       "default": ["esm"]
     },
+    "declaration": {
+      "type": "boolean",
+      "description": "Generate declaration (*.d.ts) files for every TypeScript or JavaScript file inside your project. Should be used for libraries that are published to an npm repository."
+    },
+    "declarationRootDir": {
+      "type": "string",
+      "description": "Sets the rootDir for the declaration (*.d.ts) files."
+    },
     "watch": {
       "type": "boolean",
       "description": "Enable re-building when files change.",