refactor(docx): Optimize Prop Generation Script #2786

ZakaryH · 2025-10-17T21:54:01Z

Motivations

our prop generation script takes about 60 seconds to run on my machine. it's just parsing a lot of props, and I can't help but feel like that's a long time for that sort of operation. even if it's thousands of props. they're just JSON objects really.

another small thing is that things are not in any clear order. our output is not alphabetical, and it just makes it ever so slightly harder to read. almost every other library puts props in alphabetic order.

looking at the code for the script, I noticed a lot of nested iteration. reduces inside reduces, and multiple instances of objects/documents. I wanted to take a stab at this to see if we could optimize it at all.

Changes

Added

Changed

over the last 30 days this step is around 6m, but if we look at successful runs it's closer to 4m

on this branch, 1.5m

with 1m of that in the generate + build step

vs

4m for the same step(s)

props are sorted alphabetically
sub components of a component are sorted alphabetically
runtime for prop generation is roughly 1/4th of previous runtime on CI
runtime for prop generation is roughly 1/12th of previous runtime on local machine
props for some components like Mobile Typography that had literally nothing now have props (might be the only instance)

Deprecated

Removed

Fixed

Security

Testing

running npm run generate locally should take seconds, not minutes.

the output won't be identical, it is now more deterministic with alphabetical order, and slightly different paths - though these don't really matter as long as.....

the props tables on the site all work and display our props. filtering out React/HTML props we don't want to show.

Typography now has actual props. not sure why this was getting skipped before.

it would be good to read over the props and make sure all the changes are simply order, or small things like React.ReactNode -> ReactNode. I'll see if I can come up with a nicer, easier way to compare them. because while I'm 99% sure they are the same, it's very tough to tell due to the git diff reordering things, and there being so much to look over.

Changes can be
tested via Pre-release

In Atlantis we use Github's built in pull request reviews.

…Component>V2

…clude inherited React props - Introduced a new function, `filterOutInheritedReactProps`, to clean up component documentation by removing inherited props from React base attributes. - Updated the documentation processing pipeline in `generateDocs.mjs` to include this new filtering step. - Removed unnecessary `key` prop entries from various component prop JSON files to streamline documentation.

- Updated the output path for V2 props to ensure they are written in the same directory as V1 props, improving organization and accessibility of generated documentation files. - Adjusted the path construction in `generateDocs.mjs` to reflect this change.

- Simplified the `filterOutInheritedReactProps` function by removing redundant checks and improving clarity. - Moved constants outside of util functions

…ocgen-script-for-V2-components

ZakaryH · 2025-10-17T21:57:04Z

packages/site/src/content/Typography/Typography.props-mobile.json

oh wow. this file is actually just empty on prod right now.

but now it has content!

cloudflare-workers-and-pages · 2025-10-17T21:57:42Z

Deploying atlantis with Cloudflare Pages

Latest commit:	`e13bce0`
Status:	✅ Deploy successful!
Preview URL:	https://e58e7a2c.atlantis.pages.dev
Branch Preview URL:	https://rework-prop-generation-scrip.atlantis.pages.dev

View logs

ZakaryH · 2025-10-17T22:48:45Z

.circleci/config.yml

+          name: Lint JavaScript with increased Node heap
+          command: npm run lint:js -- --quiet --format junit -o reports/junit/js-lint-results.xml
+          environment:
+            NODE_OPTIONS: "--max-old-space-size=4096"


still not 100% sure why it's only starting to fail now. while yes, there are a lot of files changed in this PR I thought this step went over everything, not just files changed meaning we'd have the same amount of files as we did before and it didn't fail...

kept hitting an out of memory error on the lint_javascript job

there are a handful of things to dig into

typescript mismatch

ts-eslint running on non TS files like JS/MJS

the KeyboardAwareHOC.js from a node module seemingly being parsed

In components-native, you import react-native-keyboard-aware-scroll-view, which resolves to .../node_modules/.../KeyboardAwareHOC.js. The plugin tries to parse that file to validate import usage; with the TS parser + version mismatch, it throws and sometimes eats RAM.

so this isn't a long term fix, but it gets us past the issue and allows the rest of the benefits of these changes to come through.

while yes, there are a lot of files changed in this PR I thought this step went over everything

Exactly, this does go over everything. It may have been a fluke with CI around the time you last ran this.

I'd pull in master and see if this is still necessary. FWIW I do think it's pretty common to bump node's memory limit for heavyweight jobs like linting, so I'm not against this change at all.

jdeichert

Great work!! This is lightning fast locally 👌

Something we should discuss here or soon: do we even need to commit these anymore? The only reason IIRC we committed them is because generation was so slow. Without that bottleneck, we could simply make this step part of the normal npm run dev for the docs site.

The only benefit of keeping these committed is that they act as a snapshot test... we can easily see when a PR negatively affects/breaks prop regen types. If we did start git ignoring these, we wouldn't catch little things like that and would probably want to add a bunch of tests in place.. which I don't think would catch many of the issues we see occasionally.

