TypeDoc v0.28 Beta

[Gerrit0]

TypeDoc 0.28 is now in beta! 🎉

Please try it out and report any issues in new issues:

npm install --save-dev typedoc@beta

The full release is planned for 2025-03-14.

This release includes a major refactor to support a typedoc/browser import suitable for use in frontend code which interacts with TypeDoc's JSON output and an updated search dialog which behaves better on mobile devices.

Default Theme Changes

@phoneticallySAARTHaK rebuilt TypeDoc's search dialog, resulting in an implementation which behaves much better on mobile devices and improved accessibility for screen readers.

Browser Entrypoint

TypeDoc's main entry point uses many node APIs during conversion making it unsuitable for usage in the browser. With this release, TypeDoc also provides typedoc/browser and typedoc/browser/(lang) entry points which can be used in a browser bundle which needs to parse TypeDoc's JSON output.

import {
    ConsoleLogger,
    Deserializer,
    FileRegistry,
    setTranslations,
} from "typedoc/browser";

// Similar paths are available for ja, ko, zh
import translations from "typedoc/browser/en";

// Before doing anything with TypeDoc, it should be configured with translations
setTranslations(translations);

const projectJson = await fetch("...").then(r => r.json());

const logger = new ConsoleLogger();
const deserializer = new Deserializer(logger);
const project = deserializer.reviveProject("API Docs", projectJson, {
    projectRoot: "/",
    registry: new FileRegistry(),
});

// Now we can use TypeDoc's models to more easily analyze the json
console.log(project.getChildByName("SomeClass.property"));
console.log(project.getChildByName("SomeClass.property").type.toString());

Change Log

Breaking Changes

• TypeDoc now expects all input globs paths to be specified with / path separators, Unable to doc file located in a dir with [] #2825.
• TypeDoc's --entryPointStrategy merge mode now requires JSON from at least version 0.28.0.
• Removed jp translations from lang, to migrate switch to ja.
• File name references in intentionallyNotExported now use a package name/package relative path instead of an absolute path for matching.
• The source-order sort ordering now considers package names / package relative paths instead of using the absolute paths to a file.

API Breaking Changes

• Path and PathArray parameter types now always contain normalized paths.
• Introduced a Router which is used for URL creation. Reflection.url,
  Reflection.anchor, and Reflection.hasOwnDocument have been removed.
• Deserializer.reviveProject(s) no longer accepts an option to add project documents.
• Deserializer.reviveProjects now requires an alwaysCreateEntryPointModule option.
• Comment.serializeDisplayParts no longer requires a serializer argument.
• ReflectionSymbolId.fileName has been removed, TypeDoc now stores a combination of a package name and package relative path instead.
• Removed DeclarationReflection.relevanceBoost attribute which was added for plugins, but never used.
• i18n proxy is no longer passed to many functions, instead, reference i18n exported from the module directly.
• ReflectionKind.singularString and ReflectionKind.pluralString now returns translated strings.
  The methods on Internationalization to do this previously have been removed.
• The HTML output structure for the search box has changed to support the new modal.

Features

• Add support for TypeScript 5.8.x
• The search modal in the HTML output has been rewritten to provide better mobile support
• Added a --router option which can be used to modify TypeDoc's output folder
  structure. This can be extended with plugins, Support for custom output directory structure #2111.
• Introduced the @primaryExport modifier tag to provide more fine grained
  control over export conversion order, Feature / Observation: Order matters in files processed regarding reflection generation for ambient namespace re-exports. #2856
• Introduced packagesRequiringDocumentation option for validation.notDocumented, TypeDoc will expect comments to be present for symbols in the specified packages.
• TypeDoc now exports a typedoc/browser entrypoint for parsing and using serialized JSON files, Runtime traversal utils for browser usage #2528.

Bug Fixes

• TypeDoc will now only create references for symbols re-exported from modules.
• Variable-functions will now prefer placing the comment on the signature if there is only one signature present, #2521 changed the behavior of documented arrow function #2824.
• User filter settings will no longer sometimes cause the search to have fewer visible results than expected.

[felipecrs]

I think there's another breaking change that wasn't listed:

TypeError: context.project.getSymbolFromReflection is not a function

[Gerrit0]

Technically that one shouldn't need a breaking change notice as it was marked internal, but I agree, it deserves one and basically every non-trivial plugin uses it... it moved to Context

[Gerrit0]

0.28.0-beta.1

• Function-like variable exports will now only be automatically converted as function types if
  they are initialized with a function expression. TypeDoc can be instructed to convert them as functions
  with the @function tag, Allow documenting callable objects as being variables of their declared type (rather than a function+namespace with duplicated docs and no type declaration/link) #2881.
• TypeDoc will only check for a project README file next to the discovered package.json file if --readme is not set
  this change improves handling of monorepo setups where some packages have readme files and others do not, TypeDoc should check for the README file adjacent to the package.json for a project #2875.
• Fixed formatting of type parameters, Missing whitespace in type parameters (beta) #2882.
• Fixed bug in logger which would cause links to the current page being rendered as #undefined
• Type packageOptions as Partial<TypeDocOptions>, TypeDocOptions seems to be missing Partial for packageOptions #2878.
• TypeDoc will now warn if an option which should only be set at the root level is set in packageOptions, TypeDocOptions seems to be missing Partial for packageOptions #2878.
• Fixed handling of expando functions which were also merged with a namespace, Functions defined as namespaces with multiple declarations not resolved correctly #2876.

[Gerrit0]

0.28.0-beta.2

This will likely be the last beta before release, which might end up being pushed out until the 16th as I am going to be very busy this Friday.

• Improved alignment of some icons within the default theme
• Add support for @preventInline and @inlineType tags, Opposite of @expand/@inline #2862
• Add support for @prevenExpand and @expandType tags, Opposite of @expand/@inline #2862
• Fixed more missing whitespace when rendering types, Missing whitespace in type parameters (beta) #2882
• API: Enable more granular control over reflection icons (603344e)
• Object literal type alias types will now be converted in a way which causes them to be rendered more similarly
  to how interfaces are rendered, include table of contents & index on type aliases that contain properties #2817.

[Gerrit0]

Not going to be tonight... which means it will be the 16th. Running some last few checks before making the release revealed some unexpected differences on a test project that needs investigation.