react-docgen

Patch Changes

• #1036
  a122bff
  Thanks @DiogoDoreto! - Do not fail when
  resolving inside ObjectMethod nodes

New Contributors

• @DiogoDoreto made their first contribution in #1036

Full Changelog: https://github.com/reactjs/react-docgen/compare/@react-docgen/cli@3.0.3...react-docgen@8.0.2

Patch Changes

• #1009
  4c7dd9d
  Thanks @danez! - Do not fail on new VoidPattern
  type

Major Changes

• #942
  c3dfead
  Thanks @danez! - Drop support for Node.js 16, 17,
  18, 19 and 21.

  With this react-docgen version Node.js support is:

  • Node.js 20.9.0 or newer 20.x versions
  • Node.js 22.0.0 or any newer version

Patch Changes

• #993
  06c2fae
  Thanks @danez! - Fixed crash when classes with
  private fields are used

Patch Changes

• #969 639bf37 Thanks @christon88! - Expose more TypeScript types

Minor Changes

• #923 3033ca0 Thanks @rvetere! - Support generic types on React.forwardRef calls.

  Example:

  react-docgen will now find IButtonProps.

  export const FullWidthButton = forwardRef<HTMLButtonElement, IButtonProps>(
    () => {},
  );
  

Patch Changes

• #890 afe8d02 Thanks @danez! - Do not throw error when using namespace specifiers in export statements

Patch Changes

• 64bf1aa Thanks @danez! - Fix handling of template literals

Patch Changes

• #870 2b51bbd Thanks @renovate! - update dependency @types/doctrine to ^0.0.9

Major Changes

