Skip to content

Autogenerate UI adapter props with ts-morph #315

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 23, 2025

Conversation

serikjensen
Copy link
Member

@serikjensen serikjensen commented May 21, 2025

This PR uses ts-morph AST to autogenerate prop documentation for the component adapters.

For more context on alternative approaches explored see the slack thread here.

The summary at a high level behind the decision to go this way:

  • Using react docgen TS is not viable because it depends on interfaces being in the same files as components (which ours are not)
  • Using typedoc with the markdown plugin is highly prescriptive about the output outputting to multiple files which we have little control over, it also fails to document our picked HTML props which is a pattern that is important to us to keep our component APIs aligned with the HTML spec
  • Using typedoc directly you are still unable to document picked props and it is almost as much overhead as just using the AST

This approach uses ts-morph which allows us to get all props (including picked html props) and format them to a single file according to our needs. This is also an approach that requires the most custom config. In the event that this script proves brittle or challenging to maintain, we may ultimately need to revisit and just deal with the limitations of typedoc + markdown plugin. But team consensus was that we could give this a try and adjust as needed down the road.

Proof of functionality

View output markdown file on the branch here https://github.com/Gusto/embedded-react-sdk/blob/chore/GWS-5000-ts-morph/docs/06/01/component-inventory.md

@serikjensen serikjensen force-pushed the chore/GWS-5000-ts-morph branch 10 times, most recently from 669d996 to 53839ae Compare May 22, 2025 17:29
@serikjensen serikjensen force-pushed the chore/GWS-5000-ts-morph branch 2 times, most recently from 16926f3 to df669bd Compare May 22, 2025 22:06
@serikjensen serikjensen marked this pull request as ready for review May 22, 2025 22:15
@serikjensen serikjensen force-pushed the chore/GWS-5000-ts-morph branch from df669bd to 2479e39 Compare May 22, 2025 22:16
@serikjensen serikjensen changed the title [WIP] Autogenerate UI adapter props with ts-morph Autogenerate UI adapter props with ts-morph May 22, 2025
@serikjensen serikjensen force-pushed the chore/GWS-5000-ts-morph branch from 2479e39 to 1108348 Compare May 22, 2025 22:35
@jeffredodd jeffredodd merged commit 1daf88f into main May 23, 2025
3 checks passed
@jeffredodd jeffredodd deleted the chore/GWS-5000-ts-morph branch May 23, 2025 18:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants