From 6d215dffa42e23e4182945d938fd3be261351c61 Mon Sep 17 00:00:00 2001 From: Martin <7252614+Lhoerion@users.noreply.github.com> Date: Sun, 13 Jun 2021 18:20:48 +0200 Subject: [PATCH] feat: Improve monorepos by adding support for TS entry points (#1596) --- README.md | 6 ++- src/lib/utils/package-manifest.ts | 40 +++++++++++++++---- src/test/packages.test.ts | 6 ++- .../multi-package/packages/bar/dist/index.js | 6 --- .../packages/bar/dist/index.js.map | 1 - .../multi-package/packages/bar/index.d.ts | 1 + .../multi-package/packages/bar/index.ts | 1 - .../multi-package/packages/bar/package.json | 2 +- .../multi-package/packages/baz/index.ts | 1 + .../multi-package/packages/baz/package.json | 5 +++ .../multi-package/packages/baz/tsconfig.json | 8 ++++ 11 files changed, 57 insertions(+), 20 deletions(-) delete mode 100644 src/test/packages/multi-package/packages/bar/dist/index.js delete mode 100644 src/test/packages/multi-package/packages/bar/dist/index.js.map create mode 100644 src/test/packages/multi-package/packages/bar/index.d.ts delete mode 100644 src/test/packages/multi-package/packages/bar/index.ts create mode 100644 src/test/packages/multi-package/packages/baz/index.ts create mode 100644 src/test/packages/multi-package/packages/baz/package.json create mode 100644 src/test/packages/multi-package/packages/baz/tsconfig.json diff --git a/README.md b/README.md index 27fbe728f..44bc867eb 100644 --- a/README.md +++ b/README.md @@ -37,14 +37,16 @@ typedoc package1/index.ts package2/index.ts ### Monorepos / Workspaces If your codebase is comprised of one or more npm packages, you can pass the paths to these -packages and TypeDoc will attempt to determine entry points from your `package.json`'s `main` -property (or its default value `index.js`). +packages and TypeDoc will attempt to determine entry points based on `package.json`'s `main` +property (with default value `index.js`) and if it wasn't found, based on `types` property. If any of the packages given are the root of an [npm Workspace](https://docs.npmjs.com/cli/v7/using-npm/workspaces) or a [Yarn Workspace](https://classic.yarnpkg.com/en/docs/workspaces/) TypeDoc will find all the `workspaces` defined in the `package.json`. This mode requires sourcemaps in your JS entry points, in order to find the TS entry points. Supports wildcard paths in the same fashion as those found in npm or Yarn workspaces. +:warning: In opposition to project entry points, package entry points are determined relatively to options file if provided. + #### Single npm module ```text diff --git a/src/lib/utils/package-manifest.ts b/src/lib/utils/package-manifest.ts index 98de79a9f..c838e9dfe 100644 --- a/src/lib/utils/package-manifest.ts +++ b/src/lib/utils/package-manifest.ts @@ -2,6 +2,7 @@ import glob = require("glob"); import { dirname, join, resolve } from "path"; +import { existsSync } from "fs"; import { flatMap } from "./array"; import { readFile } from "./fs"; @@ -200,29 +201,52 @@ export function getTsEntryPointForPackage( packageJson: Record ): string | undefined | typeof ignorePackage { let packageMain = "index.js"; // The default, per the npm docs. + let packageTypes = null; if ( hasOwnProperty(packageJson, "main") && typeof packageJson.main == "string" ) { packageMain = packageJson.main; + } else if ( + hasOwnProperty(packageJson, "types") && + typeof packageJson.types == "string" + ) { + packageTypes = packageJson.types; + } else if ( + hasOwnProperty(packageJson, "typings") && + typeof packageJson.typings == "string" + ) { + packageTypes = packageJson.typings; } - let jsEntryPointPath = resolve(packageJsonPath, "..", packageMain); - // The jsEntryPointPath from the package manifest can be like a require path. + let entryPointPath = resolve(packageJsonPath, "..", packageMain); + // The entryPointPath from the package manifest can be like a require path. // It could end with .js, or it could end without .js, or it could be a folder containing an index.js // We can use require.resolve to let node do its magic. // Pass an empty `paths` as node_modules locations do not need to be examined try { - jsEntryPointPath = require.resolve(jsEntryPointPath, { paths: [] }); + entryPointPath = require.resolve(entryPointPath, { paths: [] }); + if (/\.tsx?$/.test(entryPointPath) && existsSync(entryPointPath)) { + return entryPointPath; + } } catch (e) { if (e.code !== "MODULE_NOT_FOUND") { throw e; } else { - logger.warn( - `Could not determine the JS entry point for "${packageJsonPath}". Package will be ignored.` + entryPointPath = resolve( + packageJsonPath, + "..", + packageTypes ?? packageMain ); - logger.verbose(e.message); - return ignorePackage; + if (/\.tsx?$/.test(entryPointPath) && existsSync(entryPointPath)) { + return entryPointPath; + } else { + logger.warn( + `Could not determine the entry point for "${packageJsonPath}". Package will be ignored.` + ); + logger.verbose(e.message); + return ignorePackage; + } } } - return getTsSourceFromJsSource(logger, jsEntryPointPath); + return getTsSourceFromJsSource(logger, entryPointPath); } diff --git a/src/test/packages.test.ts b/src/test/packages.test.ts index 7116dc708..cdede97a2 100644 --- a/src/test/packages.test.ts +++ b/src/test/packages.test.ts @@ -14,7 +14,11 @@ describe("Packages support", () => { const project = app.convert(); equal( project?.children?.map((r) => r.name), - ["typedoc-multi-package-bar", "typedoc-multi-package-foo"] + [ + "typedoc-multi-package-bar", + "typedoc-multi-package-baz", + "typedoc-multi-package-foo", + ] ); }); diff --git a/src/test/packages/multi-package/packages/bar/dist/index.js b/src/test/packages/multi-package/packages/bar/dist/index.js deleted file mode 100644 index 811a3110c..000000000 --- a/src/test/packages/multi-package/packages/bar/dist/index.js +++ /dev/null @@ -1,6 +0,0 @@ -"use strict"; -exports.__esModule = true; -exports.bar = void 0; -function bar() { } -exports.bar = bar; -//# sourceMappingURL=index.js.map \ No newline at end of file diff --git a/src/test/packages/multi-package/packages/bar/dist/index.js.map b/src/test/packages/multi-package/packages/bar/dist/index.js.map deleted file mode 100644 index 455d36401..000000000 --- a/src/test/packages/multi-package/packages/bar/dist/index.js.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":";;;AAAA,SAAgB,GAAG,KAAI,CAAC;AAAxB,kBAAwB"} \ No newline at end of file diff --git a/src/test/packages/multi-package/packages/bar/index.d.ts b/src/test/packages/multi-package/packages/bar/index.d.ts new file mode 100644 index 000000000..d8850a0b6 --- /dev/null +++ b/src/test/packages/multi-package/packages/bar/index.d.ts @@ -0,0 +1 @@ +export function bar(): void; diff --git a/src/test/packages/multi-package/packages/bar/index.ts b/src/test/packages/multi-package/packages/bar/index.ts deleted file mode 100644 index e64329c05..000000000 --- a/src/test/packages/multi-package/packages/bar/index.ts +++ /dev/null @@ -1 +0,0 @@ -export function bar() {} diff --git a/src/test/packages/multi-package/packages/bar/package.json b/src/test/packages/multi-package/packages/bar/package.json index 0ae16a4f3..36cd1509e 100644 --- a/src/test/packages/multi-package/packages/bar/package.json +++ b/src/test/packages/multi-package/packages/bar/package.json @@ -1,5 +1,5 @@ { "name": "typedoc-multi-package-bar", "version": "1.0.0", - "main": "dist/index" + "types": "index.d.ts" } diff --git a/src/test/packages/multi-package/packages/baz/index.ts b/src/test/packages/multi-package/packages/baz/index.ts new file mode 100644 index 000000000..bb93e5892 --- /dev/null +++ b/src/test/packages/multi-package/packages/baz/index.ts @@ -0,0 +1 @@ +export function baz() {} diff --git a/src/test/packages/multi-package/packages/baz/package.json b/src/test/packages/multi-package/packages/baz/package.json new file mode 100644 index 000000000..10518cb7f --- /dev/null +++ b/src/test/packages/multi-package/packages/baz/package.json @@ -0,0 +1,5 @@ +{ + "name": "typedoc-multi-package-baz", + "version": "1.0.0", + "main": "index.ts" +} diff --git a/src/test/packages/multi-package/packages/baz/tsconfig.json b/src/test/packages/multi-package/packages/baz/tsconfig.json new file mode 100644 index 000000000..614afc5c7 --- /dev/null +++ b/src/test/packages/multi-package/packages/baz/tsconfig.json @@ -0,0 +1,8 @@ +{ + "extends": "../../tsconfig.json", + "compilerOptions": { + "outDir": "dist", + "sourceMap": false, + "inlineSourceMap": true + } +}