Fails to identify name/version due to the presence of an unexpected package.json

[ilg-ul]

Search terms

warning name version package.json

Expected Behavior

Pick the name & version from the project package.json.

Actual Behavior

Tries to get the name and version from src/package.json and fails, since in that file there is only a type: module definition, (required by the dual CommonJS/ES6 module nature of the project).

Steps to reproduce the bug

Assuming the entry point is src/index.ts, add a minimal src/package.json like:

{
  "type": "module"
}

This will confuse typedoc, which will no longer be able to identify the name/version:

> typedoc --logLevel Verbose

Using TypeScript 4.9.5 from ./node_modules/typescript/lib
Converting with 1 programs 1 entry points
Finished getting entry points in 724ms
Begin readme.md/package.json search at ./src <---
warning The --name option was not specified, and package.json does not have a name field. Defaulting project name to "Documentation".
warning --includeVersion was specified, but package.json does not specify a version.
Finished conversion in 124ms
Validation took 1ms
Renderer: Loading highlighter took 374ms
Documentation generated at ./docs
HTML rendering took 664ms

I think that a better strategy would be to iterate to the parent folder and try to read the name/version from there, until the project root is reached.

As a partial workaround, I also added the project name to this short package.json, but the version remained undefined.

Environment

• Typedoc version: 0.23.26
• TypeScript version: 4.9.5
• Node.js version: 14.21.2
• OS: macOS 12.6.3

[ilg-ul]

Another solution would be to add a configuration option like --packageJson to provide the path to the package.json file.

This would be preferred and also consistent with --readme

Note: in my project there is also a src/README.md file, and by default typedoc selects it, thus I have to explicitly specify "readme": "./README.md", in typedoc.json.

It would be natural to also specify "packageJson": "./package.json",.

[Gerrit0]

It seems reasonable to me to ignore a package.json if there is no name field, should take care of the esm use case. The packageJson option might not be necessary then.

[ilg-ul]

Sure, the first solution is more automated, but would probably require a bit more effort to implement.

[ilg-ul]

If this problem was fixed by 63a521c, you can close this issue.

[Gerrit0]

I leave issues open until the fix has been released - this is a part of 0.24, so isn't out yet

[tintinthong]

Here is a suggestion.

After playing with typedoc, I realise that we don't necessarily want the version tag from package.json. We may want it from lerna.json for example. Or god knows wherever else.

Is it possible more flexible to specify a --version flag like typedoc --version 0.0.1 . I know this conflicts with another tag which displays the version.

[ilg-ul]

lerna.json

There was also an alternate suggestion to use --packageJson to pass any file path.

[tintinthong]

lerna.json

There was also an alternate suggestion to use --packageJson to pass any file path.

Yea indeed this feature seems possibly useful.

Actually now that I think about it, passing command line arguments( either for packageJson or version) is probably the wrong way philosophically If we are dealing with monorepos.

[ilg-ul]

passing command line arguments( either for packageJson or version) is probably the wrong way philosophically If we are dealing with monorepos

Could you elaborate? What might be wrong with command line arguments?

[tintinthong]

passing command line arguments( either for packageJson or version) is probably the wrong way philosophically If we are dealing with monorepos

Could you elaborate? What might be wrong with command line arguments?

What I am mentioning should be related to monorepos, particularly the use entryPointStrategy=packages. If we specify a --version, it is unclear if the version corresponds to which subpackage. This is simlar if we specify --packageJson.

One "workaround" is to assume that all subpackages share the same version. The default lerna strategy for this is the Fixed/Locked mode but there is alternative strategy called Independent mode. In Independent mode we cannot assume each subpackage share the same version

See here

I presume this is a general matter of using npm/yarn workspaces

[tintinthong]

Perhaps the other entryPointStrategy options, a command-line argument would make sense

[ilg-ul]

@tintinthong, I'm afraid I can't be of much help, I personally split all my projects into separate small, independent repos, with separate CI tests, so I don't encounter the issues you mentioned.

[tintinthong]

passing command line arguments( either for packageJson or version) is probably the wrong way philosophically If we are dealing with monorepos

Could you elaborate? What might be wrong with command line arguments?

What I am mentioning should be related to monorepos, particularly the use entryPointStrategy=packages. If we specify a --version, it is unclear if the version corresponds to which subpackage. This is simlar if we specify --packageJson.

One "workaround" is to assume that all subpackages share the same version. The default lerna strategy for this is the Fixed/Locked mode but there is alternative strategy called Independent mode. In Independent mode we cannot assume each subpackage share the same version

See here

I presume this is a general matter of using npm/yarn workspaces

@Gerrit0 does that make sense?

Just a question related. Is there a plugin example that modifies the app state? Since maybe I can write a plugin that does this that changes the behaviour of typedoc a bit

[Gerrit0]

Basically every plugin modifies some typedoc behavior... a projectVersion option seems like a useful option in case the package.json has a bad version.

0.24 completely reworks packages mode so that it effectively runs TypeDoc in each package directory, then merges the results together, so versions in packages/foo/package.json will be correctly applied

[tintinthong]

Basically every plugin modifies some typedoc behavior... a projectVersion option seems like a useful option in case the package.json has a bad version.

0.24 completely reworks packages mode so that it effectively runs TypeDoc in each package directory, then merges the results together, so versions in packages/foo/package.json will be correctly applied

thanks for the clarification. Actually good idea to wait on 0.24 before making any changes. My workaround currently is to fork the typedoc-plugin-versions and add a new option from there