前端性能工程实践
The starting point: a performance tuning pass
During my first month at LobeHub, I ran a performance optimization pass, documented with benchmarks in
"Performance and DX Optimizations at LobeHub"
. The heaviest bottlenecks in that pass were all style-related: CSS-in-JS Flexbox components like react-layout-kit numbered in the hundreds on a single page, each generating CSS; the
useStyle
running across almost every component recalculated styles on every re-render; and a single antd Tooltip took 0.5ms on its own. The first two could be fixed by switching styling solutions, but Tooltip required a full rewrite. I rebuilt both it and Popover with Base UI—the first time Base UI was used in lobe-ui.
With those fixes in place, the remaining overhead came from antd components themselves. Since antd's UI was also notoriously hard to customize deeply, replacing it was the obvious next move. I had wanted to do this for a while, but never started because manually rewriting a codebase of this size was unrealistic, and AI wasn't capable enough yet.
When we actually started, this was what we were facing:
@lobehub/ui
had almost a hundred component modules, with behavior tightly coupled to antd and all component styles written in Emotion-based
antd-style
, which generated CSS at runtime and injected it into the document on every page load. Downstream, five ecosystem libraries—icons, editor, charts, tts, and fluent-emoji—declared it as a peer dependency, and at the top layer, hundreds of business files in lobe-chat directly imported from
import ... from 'antd'
. Meanwhile, product features shipped weekly, so maintaining a long-running rewrite branch wasn't an option. The entire migration had to happen without interrupting delivery, split into two parallel tracks: first swap out the underlying component foundation from antd to Base UI, then switch styling from runtime Emotion to compile-time StyleX.
Letting old and new components coexist in the same package
lobe-ui#448
rewrote Tooltip. Beyond performance gains, it also resolved seven Linear issues: positioning drift, tooltips failing to dismiss, and elements snapping back to (0, 0) when their host unmounted. Base UI is headless, providing only behavior and accessibility while leaving DOM structure and styling to us, so we could customize everything freely without fighting antd's limitations.
The next question was how to make the transition. With weekly product releases and several downstream libraries tracking our changes, ripping out antd all at once wasn't practical. Instead, I opted for coexistence: build new components with Base UI, package them alongside the antd versions, and migrate product call sites one component at a time. Throughout January 2026, we gradually added
lobe-ui#444
's Base UI Menu–based DropdownMenu and ContextMenu, alongside LobeSwitch and LobeSelect. To avoid name clashes with their antd counterparts, they initially carried a Lobe prefix or a V2 suffix.
On March 2,
lobe-ui#467
released v5, formalizing this coexistence in the package structure: adding a
@lobehub/ui/base-ui
subpath where LobeSelect and LobeSwitch were moved (dropping their prefixes), while DropdownMenu, Toast, ContextMenu, and ScrollArea were exported from there as well. The package itself also became ESM-only. Subsequent components followed the exact same pattern: the implementation lived under
src/base-ui/
, while the root entry only re-exported it. For instance, when
lobe-ui#486
migrated Popover,
@lobehub/ui
and
@lobehub/ui/base-ui
were both valid, requiring zero changes in product code. From here on, migrating a component took just two steps: write the new implementation under base-ui, then switch the call sites in product code.
Components had to be drop-in replacements, locked down with linting once migrated
Between March and September, components were ported into base-ui roughly in this order: overlays, basic controls, forms, display, and layout.
Overlays first
This came down to two reasons. To begin with, overlays naturally belong together: Dropdown, Popover, Tooltip, Modal, and Drawer all share floating positioning and stacking management, making them ideal to tackle together. Later,
lobe-ui#518
unified their z-index management under a single layer manager. The second reason was how Modal was structured. Antd's Modal is primarily declarative, requiring components to be mounted on the React tree in advance:
open
is
false
, its children still render, re-rendering whenever ancestor state updates. With multiple Modals on a page, that overhead adds up on every single render. An imperative Modal creates an instance only when invoked and destroys it when closed, shifting the cost to the user action that opens it. I previously wrote about this in
"Why I Recommend Imperative Modals,"
and base-ui's Modal has supported both imperative and declarative patterns since its
first release
.
In the top example, every closed Modal participates in every render; in the bottom example, only the active Modal exists in the tree.
Migration windows by component category
After overlays came basic controls, forms, and display components. They all followed the exact same workflow: merge the new component into base-ui, switch product call sites over, and finally ban the legacy import via ESLint. Each bar below runs from when the new component merged to when the legacy import was banned:
A stark dividing line is visible around August. Before August, taking a component category from initial merge to banning legacy imports took weeks or months: Modal and Select took nearly four months, and form controls took 36 days. After August, Drawer took 5 days, Alert 6 days, Skeleton 3 days, DraggablePanel and Tree 2 days each, while ActionIcon, Avatar, Tag, and Text took just 1 day combined. The migration process hadn't changed—what changed was the models. Anthropic released Claude Fable 5 on June 9 and Claude Opus 5 on July 24. To me, Opus 5 felt exceptionally strong at front-end tasks, and at half the price of Fable 5, it cost about the same as Opus 4.8. By August, commits in lobe-chat switched from Opus 4.8 to Opus 5, and Fable 5 usage was rising too. The bars for Tabs and Segmented are also very short, but only because the initial preset banned five components all at once on June 26—not because they migrated faster.
Components like DropdownMenu, Tooltip, and Popover were replaced in place at the root entry point without legacy versions to ban, so they aren't shown in the chart. Commits for each component:
Modal
,
Menu
,
Tooltip
,
Button
,
Form controls
,
Drawer
,
Alert
,
ActionIcon and three others
,
Skeleton
,
DraggablePanel
, and
Tree
.
Each new component had to be a drop-in replacement, matching the old version in both API and visuals so switching only meant changing import paths. In lobe-ui#621, Tag's color resolution was ported straight from the old implementation: 13 preset colors, 5 system colors, and and all four variants (solid, filled, outlined, borderless) across three sizes had to match. Avatar replaced antd Avatar with native
img
, keeping the fallback on load failure and the +N counter for AvatarGroup. After Drawer merged, a separate
commit
followed to align its surface, edges, and drop shadows with antd Drawer.
The ban rules lived in lobe-ui's built-in ESLint preset, inherited directly by product projects. The
initial preset
on June 26 deprecated and banned imports of five antd-based wrappers: Button, Modal, Segmented, Select, and Tabs. When that first version went live, product code still had numerous legacy calls, which were temporarily grandfathered via an allowlist (detailed in the next section). From that point on, rules for each component category were added to the preset only after downstream projects had cleared all legacy imports. The PR description in
lobe-ui#610
was blunt: downstream migrations had removed legacy imports for these components, and this PR turned the migration boundary into an enforceable lint rule. That way, new code couldn't introduce old patterns, and legacy usage could only ever go down.
On the product side: freeze new usage, then clear legacy code category by category
Each time lobe-ui finished migrating a component category, lobe-chat had to update corresponding call sites. The chart below shows the number of files directly importing antd in lobe-chat, sampled biweekly:
Until mid-June, this line kept rising—climbing from 338 in mid-February to 485 on June 15. While legacy calls were being replaced, new features continued using antd. By then, the team had already delegated most product coding to AI, and component precedence had long been codified into
AGENTS.md
and react skills:
@lobehub/ui/base-ui
Any component available in it had to be imported from it, with same-named components at the root entry point off-limits, leaving antd strictly as a fallback when neither had it. Agents routinely ignored this. Because training data and hundreds of existing files demonstrated antd patterns, PRs for new features kept using legacy components even after lobe-ui published replacements. To an agent, docs are merely suggestions. The only way to stop them was to make violations break the build: ESLint fails directly, and lint-staged runs the same checks in pre-commit hooks to block the commit.
That was precisely what
lobehub#16334
did on June 26: it adopted lobe-ui's ESLint preset, banning the five legacy wrappers (Button, Modal, Segmented, Select, Tabs) as well as antd-style's
createStyles
; existing call sites (354 in total) were added to
eslint-suppressions.json
for temporary exemption, while any new violations failed immediately. Afterward, whenever a batch was migrated, we ran
eslint --prune-suppressions
, ensuring the allowlist only ever shrank.
Legacy code was cleared category by category: each PR targeted only one component category, but covered the entire repository. The count dropped slowly over the summer, followed by a steep drop in early October.
lobehub#20247
touched 285 files in one go, swapping out all remaining instances of Table, DatePicker, Menu, List, Input variants, and more, eliminating 163 files with direct antd imports. The PR included before-and-after screenshots compared against canary for verification, and five component library issues caught along the way were patched in
lobe-ui#675
. Next,
lobehub#20317
migrated forms, removing another 63 files;
lobehub#20408
updated menu item types to lobe-ui's, shedding 21 files; finally,
lobehub#20503
cleaned up the remainder. The two files still remaining on November 1 in the chart are test fixtures for alint.
Behavioral discrepancies are harder to catch than visual differences
Visual differences are easy to spot by comparing screenshots side by side, but behavioral discrepancies usually don't surface until a user saves data. After lobehub#20317 migrated forms to base-ui, the values returned on submit differed between the two:
antd Form
base-ui Form
Returned on submit
Values of currently mounted
Form.Item
fields only
Entire form store
Conditionally hidden fields
Discarded
Submitted together
initialValues
extra keys
Discarded
Submitted together
Fields that used to be quietly dropped were now persisted together. Switching a plugin's authentication from bearer to none left the old token behind. Similarly, switching transport from HTTP to stdio kept the old URL, causing later re-installations to fetch manifests from that stale address and overwrite existing settings.
lobehub#20644
added a
pruneHiddenFields
step before saving to prune fields that don't belong to the active type.
The compatibility layer itself can introduce bugs. The
ImperativeModal
wrapper, created for a smooth migration, unmounted its content in the very same commit that
open
became
false
, while base-ui's panel still had a 120ms exit animation—so closing the Skill Store details modal caused the content to collapse prematurely. Instead of patching the wrapper,
lobehub#17941
replaced all 11 call sites with imperative
createModal
Content lives inside a ModalHost and is only unmounted after the exit animation finishes.
Bumping the ecosystem libraries along with lobe-ui's majors
As we wrapped up the app-level cleanup, the intermediate ecosystem tier had to come along. Beyond lobe-ui, lobe-chat depends on icons, editor, charts, tts, and fluent-emoji—most of which declare lobe-ui as a peer dependency:
Whenever lobe-ui bumped a major version, the ecosystem layer broke: downstream packages lost exports they still needed, or peer versions fell out of sync. As a result, we always released them all together:
lobe-ui
Release date
icons
editor
charts
fluent-emoji
v3 (upgraded to antd v6)
2025-12-20
v3
v2
v3
v4 (static styles)
2025-12-24
v4
v3
v4
v5 (base-ui subpackage)
2026-03-02
v5
v4
v5
unchanged
v6 (dropped antd)
2026-10-15
v6
v5
v6
v5
v6 was by far the biggest set of changes, split into a stacked sequence of PRs:
lobe-ui#699
removed the antd components and
ThemeProvider
;
lobe-ui#700
dropped the antd, antd-style, and rc-* dependencies; and
lobe-ui#702
merged
src/base-ui
completely empty.
@lobehub/ui/base-ui
back into the root directory, getting rid of the base-ui subpath. With the coexistence phase over, we tore down that v5 scaffolding and exported the new components straight from the root entry. In early October, the downstream libraries first ported their own component usage over to base-ui (
lobe-editor#222
and
lobe-charts#32
), before each bumped to lobe-ui 6 and stripped out antd.
This cascade of changes couldn't be released and verified piecemeal. Instead, we tested across repos using pkg.pr.new preview packages: PRs for lobe-ui and the five downstream libraries each published preview packages, and
lobehub#20503
pointed all dependencies to those preview URLs. We compared lobe-chat against production page by page to ensure zero visual regressions before officially publishing in dependency order and and then switched back to real version numbers. PR #20503 alone updated imports across 2,728 files, purged antd from 24 workspace packages, and finally left
pnpm ls -r antd
with nothing to show.
Moving styles from runtime generation to build-time compilation
Dropping antd took care of components, but styles were still being generated at runtime. lobe-ui wrote its component styles in antd-style, built on Emotion: on page load, JavaScript generated CSS on the fly and inserted it into the page. The initial optimization pass replaced dynamic hooks with
createStaticStyles
, ensuring components no longer recomputed styles on every re-render. Yet the insertion step remained. In September,
lobehub#19066
pre-computed purely static calls at build time, slashing the time spent on styles during cold home page loads from ~56ms to ~28ms. The remaining ~14ms came from
insertRule
itself—an unavoidable cost as long as emotion was in the loop.
To eliminate this remaining overhead, styles needed to compile down to plain CSS files at build time. I chose StyleX, which splits styles into deduplicated atomic classes during compilation. The underlying mechanics—and how I migrated 10,000 lines of CSS to StyleX on another project—are covered in
"From Pure CSS to StyleX: Migrating 10,000 Lines of CSS with AI"
. For lobe-ui 6,
lobe-ui#701
piloted the approach on six components: Button, Divider, Spin, Switch, Tag, and Tooltip. Then
lobe-ui#705
migrated the remaining 89 modules in one go, freeing all 95 component modules from their emotion dependency. Markup not directly rendered by lobe-ui—such as Markdown, KaTeX, and code syntax highlighting—was styled with plain CSS in
@layer lobe-ui
.
Migrating 89 modules in a single pass succeeded thanks to per-element visual regression testing: we captured 500 demos in the documentation site across both light and dark themes while comparing computed styles for every element. Out of 1,000 runs, 891 matched completely. The remaining runs differed only because of animation timing, image loading, Mermaid layout jitter, or subpixel antialiasing differences. We also installed the packaged bundle into lobe-chat and ran the same comparison across 45 routes and 5 open menus.
Here are median cold-start metrics for the authenticated home page in lobe-chat, with CPU throttled 4x and each build tested across 8 runs. Both builds had already shed antd; the only difference was whether styles were generated at runtime via emotion or compiled ahead of time via StyleX:
Runtime overhead dropped across the board: document CSS rules fell from 5,817 to 4,429, blocking time decreased by 9%, and style recalculations dropped by 8%. The downside was First Contentful Paint: 4G FCP climbed from 440ms to 594ms because lobe-ui's
style.css
bundled styles for all 95 components, weighing in at 179KB uncompressed. In lobe-chat, it ended up in the single render-blocking stylesheet, pushing initial blocking CSS from 20.2KB to 45.5KB (gzipped). On November 2,
lobe-ui#776
introduced the fix: per-component stylesheets, so applications only pull in what they use. In a benchmark app using 30 components, per-component loading yielded 45.9KB, compared to 59.5KB for the full
style.css
bundle. lobe-chat is currently still running on the monolithic
style.css
and hasn't made the switch yet.
What antd was doing behind the scenes
Once antd and emotion were completely removed from the dependency tree, hidden assumptions began surfacing. Beyond providing components, antd silently did plenty of heavy lifting for the entire page: setting root fonts and sizes, providing baseline icon layout, and supplying a global reset. None of this was ever stated in application code—it only became visible after antd was removed:
Symptom
Cause
Fix
Text without a font size falls back to a 16px system font
antd's
App
previously set the font family, font size, line height, and color for everything underneath
theme.css
puts them back in the lowest cascade layer,
@layer lobe-base
, leaving
html
alone so rem values don't change; see
lobe-ui#703
Icons sit 2–3px higher than the text beside them
.anticon
's
inline-flex
and
vertical-align
were previously provided by antd styles
Icon now supplies these baseline layout rules itself; see
lobe-ui#705
List rows stop inheriting the app's font settings
During migration, expanding the
font: inherit
shorthand into longhand lost
font-feature-settings
along with other properties only reset by the shorthand
Fixed by reverting to
font: inherit
; see also lobe-ui#705
ScrollShadow
stops hiding scrollbars
Because component styles moved into
@layer lobe-ui
, the app's unlayered
* { scrollbar-width: thin }
rule took higher priority
Remove the duplicate global rule from the app, or place it below
lobe-ui
in the cascade
The last two issues both trace back to CSS cascade layers. Placing component styles into
@layer
, the layer hierarchy (from lowest to highest) looked like this:
Unlayered styles always beat layered styles, regardless of selector specificity. That makes overriding component styles easy, but, an offhand global rule in application code can also quietly stomp over components.
The icon vertical misalignment was the trickiest to catch. The visual regression tool mentioned in lobe-ui#705 used the v6 preview as its baseline. But
.anticon
styles had vanished earlier when
lobe-ui#699
stripped antd, so the regression was already baked into the baseline, leaving the diff completely empty. We eventually caught it with the naked eye in the Tree component. Once we added a visual comparison against an antd-era lobe-chat build, vertical alignment across 73 icons and text elements snapped into place on the home page, appearance settings, and community page—where the pre-fix preview had matched only 3. A visual regression baseline must be the last version users actually saw, not the previous commit.
Conversely, bugs in the old implementation could also sneak into the baseline. emotion's
cx
merges multiple class names into one, which prevented the
& + &
divider rule in lobe-chat's workspace empty state from matching any element. After the move to StyleX, it kicked in for the first time, and the comparison tool flagged it as a diff. We kept this change as intended behavior.
How much lighter is a Button after dropping antd?
Because application code in the main lobe-chat bundle was also evolving over the year, comparing it before and after wouldn't isolate what changed in the component library itself. Instead, I spun up a clean Vite project rendering a single Button, building it with v5 (5.64.4, with the antd Button) and v6 (6.15.0). Both setups included only what was strictly necessary for rendering: v5 wrapped the button in
ThemeProvider
, while v6 imported
theme.css
alongside the Button stylesheet, plus a
MotionProvider
.
Excluding React, Button-related JS dropped from ~130KB to ~32KB. The bulk of v5 came from antd and its rc-component dependencies, totaling around 287KB uncompressed; v6's 32KB mostly belongs to the motion animation library, with lobe-ui itself accounting for just ~9KB uncompressed. The tradeoff is that v6 introduces a static CSS file measuring 22.6KB gzipped, of which 16.5KB is "}
theme.css
design tokens, shared across all components; v5 shipped no CSS files because JavaScript generated styles at runtime, shared across all components and generated styles at runtime with JS.
During benchmarking, we also uncovered an issue: importing from the root entry
import { Button } from '@lobehub/ui'
, both versions pulled in around 450KB of unminified —or roughly 141KB gzipped KaTeX and Markdown parsing code that had nothing to do with Button. The figures above already exclude this overhead. In v6, importing from the
es/Button
subpath avoids pulling it in entirely, whereas v5 only exported the root entry, leaving no way around it. The reason was that the root entry re-exported
@lobehub/streamdown
's
rehypeStreamAnimated
, but streamdown's package.json didn't declare
sideEffects
, and the module top level contained impure
memo()
calls and
displayName
assignments. Because bundlers couldn't prove they were side-effect-free, they had to keep the entire Markdown rendering stack. The fix was shipped in
lobehub/streamdown#7
in version 1.4.5, simply adding to package.json:
"sideEffects": false
. lobe-ui 6's dependency range automatically picks up this new release. After a clean reinstall, importing from the root entry matches the subpath import at 92.4KB.
Beyond bundle size, we also eliminated the leftover styling overhead from antd. The share, workbench, and auth SSR apps previously had to extract antd's static CSS separately;
lobehub#20503
deleted that entire pipeline. We also removed the
antdOverride
global stylesheet that existed solely to override antd defaults, while
lobehub#21046
purged the application CSS rules written for
.ant-*
classes, which no longer match any elements once antd was removed.
Next step: can we migrate Application Code to StyleX in One Go?
With the component library migrated, styling in application code was still using the legacy styling approach: using
createStaticStyles
at the top of a file to write CSS in template strings, which Emotion then injected into the page at runtime. On canary, 1,112 files still follow this pattern, while around 350 have been converted to StyleX. On October 20,
lobehub#21042
paved the way for writing StyleX in application code, allowing direct imports of lobe-ui design tokens. Below is a file from the homepage sidebar notifications list, shown before and after the rewrite in
lobehub#21446
:
Before:
createStaticStyles
CodeBlock Loading...
After: StyleX
CodeBlock Loading...
Rewriting a single file isn't hard; the hard part is proving it looks identical afterward. Notice the extra property on the right:
backgroundImage: 'none'
on the right: the original
background
is a shorthand property that also resets the background image. StyleX discourages shorthand properties, which means writing only
backgroundColor
drops that reset. The
font: inherit
pitfall in the earlier table stems from the exact same issue. Visual differences like this rarely show up in screenshots, and comparing over a thousand files by eye is painfully slow and error-prone. Beyond writing a migrator, we needed an automated tool to confirm styles stayed identical before and after the rewrite and catch pitfalls like the ones above before and after.
Our initial plan was to compare computed styles rather than screenshots: checking browser-computed styles before and after across themes, breakpoints, and hover or focus states for every styled element. Taking HomeSidebar (
lobehub#21446
) and ChatInput (
lobehub#21452
), it caught an actual regression:
Params/Controls.tsx
had its
font: inherit
expanded into longhands, causing the button to lose its
font-feature-settings
. The exact trap we stumbled into in the component library resurfaced during the app migration—except this time the tool caught it first.
Before trusting the tool when it reported "equivalent," we had to prove the tool itself was trustworthy. That verification baseline required three things: tell noise from real differences by remaining completely stable when comparing a version against itself; catch actual regressions by flagging 100% of intentionally injected changes; and know its limits by deferring anything synthetic rendering can't cover to human review, storing those sign-offs with the source code and invalidating them whenever the code changes.
Once the baseline was locked in, we re-ran all 16 migration PRs summarized in
lobehub#22041
. The results fell into three buckets: proven equivalent and passed immediately, divergent and sent back for fixes, or unprovable and escalated for human review.
To save reviewers from digging through logs, I built a local reporting UI. The overview lists results by file and condition, letting you click into any element to inspect evidence and see a side-by-side live comparison. Meanwhile, the sign-off page groups items by root cause for batch approval.
Report overview: one row per file, one column per condition. ✓ indicates equivalent; numbers show counts of differing elements.
Sign-off view: grouped by reason, with side-by-side renders comparing before and after under the same condition
Summary
Between December 2025 and October 2026, lobe-ui evolved from v3 to v6, direct antd imports in lobe-chat dropped from a peak of 485 files to zero, and the JS footprint for a single Button shrank from around 130KB to roughly 32KB (gzipped). Looking back, once AI and codemods made rewriting code cheap, the real bottlenecks came down to two challenges: creating coexistence mechanisms and guardrails so shipping never stopped while legacy patterns continuously shrank, and automatically proving with tooling that behavior and styles hadn't regressed. A few key practices from this year transfer well to other projects:
Let new and legacy components coexist in the same package, migrating component by component.
v5's
base-ui
subpath spared application code from an all-or-nothing rewrite, allowing us to tear down that scaffolding in v6.
Migrate the highest-overhead, most interconnected layer first.
Overlays share positioning and z-index logic. Declarative modals stay mounted all the time, whereas an imperative approach only incurs overhead when a modal actually opens.
Make new components drop-in replacements.
Match both the API and visual appearance of legacy components so app code only changes import paths, porting over quirks like Tag's color resolution verbatim.
Lock down migrated categories with lint rules, grandfathering existing usage via allowlists.
AGENTS.md
and skills couldn't prevent AI agents from mimicking legacy antd patterns found in existing files. Import counts only began to steadily decline once we added lint rules and commit hooks on June 26.
Verify equivalence via computed styles, using the version users actually see as the baseline.
.anticon
positioning drift and
font: inherit
attribute loss both slipped past screenshot diffs and "compare against previous version" checks.
Isolate variables when measuring gains.
Instead of benchmarking entire production bundles, spin up a dedicated project rendering only a single Button—which also uncovered our root entry tree-shaking bug.