Reduce React Bundle Size with Per-Component Imports

A component library should cost you only the components you use. In practice, importing everything from a library's main entry point often ships far more than that. This guide explains why, and how to import oks-ui so your app pays only for what it renders.

Why "just import it" can be expensive

The usual import looks harmless:

import { Button, Modal, Table } from "oks-ui";
import "oks-ui/styles.css";

Bundlers try to drop unused exports ("tree shaking"), but they can only drop code they can prove has no side effects. A stylesheet import is a side effect by definition, and a single combined stylesheet contains every component's CSS no matter which ones you use. The result in many real apps: the whole library ships. For oks-ui that is around 770 KB of JavaScript before compression and a 320 KB stylesheet — even for a page with three components.

Import each component from its own path

Since version 1.2, every oks-ui component has its own entry point and its own stylesheet:

import { Button } from "oks-ui/button";
import "oks-ui/button.css";

import { Modal } from "oks-ui/modal";
import "oks-ui/modal.css";

import { Table } from "oks-ui/table";
import "oks-ui/table.css";

The bundler has nothing to guess about: it includes the files you imported and nothing else.

Two things make this easy:

• Stylesheets include their parts. oks-ui/modal.css already contains the Backdrop's styles, and oks-ui/table.css covers its empty state and loading skeleton. You never need to know what a component is made of.
• Tokens stay global. Load oks-ui/tokens.css (and optionally oks-ui/utilities.css) once at the root of your app. Every component reads the same colour, spacing and radius variables.

The path is the component name in kebab-case: oks-ui/button-group, oks-ui/page-title, oks-ui/form-field-set, oks-ui/text-editor.

Next.js and Turbopack

Each component's JavaScript also imports its own stylesheet, and most bundlers — webpack, Vite, Rollup, Rspack — follow that automatically. Next.js with Turbopack does not follow a stylesheet imported from inside a package, so write the .css import yourself. It's harmless elsewhere, so the simplest rule is to always write it.

In the App Router, add "use client" to files that render oks-ui components. A small wrapper file per component keeps that boundary contained, so your pages can stay server components.

Migration checklist

1. Replace import "oks-ui/styles.css" with oks-ui/tokens.css and oks-ui/utilities.css in your root stylesheet.
2. Change each from "oks-ui" import to the component's own path, and add its .css import beside it.
3. Search for any remaining from "oks-ui" — one leftover import can pull the whole library back in.
4. Open each page and look for unstyled components. A missing .css import is the only thing that can go wrong, and it is obvious on sight.

Old and new imports work side by side, so you can migrate one file at a time.

Measure it

Don't trust the theory — measure before and after:

• Your framework's build output lists the size of each route.
• A bundle analyzer shows which packages end up in each chunk.
• Lighthouse on a throttled mobile profile shows what the difference means for real users.

On the oks-ui website, moving to per-component imports cut compressed CSS from 48 KB to 16 KB and JavaScript by about a fifth. Less CSS matters most on phones, because the browser can't paint the page until its stylesheets have arrived.

See both import styles in the installation guide.