• #846 82154c3 Thanks @danez! - getTypeFromReactComponent now returns an array of paths to types instead of just one. This can appear when multiple type definitions are found for a component, for example:

  const Component: React.FC<Props> = (props: { some: string }) => {};
  

  In this example both the Props definition as well as { some: string } are now found and used.

  Here is a simple diff to illustrate the change when using getTypeFromReactComponent:

  
  const type = getTypeFromReactComponent(path)
  
  -if (type) {
  +if (type.length > 0) {
      // do smth
  }
  
  

• #848 dda8915 Thanks @danez! - Drop support for Node.js version 14.

  The minimum supported version is now 16.14.0

• #846 62e692f Thanks @danez! - resolveToValue will not resolve to ImportDeclaration anymore but instead to one of the possible specifiers (ImportSpecifier, ImportDefaultSpecifier or ImportNamespaceSpecifier). This gives better understanding to which specifier exactly resolveToValue did resolve a NodePath to.

  Here is a possible easy fix for this in a code snippet that uses resolveToValue

  const resolved = resolveToValue(path);
  
  -if (resolved.isImportDeclaration()) {
  +if (resolved.parentPath?.isImportDeclaration()) {
      // do smth
  }
  

Minor Changes

• #862 40ebb00 Thanks @danez! - Support PropsWithoutRef, PropsWithRef and PropsWithChildren in TypeScript.

  Component props are now detected correctly when these builtin types are used, but they do currently not add any props to the documentation.

• #846 82154c3 Thanks @danez! - Add support for React.FC in TypeScript.

Patch Changes

• 6312f2f Thanks @renovate[bot]! - update dependency @types/doctrine to ^0.0.7

• #846 c01d1a0 Thanks @danez! - Fix detection of react class components when super class is imported via named import.

• #861 74b6680 Thanks @renovate! - update dependency @types/doctrine to ^0.0.8

• #846 0641700 Thanks @danez! - Remove unnecessary call to resolveToValue when trying to find props type from react components.

• #858 3be404e Thanks @danez! - Fix detection of React.Children with ESM imports

Patch Changes

• #838 8ba9ac7 Thanks @danez! - Support index types correctly in flow

Patch Changes

• #830 c3c16e3 Thanks @danez! - Fixed error with object and array patterns in function signatures.

Patch Changes

• #810 ddf4e20 Thanks @danez! - Read docblock in nested flow object types and use them as descriptions

Patch Changes

• #806 c7e2bd5 Thanks @danez! - Make docblocks for assigned methods be correctly detected.

Major Changes

• 96d6e9e Thanks @danez! - Rename flowTypeHandler to codeTypeHandler because it handles Flow and TypeScript

• #719 d7a39af Thanks @danez! - Refactored resolveComponentDefinition utility.

  • Renamed to findComponentDefinition
  • Removed named export isComponentDefinition
  • The utility now does a lot more than previously, check out the commit to see the changes in detail.

• #761 dfc2f85 Thanks @danez! - Renamed propDocBlockHandler to propDocblockHandler for consistency

• 96d6e9e Thanks @danez! - Simplify resolveObjectValuesToArray and remove type handling. None of the code that was handling types was used.

• caae6bf Thanks @danez! - The return values of resolveObjectValuesToArray are now in the order they are defined in the source code.

• #744 e956802 Thanks @danez! - Removed match utility.

  The utility can be replaced by babel helpers and is not needed anymore. Also using explicit checks like path.isMemberExpression() is better for type safety and catching potential bugs.

• 96d6e9e Thanks @danez! - Migrate react-docgen to ES modules. Please read this

• #693 3b28f6e Thanks @danez! - The CLI was removed from react-docgen into its own package @react-docgen/cli.

  Check out https://react-docgen.dev/docs/getting-started/cli for the documentation.

• 96d6e9e Thanks @danez! - The main parse API had some breaking changes.

  • The arguments were changed from previously 5 to just 2. The following diff illustrates how to migrate:

    -parse(src, resolver, handlers, importer, options: { filename, ...babelOptions})
    +parse(src, { resolver, handlers, importer, filename, babelOptions: {} })
    

  • The return type is now always an array, independent of the resolver, even if only one component was found in the file.

• #786 0a2481d Thanks @danez! - Renamed the method toObject to build in the DocumentationBuilder.

  This method might be used by integrations.

• 96d6e9e Thanks @danez! - Renamed some of the main exports for clarity.

  Renamed handlers to builtinHandlers Renamed resolver to builtinResolvers Renamed importers to builtinImporters

• #743 5215bab Thanks @danez! - Removed support for the @extends React.Component annotation on react class components.

  Instead, you can use the new @component annotation or define your own annotation by creating a custom FindAnnotatedDefinitionsResolver instance

• #714 80e4c74 Thanks @danez! - Renamed and migrated built-in resolvers to classes.

  • findAllComponentDefinitions was renamed to FindAllDefinitionsResolver and is now a class.

    -const resolver = builtinResolvers.findAllComponentDefinitions
    +const resolver = new builtinResolvers.FindAllDefinitionsResolver()
    

  • findAllExportedComponentDefinitions was renamed to FindExportedDefinitionsResolver and is now a class.

    -const resolver = builtinResolvers.findAllExportedComponentDefinitions
    +const resolver = new builtinResolvers.FindExportedDefinitionsResolver()
    

  • findExportedComponentDefinition was removed. Use FindExportedDefinitionsResolver with the limit option instead.

    This is still the default resolver.

    -const resolver = builtinResolvers.findExportedComponentDefinition
    +const resolver = new builtinResolvers.FindExportedDefinitionsResolver({ limit: 1 })
    

• 96d6e9e Thanks @danez! - Migrated to babel toolchain

  This is one of the big changes in this new version of react-docgen. It made the code a lot more robust because there are now finally working TypeScript types for the ASTs.

  Another benefit from this change is that react-docgen is now a lot faster. 🚀 In some tests an improvement of nearly 50% was seen in comparison to version 5.

• #707 d4c27d4 Thanks @danez! - Improve performance of file system importer.

  The file system importer now also caches the resolving of files in addition to parsing files. If the importer is used in an environment where files do change at runtime (like a watch command) then the caches will need to be cleared on every file change.

• 96d6e9e Thanks @danez! - Changed the minimum Node.js version to 14.18.0

Minor Changes

• 96d6e9e Thanks @danez! - Add support for .cts and .mts extension when using typescript

• 96d6e9e Thanks @danez! - Treat functions returning React.Children.map as components

• 96d6e9e Thanks @danez! - Improve performance by creating all visitors only once

• 96d6e9e Thanks @danez! - Support all possible kinds of functions in the displayNameHandler

• #786 0a2481d Thanks @danez! - Export the type for the DocumentationBuilder.

• #786 0a2481d Thanks @danez! - The types NodePath and babelTypes are now exported.

  These types are useful when building integrations in TypeScript.

  babelTypes includes all types from @babel/types.

• #714 80e4c74 Thanks @danez! - Add the new ChainResolver which allows multiple resolvers to be chained.

  import { builtinResolvers } from 'react-docgen';
  
  const { ChainResolver } = builtinResolvers;
  const resolver = new ChainResolver([resolver1, resolver2], {
    chainingLogic: ChainResolver.Logic.ALL, // or ChainResolver.Logic.FIRST_FOUND,
  });
  

• 96d6e9e Thanks @danez! - Support all literal types in typescript

• 96d6e9e Thanks @danez! - Support flow qualified type names

• 96d6e9e Thanks @danez! - Support class and function declarations without identifier

• 96d6e9e Thanks @danez! - Support resolving of destructuring in resolveToValue

• #714 80e4c74 Thanks @danez! - Allow resolvers to be classes in addition to functions.

  import type { ResolverClass, ResolverFunction } from 'react-docgen';
  
  // This was the only option until now
  const functionResolver: ResolverFunction = (file: FileState) => {
    //needs to return array of found components
  };
  
  // This is the new class resolver
  class MyResolver implements ResolverClass {
    resolve(file: FileState) {
      //needs to return array of found components
    }
  }
  
  const classResolver = new MyResolver();
  

• 96d6e9e Thanks @danez! - Improve performance drastically by making changes to AST traversal

  Visitors are now pre-exploded and are cached in the module scope instead of creating them on every call. This change brought the benchmark from 170ops/s to 225ops/sec

• 96d6e9e Thanks @danez! - Add codes to errors to be able to easily detect them

  There is a new export ERROR_CODES that contains all possible error codes. The two errors that have codes right now are:

  • MISSING_DEFINITION: No component found in a file
  • MULTIPLE_DEFINITIONS: Multiple components found in one file

• 96d6e9e Thanks @danez! - Support handling useImperativeHandle correctly

• #743 5215bab Thanks @danez! - Added a new resolver that finds annotated components. This resolver is also enabled by default.

  To use this feature simply annotated a component with @component.

  // @component
  class MyComponent {}
  

Patch Changes

• #745 8fe3dbf Thanks @danez! - Fix crash when using TypeScript mapped types

• #789 7c99f15 Thanks @danez! - Fix TypeScript types when strict null checks are disabled

• 96d6e9e Thanks @danez! - Handle React.forwardRef calls without a function

• 96d6e9e Thanks @danez! - Fixed the handling of some edge cases in resolveToValue

• 96d6e9e Thanks @danez! - Remove trailing commas and semicolons from raw values in the documentation

• #767 a684d82 Thanks @danez! - Fix handling of PropTypes.oneOf to handle unresolved imported values correctly

• #761 cc94da2 Thanks @danez! - Fix using react-docgen in browsers

• #761 98a1138 Thanks @danez! - Add displayName and description to Documentation type

• 96d6e9e Thanks @danez! - Parse jsdoc comments for TypeScript structs

• #748 ea25b16 Thanks @danez! - Handle cyclic references in PropTypes shape() and exact() methods.

• #787 5a226ac Thanks @danez! - Fix @babel/traverse import to work in non ESM environments

• 96d6e9e Thanks @danez! - Correctly handle ObjectProperties in isReactComponentMethod

• #747 1aa0249 Thanks @danez! - Handle typeof import('...') and typeof MyType.property correctly in TypeScript

• 050313d Thanks @danez! - Correctly add LICENSE file to published packages

• 96d6e9e Thanks @danez! - Add support for TSAsExpressions when trying to stringify expressions

• #720 f6e4fe7 Thanks @renovate! - Update dependency strip-indent to v4

• #769 e08e08d Thanks @danez! - Correctly resolve the values in an Object.values() call

Patch Changes

• #789 7c99f15 Thanks @danez! - Fix TypeScript types when strict null checks are disabled

Patch Changes

• #787 5a226ac Thanks @danez! - Fix @babel/traverse import to work in non ESM environments

Major Changes

• #786 0a2481d Thanks @danez! - Renamed the method toObject to build in the DocumentationBuilder.

  This method might be used by integrations.

Minor Changes

• #786 0a2481d Thanks @danez! - Export the type for the DocumentationBuilder.

• #786 0a2481d Thanks @danez! - The types NodePath and babelTypes are now exported.

  These types are useful when building integrations in TypeScript.

  babelTypes includes all types from @babel/types.

Patch Changes

• #767 a684d82 Thanks @danez! - Fix handling of PropTypes.oneOf to handle unresolved imported values correctly

• #769 e08e08d Thanks @danez! - Correctly resolve the values in an Object.values() call

Major Changes

• dfc2f85: Rename propDocBlockHandler to propDocblockHandler for consistency

Patch Changes

• cc94da2: Fix using react-docgen in browsers
• 98a1138: Add displayName and description to Documentation type

Major Changes

• d7a39af: Refactored resolveComponentDefinition utility.

  • Renamed to findComponentDefinition
  • Removed named export isComponentDefinition
  • The utility now does a lot more than previously, check out the commit to see the changes in detail.

• e956802: Remove match utility.

  The utility can be replaced by babel helpers and is not needed anymore. Also using explicit checks like path.isMemberExpression() is better for type safety and catching potential bugs.

• 5215bab: Removed support for the @extends React.Component annotation on react class components.

  Instead you can use the new @component annotation.

• 80e4c74: Renamed and migrated built-in resolvers to classes.

  • findAllComponentDefinitions was renamed to FindAllDefinitionsResolver and is now a class.

    -const resolver = builtinResolvers.findAllComponentDefinitions
    +const resolver = new builtinResolvers.FindAllDefinitionsResolver()
    

  • findAllExportedComponentDefinitions was renamed to FindExportedDefinitionsResolver and is now a class.

    -const resolver = builtinResolvers.findAllExportedComponentDefinitions
    +const resolver = new builtinResolvers.FindExportedDefinitionsResolver()
    

  • findExportedComponentDefinition was removed. Use FindExportedDefinitionsResolver with the limit option instead.

    This is still the default resolver.

    -const resolver = builtinResolvers.findExportedComponentDefinition
    +const resolver = new builtinResolvers.FindExportedDefinitionsResolver({ limit: 1 })
    

Minor Changes

• 80e4c74: Add the new ChainResolver which allows multiple resolvers to be chained.

  import { builtinResolvers } from 'react-docgen';
  
  const { ChainResolver } = builtinResolvers;
  const resolver = new ChainResolver([resolver1, resolver2], {
    chainingLogic: ChainResolver.Logic.ALL, // or ChainResolver.Logic.FIRST_FOUND,
  });
  

• 80e4c74: Allow resolvers to be classes in addition to functions.

  import type { ResolverClass, ResolverFunction } from 'react-docgen';
  
  // This was the only option until now
  const functionResolver: ResolverFunction = (file: FileState) => {
    //needs to return array of found components
  };
  
  // This is the new class resolver
  class MyResolver implements ResolverClass {
    resolve(file: FileState) {
      //needs to return array of found components
    }
  }
  
  const classResolver = new MyResolver();
  

• 5215bab: Added a new resolver that finds annotated components. This resolver is also enabled by default.

  To use this feature simply annotated a component with @component.

  // @component
  class MyComponent {}
  

Patch Changes

• 8fe3dbf: Fix crash when using TypeScript mapped types
• ea25b16: Handle cyclic references in PropTypes shape() and exact() methods.
• 1aa0249: Handle typeof import('...') and typeof MyType.property correctly in TypeScript
• 050313d: Correctly add LICENSE file to published packages
• f6e4fe7: Update dependency strip-indent to v4

Major Changes

• 96d6e9e: Rename flowTypeHandler to codeTypeHandler because it handles Flow and TypeScript

• 96d6e9e: Simplify resolveObjectValuesToArray and remove type handling. None of the code that was handling types was actually used.

• caae6bf: The return values of resolveObjectValuesToArray are now in the order they are defined in the source code.

• 96d6e9e: Migrate react-docgen to ES modules. Please read this

• 3b28f6e: The CLI was removed from react-docgen into its own package @react-docgen/cli.

  Check out https://react-docgen.dev/docs/getting-started/cli/ for the documentation.

• 96d6e9e: Main parse API was changed

  The main API changed and now includes only 2 arguments.

  -parse(src, resolver, handlers, importer, options)
  +parse(src, { resolver, handlers, importer, ... })
  

• 96d6e9e: Renamed some of the main exports for clarity.

  Renamed handlers to builtinHandlers Renamed resolver to builtinResolvers Renamed importers to builtinImporters

• 96d6e9e: Migrated to babel toolchain

  This is one of the big changes in this new version of react-docgen. It made the code a lot more robust because there are now finally working TypeScript types for the ASTs.

  Another benefit from this change that react-docgen is now a lot faster. 🚀 In some tests an improvement of nearly 50% was seen in comparison to version 5.

• d4c27d4: Improve performance of file system importer.

  The file system importer now also caches resolving of files in addition to parsing files. If the importer is used in an environment where files do change at runtime (like a watch command) then the caches will need to be cleared on every file change.

• 96d6e9e: Changed the minimum Node.js version to 14.18.0

Minor Changes

• 96d6e9e: Add support for .cts and .mts extension when using typescript

• 96d6e9e: Treat functions returning React.Children.map as components

• 96d6e9e: Improve performance by creating all visitors only once

• 96d6e9e: Support all possible kinds of functions in the displayNameHandler

• 96d6e9e: Support all literal types in typescript

• 96d6e9e: Support flow qualified type names

• 96d6e9e: Support class and function declarations without identifier

• 96d6e9e: Support resolving of destructurings in resolveToValue

• 96d6e9e: Improve performance drastically by making changes to AST traversal

  Visitors are now pre-exploded and are cached in the module scope instead of creating them on every call. This change brought the benchmark from 170ops/s to 225ops/sec

• 96d6e9e: Add codes to errors to be able to easily detect them

  There is a new export ERROR_CODES that contains all possible error codes. The two errors that have codes right now are:

  • MISSING_DEFINITION: No component found in file
  • MULTIPLE_DEFINITIONS: Multiple components found in one files

• 96d6e9e: Support handling useImperativeHandle correctly

Patch Changes

• 96d6e9e: Handle React.forwardRef calls without a function
• 96d6e9e: Handle some edge cases in resolveToValue
• 96d6e9e: Remove trailing commas and semicolons from raw values in the documentation
• 96d6e9e: Parse jsdoc comments for TypeScript structs
• 96d6e9e: Correctly handle ObjectProperties in isReactComponentMethod
• 96d6e9e: Add support for TSAsExpressions when trying to stringify expressions

Bug Fixes

• Correctly detect index access types in typescript (#400) (85ea6a5)
• Correctly handle ObjectTypeSpreadProperty in object type annotations (#593) (395f338)
• Fix typescript types for parsing (34c55ac)
• Fix wrong detection of forwardRef in combination with memo (#592) (ea9cbeb)
• Handle ObjectTypeSpreadProperties which are not resolvable (4b8b721)
• Ignore methods in Object.value() calls (4fc5b21)

Bug Fixes

• Change folder name inside the npm package back to dist. (5f3da8c) There was no real reason to change this and happened during the TypeScript migration.

Bug Fixes

• Fix for expressionTo with Spread and Methods (5f3da8c)
• Remove obsolete id check (66961d8)
• Remove usage of ast-type builders (17c8a9c)

Features

• Migrate to TypeScript (7b35e6f)
• Remove building out of scope AST Nodes from resolveToValue (5bcf56c)

BREAKING CHANGES

• resolveToValue will not create a MemberExpression for targets ending in destructuring. It will now simply resolve to the Identifier inside the destructuring. Use new helper isDestructuringAssignment to further check this identifier.
• The helpers resolveObjectValuesToArray and resolveObjectKeysToArray return now string[] instead of a NodePath