Default to the package.json source field

[jlarmstrongiv]

Search Terms

Legacy typedoc entry point config (using "typedocMain" field) found for "". Please update to use "typedoc": { "entryPoint": "..." } instead. In future upgrade, "typedocMain" field will be ignored.

package.json source field

Problem

Typedoc understandably needs to know where my source typescript files are.

Suggested Solution

Use the defacto standard of the package.json.source field by default. However, allow overriding the source field by using "typedoc": { "entryPoint": "..." }

The source field in the package.json points to the entry ts file and is used as a defacto standard.

Examples of the source field in the wild are:

• parcel
  • docs https://parceljs.org/features/targets/#entries

  • They can be specified on the CLI, or using the source field in package.json

• microbundle
  • readme https://github.com/developit/microbundle

  • "source": "src/foo.js", // your source code

• Resolving multiple package.json "main" fields microsoft/TypeScript#21423

[akphi]

I'm pretty sure if you don't specify either typedocMain or typedoc.entryPoint, we will resolve by main field

typedoc/src/lib/utils/package-manifest.ts

Lines 243 to 281 in 5060fe2

	export function getTsEntryPointForPackage(
	logger: Logger,
	packageJsonPath: string,
	packageJson: Record<string, unknown>
	): string | undefined | typeof ignorePackage {
	let packageMain = "index.js"; // The default, per the npm docs.
	let packageTypes = null;
	const typedocPackageConfig = extractTypedocConfigFromPackageManifest(
	logger,
	packageJsonPath
	);
	if (typedocPackageConfig?.entryPoint) {
	packageMain = typedocPackageConfig.entryPoint;
	} else if (
	hasOwnProperty(packageJson, "typedocMain") &&
	typeof packageJson.typedocMain == "string"
	) {
	logger.warn(
	`Legacy typedoc entry point config (using "typedocMain" field) found for "${nicePath(
	packageJsonPath
	)}". Please update to use "typedoc": { "entryPoint": "..." } instead. In future upgrade, "typedocMain" field will be ignored.`
	);
	packageMain = packageJson.typedocMain;
	} else 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;
	}

[jlarmstrongiv]

@akphi very interesting! For me, the main field always refers to the compiled dist/index.cjs, rather than the typescript in the source field src/index.ts

[Gerrit0]

I'm somewhat wary of adding even more options for specifying source files without a very clear reason for making the already fairly complicated monorepo code even more so...

If your compiled source contains source maps, TypeDoc in packages mode will automatically resolve the compiled file back to the .ts file.

Another proposal for the use of the typescript:main key: microsoft/TypeScript#12561

---

This source key doesn't seem very commonly used... I have a folder with the 1000-packages dependency installed, which actually installs nearly 19,000 packages. Of these packages, a total of 23 use the source key.

[jlarmstrongiv]

@Gerrit0 alrighty, thank you for your consideration! I do not use source maps in production, so typedoc will not automatically resolve in my case.