[infra] Extract utilities to a separate package #2167

michaldudak · 2025-06-25T15:56:09Z

Extracted utilities that can be used in other MUI projects to a separate library - @base-ui-components/utils.

Before we start using it across the company, I want to update JSDocs and possibly rename and reorganize few utilities.

mui-bot · 2025-06-25T15:58:14Z

Bundle size report

Bundle	Parsed Size	Gzip Size
@base-ui-components/react	▼-295B^(-0.10%)	▼-124B^(-0.13%)

Details of bundle changes

Generated by 🚫 dangerJS against c4c063a

Janpot · 2025-06-25T16:03:55Z

can be used in other MUI projects to a separate library

That means they will be semver stable? Should we document them?

cc @romgrk to get your attention on this PR, I believe you brought up the topic of shared libraries recently.

romgrk · 2025-06-25T18:51:26Z

packages/react-utils/README.md

@@ -0,0 +1,3 @@
+# @base-ui-components/react-utils


I think I'd go with just @base-ui-components/utils for the name. The package contains more than just react-specific utils, and the name is already long due to the prefix.

Yeah, I'm fine with it too. I'm wondering if it shouldn't be internal-utils, though, to match the convention we use in other such libraries (@Janpot, any opinions?).

According to the current conventions, that would make it semver unstable and then it can only be depended in this repo, and only if the dependency is defined with exact version.
I think @base-ui-components/utils makes sense, just don't make breaking changes in it on a minor.

romgrk · 2025-06-25T18:54:23Z

packages/react-utils/package.json

That means they will be semver stable? Should we document them?

Yes it should follow semver, and no I don't think we should document them beyond jsdoc.

pkg-pr-new · 2025-06-26T09:32:15Z

vite-css-base-ui-example

npm i https://pkg.pr.new/@base-ui-components/react@2167

npm i https://pkg.pr.new/@base-ui-components/utils@2167

commit: c4c063a

netlify · 2025-06-26T09:32:46Z

✅ Deploy Preview for base-ui ready!

Name	Link
🔨 Latest commit	`c4c063a`
🔍 Latest deploy log	https://app.netlify.com/projects/base-ui/deploys/6870c96a87c30f00088628cc
😎 Deploy Preview	https://deploy-preview-2167--base-ui.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

brijeshb42 · 2025-07-08T11:26:43Z

docs/src/app/(private)/experiments/dialog.tsx

-  useSpringRef,
-} from '@react-spring/web';
+// eslint-disable-next-line no-restricted-imports
+import { useTransitionStatus } from '@base-ui-components/react/utils/useTransitionStatus';


Shouldn't this be -

Suggested change

import { useTransitionStatus } from '@base-ui-components/react/utils/useTransitionStatus';

import { useTransitionStatus } from '@base-ui-components/utils/useTransitionStatus';

No, useTransitionStatus is Base UI-specific and lives in the main package.

brijeshb42 · 2025-07-08T11:27:34Z

docs/src/components/MobileNav.tsx

 import * as ReactDOM from 'react-dom';
-import { useScrollLock } from '@base-ui-components/react/utils';
+// eslint-disable-next-line no-restricted-imports
+import { useScrollLock } from '@base-ui-components/react/utils/useScrollLock';


LukasTy

Great work!
Thank you for exporting these. 🙏
Leaving some minor nitpicks.

I've tested it on mui/mui-x#18734 and have a question.
Have you considered exporting useButton hook? 🤔

LukasTy · 2025-07-07T15:32:12Z

docs/src/app/(private)/experiments/dialog.tsx

-  useSpring,
-  useSpringRef,
-} from '@react-spring/web';
+// eslint-disable-next-line no-restricted-imports


If this package does not have problems importing files from more than 2 levels deep, then maybe the ESLint rules should be adjusted? 🤔

It doesn't really import these from the package. Docs use Base UI sources directly, so they can access private exports.

Docs use Base UI sources directly

Is this avoidable? this tends to mess up caching algorithms that rely only on npm dependencies. and all kinds of other subtle problems, e.g. typescript filles outside of the root folder and stuff like that

It does create subtle problems, but it also makes the devmode DX much nicer. HMR works seamlessly if you use source files rather than built files, and you can import anything you want. The setup is harder to maintain, but the tradeoff is worth it, imho.

HMR works seamlessly if you use source files rather than built files

I think for this case, we should be using a watch script for typescript builds of the lib. HMR should work fine on the built files after they are updated by the typescript watcher.

I think another good purpose of the docs is testing that our packaging is working properly. I could see an issue if there were subtle differences in the typescript config between the docs and the lib.

Also, why do the docs need to access private exports?

if necessary we can alias to sources for dev mode, I don't mind so much, as long as the aliasing can be removed and no code changes are necessary for regular pnpm workspaces resolution to work correctly.

each package building in watch mode has my preference, but we need to make sure it can scale to the size of core and X monorepos. We'll likely start work on a vite configuration for building our libraries soon.

I could see an issue if there were subtle differences in the typescript config between the docs and the lib.

I have witnessed such issues in the past, but I argued unsuccessfully for running our test suites (rather than the docs) in prod mode to deal with that.

Also, why do the docs need to access private exports?

Private experiments that we don't want to publish, such as this case and anything else under .../(private)/experiments/.

I think for this case, we should be using a watch script for typescript builds of the lib. HMR should work fine on the built files after they are updated by the typescript watcher.

If it can be shown to not affect the DX, I'm fine with it.

Is this avoidable? this tends to mess up caching algorithms that rely only on npm dependencies. and all kinds of other subtle problems, e.g. typescript filles outside of the root folder and stuff like that

We can discuss it on the infra meeting. It's not in scope of this PR anyway.

docs/src/blocks/GoogleAnalytics.tsx

packages/react/src/floating-ui-react/components/FloatingPortal.test.tsx

packages/utils/README.md

Co-authored-by: Lukas Tyla <llukas.tyla@gmail.com> Signed-off-by: Michał Dudak <michal.dudak@gmail.com>

michaldudak · 2025-07-09T09:31:33Z

Have you considered exporting useButton hook? 🤔

We might actually have a Button component at some point, but it's not fully decided yet.
If you need to add button functions to a non-interactive component, I suppose useButton could be useful. However, before we export it, I'd like to clean it up properly and remove handling of HTML anchors (we could have useLink if there's a need, but I don't see it now).

michaldudak added 5 commits June 25, 2025 16:22

Package stub

116bb03

Move utils to the new project

86da4b5

Update imports

fab9170

Move store to the utils package

d402d39

necessary files

323abcf

michaldudak added the scope: code-infra Involves the code-infra product (https://www.notion.so/mui-org/5562c14178aa42af97bc1fa5114000cd). label Jun 25, 2025

michaldudak requested a review from a team June 25, 2025 15:56

romgrk reviewed Jun 25, 2025

View reviewed changes

github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged. label Jun 26, 2025

michaldudak added 5 commits June 26, 2025 09:52

Generate package.json

3e43ab2

Clean dependencies

732e5f9

Set up vitest

f5a245b

Merge remote-tracking branch 'upstream/master' into utils-library

4ed6510

Fix package verification tests

b139973

github-actions bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged. label Jun 26, 2025

michaldudak added 5 commits June 26, 2025 11:33

Set up vite alias

c2cc947

Set up aliases in other tests

6377deb

Configure pkg.pr.new and csbci

8afbec7

react-utils -> utils

95bb9b4

Use the local changelog in the package

9fe6066

michaldudak mentioned this pull request Jun 26, 2025

[infra] Support project-specific changelog in build scripts mui/material-ui#46425

Merged

michaldudak added 4 commits June 26, 2025 13:18

Add the missing eslint plugin

463ad64

dedupe

ce8b15b

Add missing dependency

60d5afd

Fix the lockfile

b4475d3

github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged. label Jun 30, 2025

Merge branch 'master' into utils-library

b4770d2

github-actions bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged. label Jul 2, 2025

Prettier

69435b9

github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged. label Jul 2, 2025

Merge remote-tracking branch 'upstream/master' into utils-library

58cfa6e

github-actions bot added PR: out-of-date The pull request has merge conflicts and can't be merged. and removed PR: out-of-date The pull request has merge conflicts and can't be merged. labels Jul 7, 2025

Merge remote-tracking branch 'upstream/master' into utils-library

03b5e91

github-actions bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged. label Jul 8, 2025

michaldudak added 5 commits July 8, 2025 12:40

Use subpath imports

9b55235

Remove version from the root package.json

5dce78b

Include the new package in bundle size checker

603dfab

Fix bundle size checker config

df7b227

Remove the index file

a38bd90

brijeshb42 reviewed Jul 8, 2025

View reviewed changes

github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged. label Jul 8, 2025

LukasTy mentioned this pull request Jul 8, 2025

[scheduler] Use @base-ui-components/utils package mui/mui-x#18734

Merged

LukasTy reviewed Jul 8, 2025

View reviewed changes

Update packages/utils/README.md

46b2cbc

Co-authored-by: Lukas Tyla <llukas.tyla@gmail.com> Signed-off-by: Michał Dudak <michal.dudak@gmail.com>

romgrk approved these changes Jul 9, 2025

View reviewed changes

Merge remote-tracking branch 'upstream/master' into utils-library

eedc85d

github-actions bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged. label Jul 11, 2025

Restart CI

c4c063a

michaldudak merged commit cbfd881 into mui:master Jul 11, 2025
21 checks passed

michaldudak deleted the utils-library branch July 11, 2025 08:27

Janpot mentioned this pull request Jul 16, 2025

[docs-infra] Create llms.txt #1738

Merged

michaldudak added the package: utils Specific to the utils package. label Jul 30, 2025

	import { useTransitionStatus } from '@base-ui-components/react/utils/useTransitionStatus';
	import { useTransitionStatus } from '@base-ui-components/utils/useTransitionStatus';

Uh oh!

[infra] Extract utilities to a separate package #2167

[infra] Extract utilities to a separate package #2167

Uh oh!

Conversation

michaldudak commented Jun 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mui-bot commented Jun 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle size report

Uh oh!

Janpot commented Jun 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pkg-pr-new bot commented Jun 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Jun 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for base-ui ready!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LukasTy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dav-is Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Janpot Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

romgrk Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

michaldudak commented Jul 9, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

michaldudak commented Jun 25, 2025 •

edited

Loading

mui-bot commented Jun 25, 2025 •

edited

Loading

Janpot commented Jun 25, 2025 •

edited

Loading

pkg-pr-new bot commented Jun 26, 2025 •

edited

Loading

netlify bot commented Jun 26, 2025 •

edited

Loading

dav-is Jul 9, 2025 •

edited

Loading

Janpot Jul 9, 2025 •

edited

Loading

romgrk Jul 9, 2025 •

edited

Loading