it would be good to read over the props and make sure all the changes are simply order, or small things like React.ReactNode -> ReactNode. I'll see if I can come up with a nicer, easier way to compare them. because while I'm 99% sure they are the same, it's very tough to tell due to the git diff reordering things, and there being so much to look over.

Is the alphabetical ordering change easy to make a separate PR for that hits master first? If we had that PR, it would likely contain the largest diff and would be easy to review, knowing only order changed. Then this PR could be updated with that... and there would probably be similar # of file changes, but the diff would be very minimal in comparison.

Leaving my approval for after this gets updated with master 👍

The alphabetical PR is optional, just would improve confidence in the diff.

jdeichert · 2025-12-01T15:26:34Z

.circleci/config.yml

+          name: Lint JavaScript with increased Node heap
+          command: npm run lint:js -- --quiet --format junit -o reports/junit/js-lint-results.xml
+          environment:
+            NODE_OPTIONS: "--max-old-space-size=4096"


while yes, there are a lot of files changed in this PR I thought this step went over everything

Exactly, this does go over everything. It may have been a fluke with CI around the time you last ran this.

I'd pull in master and see if this is still necessary. FWIW I do think it's pretty common to bump node's memory limit for heavyweight jobs like linting, so I'm not against this change at all.

jdeichert · 2025-12-01T15:44:21Z

packages/site/generateDocs.mjs

 } from "./baseComponentLists.mjs";

+// Load tsconfig once and build compiler options
+const tsconfigPath = resolve(process.cwd(), "../../tsconfig.json");


This is the root tsconfig.json, however components and components-native both have their own respective tsconfig.json files which take precedence. I'm not even sure if the root one is used for anything.. I guess it's a fallback for packages that don't have their own tsconfig.json.

While this works because it shares ~90% of the config, I'm curious if using the components/components-native files leads to differences in generation.

nad182 and others added 12 commits October 8, 2025 14:34

feat(site): generate V2 docs when *.rebuilt.tsx exists and write to <…

2798127

…Component>V2

Generate V2 props in the same dir as V1

9edd355

Use the new setup for combined Autocomplete (V1 and V2)

71547f1

reverte Autocomplete index changes (will be done separately)

e4db841

remove remnants of Autocomplete v2 in v1 folder

ac3f001

remove remnants of Autocomplete v2 in v1 folder

faad17e

refactor(docs): address PR comments

1e483d2

- Simplified the `filterOutInheritedReactProps` function by removing redundant checks and improving clarity. - Moved constants outside of util functions

Merge remote-tracking branch 'origin/master' into JOB-138157/update-d…

b7a68c4

…ocgen-script-for-V2-components

optimize generation script

96d6cd7

run script for new deterministic results

0055e95

ZakaryH changed the base branch from master to JOB-138157/update-docgen-script-for-V2-components October 17, 2025 21:54

ZakaryH commented Oct 17, 2025

View reviewed changes

ZakaryH added 3 commits October 17, 2025 15:04

keep propFilter as single source of truth

bac3ff5

ignore generated props for linting

382cb4f

increase Node heap for lint job

e13bce0

ZakaryH commented Oct 17, 2025

View reviewed changes

Base automatically changed from JOB-138157/update-docgen-script-for-V2-components to master October 20, 2025 15:01

jdeichert reviewed Dec 1, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

refactor(docx): Optimize Prop Generation Script #2786

refactor(docx): Optimize Prop Generation Script #2786

Uh oh!

ZakaryH commented Oct 17, 2025 •

edited

Loading

Uh oh!

ZakaryH Oct 17, 2025

Uh oh!

cloudflare-workers-and-pages bot commented Oct 17, 2025 •

edited

Loading

Uh oh!

ZakaryH Oct 17, 2025

Uh oh!

jdeichert Dec 1, 2025

Uh oh!

jdeichert left a comment

Uh oh!

jdeichert Dec 1, 2025

Uh oh!

jdeichert Dec 1, 2025

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

4 participants

refactor(docx): Optimize Prop Generation Script #2786

Are you sure you want to change the base?

refactor(docx): Optimize Prop Generation Script #2786

Uh oh!

Conversation

ZakaryH commented Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivations

Changes

Added

Changed

Deprecated

Removed

Fixed

Security

Testing

Uh oh!

ZakaryH Oct 17, 2025

Choose a reason for hiding this comment

Uh oh!

cloudflare-workers-and-pages bot commented Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying atlantis with Cloudflare Pages

Uh oh!

ZakaryH Oct 17, 2025

Choose a reason for hiding this comment

Uh oh!

jdeichert Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

jdeichert left a comment

Choose a reason for hiding this comment

Uh oh!

jdeichert Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

jdeichert Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

4 participants

ZakaryH commented Oct 17, 2025 •

edited

Loading

cloudflare-workers-and-pages bot commented Oct 17, 2025 •

edited

Loading