Unable to setup typedoc in a nx monorepo

[MrOnlineCoder]

Search terms

monorepo, nx

Question

Hey, I am having a similiar setup as in #2061 - a pretty large project as nx monorepo, which contains both web (React) apps and some standalone libraries.

I want to generate docs for the libraries which are located at path libs/data

The typedoc config is following, I've added one package products just for sake of testing/simplicity, but there are more:

{
  "out": "docs",
  "entryPointStrategy": "packages",
  "entryPoints": [
    "libs/data/products"
  ]
}

The package.json for the products package is following:

{
  "name": "@mycompany/products",
  "version": "0.0.1",
  "main": "./src/index.ts",
  "typedoc": {
    "entryPoint": "./src/index.ts",
    "readmeFile": "./README.md",
    "displayName": "@mycompany/products"
  }
}

However I am getting these errors:

error TS6305: Output file '...../libs/data/products/src/service.d.ts' has not been built from source file '..../libs/data/products/src/service.ts'.
  The file is in the program because:
    Root file specified for compilation
    
error TS6306: Referenced project '....../libs/data/products/tsconfig.lib.json' must have setting "composite": true
error TS6306: Referenced project '....../libs/data/products/tsconfig.spec.json' must have setting "composite": true

Any advices on how to fix it? Thanks in advance.
Please note, that I cannot apply same solution of renaming every tsconfig file as mentioned in the linked issue above - the project is too large for that.

Node v.14.18.2
yarn 1.22.19
nx 13.1.2
typedoc 0.23
typescript 4.5.5 (I am aware of compatibiltiy issues with that typedoc version, however, typedoc@0.22 seems to be lack of the child package.json setup)

[Gerrit0]

Sounds like you need the feature in #2061 to me. You could probably work around this with a script that generates a tsconfig that extends the "real" tsconfig, runs typedoc, then removes it.

[MrOnlineCoder]

@Gerrit0 thanks for reply! Do you mean to generate the tsconfig.json for every child package before running typedoc?

[Gerrit0]

Yeah, very hacky way of getting around it, but...

[MrOnlineCoder]

@Gerrit0 Got it, I'll try to make a work around and post here if I have any success or failures, maybe someone will find it useful until further resolve

[MrOnlineCoder]

@Gerrit0 ah, sorry, just found, that nx already generates a tsconfig file in child packages with contents like that:

{
  "extends": "../../../../tsconfig.base.json",
  "files": [],
  "include": ["./src"],
  "references": [
    {
      "path": "./tsconfig.lib.json"
    },
    {
      "path": "./tsconfig.spec.json"
    }
  ],
  "compilerOptions": {
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true
  }
}

[Gerrit0]

Just to confirm:

1. Does npx tsc -p path/to/tsconfig.lib.json --noEmit exit with no errors?
2. Does npx tsc -p path/to/tsconfig.json --noEmit exit with the same errors as TypeDoc?

[MrOnlineCoder]

@Gerrit0

1. Fails with other errors like error TS2591: Cannot find name 'process'. Do you need to install type definitions for node? Try npm i --save-dev @types/node and then add 'node' to the types field in your tsconfig
2. Yea, though the error output is a little bit more verbose, but the errors are the same

[Gerrit0]

Given that, even with a tsconfig option it sounds like TypeDoc will still fail to build. Your project needs to be able to compile in order for TypeDoc to work correctly...

[MrOnlineCoder]

@Gerrit0 correct, but there is catch.

If I run yarn nx build <my project name> it successfully builds it without any error. So I suppose nx is doing some 'magic' under the hood to make the project build successfully.

Moreover, by default nx generates package tsconfig with empty includes: [] option, so if I run typedoc without adding ./src to it, the error would be as following:

Entry point "libs/data/products/src/index.ts" does not appear to be built by/included in the tsconfig found at "libs/data/products/tsconfig.json"

On other hand, If I include src folders for build, the errors described in first comment appear.

nx build succeds regardless of the value for includes option in tsconfig.json

[Gerrit0]

Hmm... could you by chance create an example project that is similar to your real project that I could poke at? If it's really doing magic, can't promise I'll support that, but if I can figure out how to get a successful build with tsc, might be able to provide better guidance.

