Local Components vs Runtime Components: Which One Should You Use?

If you've ever debated between shadcn/ui and HeroUI — or wondered why one team copies components manually while another just runs npm install — it comes down to one architectural decision most developers make without thinking about it.

There are two fundamentally different ways to use a UI component library. Understanding the difference will change how you evaluate every library going forward.

What are Local Components?

Local components are copied directly into your codebase — not installed as an npm dependency. shadcn/ui is the most prominent example right now.

Run this in your terminal:

bash

npx shadcn@latest add button

Nothing gets added to node_modules. Instead, a file appears:

components/
└── ui/
    └── button.tsx   ← this is now yours

That code is yours to keep. Change the variants, remove props you don't need, rewrite the internals, redesign how it looks entirely — no waiting for a release, no fighting a theming API, no permission needed from anyone.

The key insight: shadcn/ui is not a library you install. It's a collection of code you own.

What are Runtime Components?

Runtime components work the traditional way — install, import, use. HeroUI, Nuxt UI, Mantine, Chakra UI, and PrimeVue all fall into this category.

bash

npm install @heroui/react

The components live inside node_modules. Your project structure stays clean:

node_modules/
└── @heroui/
    └── react/        ← their code, not yours

If you need to change how a component looks or behaves, you go through whatever customization system the library provides — usually a theme config, CSS variables, or class overrides.

tsx

// Customizing in HeroUI — you work within their system
<Button color="primary" variant="bordered" radius="sm">
  Click me
</Button>

Sometimes that's enough. Sometimes it isn't.

The Core Question: Who's Actually in Control?

With local components, the answer is clear:

You are. No external dependency can release a major version and break your entire UI. No library roadmap decides when a design bug gets fixed.

With runtime components, the trade-off flips:

They own the code, you own the speed. Polished components, solid docs, and active maintenance — but you're tied to their release cycle.

Here's the difference side by side:

Local (shadcn/ui)              Runtime (HeroUI, Nuxt UI)
──────────────────             ──────────────────────────
Code lives in /components      Code lives in node_modules
Edit anything directly         Customize via theme API
No breaking changes            Major versions can break
You maintain it                They maintain it
Slower to start                Faster to start

When to Choose Local Components

Go with the local approach when:

• You're building a long-term product where UI quality is a differentiator

• You need a custom design system that doesn't look like a template

• Your team has bandwidth to own and evolve UI code over time

• You want zero risk of breaking changes from an external package

A concrete example — if you need a button that behaves like this:

tsx

<Button variant="ghost-amber" size="sm" loading={isPending}>
  Save changes
</Button>

With a local component, you just add that variant and loading prop directly to button.tsx. With a runtime library, you're either overriding, wrapping, or hoping it's on their roadmap.

When to Choose Runtime Components

Go with the runtime approach when:

• You're prototyping or shipping an MVP and time-to-market matters most

• You have a small team with no capacity to maintain a UI library

• The project has a short scope and visual differentiation isn't the goal

• You want a complete, consistent UI without building anything from scratch

bash

# Get a full component system in minutes
npm install @nuxtjs/ui

# Import and go
import { UButton, UModal, UTable } from '#components'

For those scenarios, Nuxt UI and HeroUI are genuinely excellent choices. Don't fight the tool.

The Bottom Line

Building something long-term with a unique visual identity? Local components are the better investment.

Validating an idea or racing to an MVP? Runtime components are the pragmatic choice.

The mistake isn't choosing one over the other — it's choosing without understanding the trade-off.

Junno UI is built entirely on the local approach. Every component lands directly in your project as editable source code, with no dependency on anyone else's roadmap, release schedule, or design decisions.