[MrOnlineCoder]

Trying to create as similiar but minimal example to reproduce the error

[MrOnlineCoder]

@Gerrit0 here is minimal example: https://github.com/MrOnlineCoder/typedoc_nx_issue

typedoc gives the same error as in my main project.

Project was setup under node 14.18.2 and yarn 1.22.19, using next commands:

yarn global add nx
yarn create nx-workspace
yarn nx generate @nrwl/web:lib products-service --directory=data/services --buildable --importPath=@myapp/products-service --publishable

[MrOnlineCoder]

Update: I've tried updating to latest typedoc version with tsconfig option support for separate packages and setting it to 'tsconfig.lib.json', but it didn't work too:

TypeError: context.checker.getTypeOfSymbol is not a function
    at Object.convertProperty (.../node_modules/typedoc/dist/lib/converter/symbols.js:362:25)

[Carduelis]

Can confirm inability to work with monorepo with nx and lerna

When entryPointsStrategy is set to packages I get the error:

error Tried to set an option (entryPointsStrategy) that was not declared.

But it is declared like this:

{
  "tsconfig": "./tsconfig.base.json",
  "entryPoints": [
    "packages/time/src/index.ts",
    "packages/ui/src/index.ts",
    "packages/utils/src/index.ts"
  ],
  "entryPointsStrategy": "packages",
  "exclude": [],
  "out": "docs",
  "name": "Insided Packages",
  "pretty": true
}

By any configuration it does not use child (leaf) package.jsons typedoc property. For example, I would like to use tsconfig.json files per package (some packages are react-based, some not).

And I would like to use a custom .md (in my case Changelog by Conventional Commits) on page of each package.

[Carduelis]

Just to confirm:

1. Does npx tsc -p path/to/tsconfig.lib.json --noEmit exit with no errors?
2. Does npx tsc -p path/to/tsconfig.json --noEmit exit with the same errors as TypeDoc?

They work fine for me.

[Gerrit0]

@Gerrit0 here is minimal example: https://github.com/MrOnlineCoder/typedoc_nx_issue

With the following changes, documentation generates as expected.

diff --git a/libs/data/services/products-service/package.json b/libs/data/services/products-service/package.json
index 5e81c08..7281d96 100644
--- a/libs/data/services/products-service/package.json
+++ b/libs/data/services/products-service/package.json
@@ -4,6 +4,7 @@
   "typedoc": {
     "entryPoint": "./src/index.ts",
     "readmeFile": "./README.md",
-    "displayName": "@myapp/products-service"
+    "displayName": "@myapp/products-service",
+    "tsconfig": "tsconfig.lib.json"
   }
 }

Update: I've tried updating to latest typedoc version with tsconfig option support for separate packages and setting it to 'tsconfig.lib.json', but it didn't work too:

TypeError: context.checker.getTypeOfSymbol is not a function
    at Object.convertProperty (.../node_modules/typedoc/dist/lib/converter/symbols.js:362:25)

Apparently I need to make the warning about running with unsupported versions of TypeDoc louder. TypeScript 4.5 is not supported. If you upgrade TypeScript, this error will go away.

When entryPointsStrategy is set to packages I get the error:

The option is entryPointStrategy, not entryPointsStrategy. For packages mode, you should also specify package directories containing package.json as your entry points, not files.

[Carduelis]

@Gerrit0 oh! thank you! My bad. The part: or packages mode, you should also specify package directories containing package.json as your entry points, not files. is super crucial as well. I could not figure it out when I used the correct spelling of this flag. Now I understand, why were there two different error messages.

[MrOnlineCoder]

@Gerrit0 thanks for investing time into my issue. I'll try to update the Typescript - though I've seen the warning, I didn't want to update it because of unknown consequences of that on other apps in the project of updating the ts version, even if it's a minor one. And it said it may work, but it might break - and thus I tried my luck

[MrOnlineCoder]

@Gerrit0 thanks for help again, issue seems to be resolved, upgrading typescript and adding tsconfig to package.json was the way for fixing.