5 Pitfalls

Common Pitfalls

Patterns that catch beginners off guard. Each entry shows the wrong way, the right way, and why it matters.

Conditional Element Rendering

❌ Problem

Using a dynamic function to conditionally return different elements won't render anything visible:

typescript

✅ Solution

Use when() to conditionally mount/unmount elements from the DOM:

typescript

Why?

Dynamic functions like () => value work great for text content and attributes because Nuclo re-evaluates them during update(). But elements need to be physically mounted and removed from the DOM — that's what when() is for.

Forgetting to Call update()

❌ Problem

Changing state without calling update() leaves the UI frozen:

typescript

✅ Solution

Always call update() after mutating state to run a new update pass:

typescript

Replacing Objects in Lists

❌ Problem

Creating a new object instead of mutating the existing one causes list() to destroy and recreate the DOM element:

typescript

✅ Solution

Mutate the existing object to preserve DOM identity and skip unnecessary re-creation:

typescript

Why?

list() tracks items by object reference. Replace the reference and Nuclo treats it as a brand-new item, discarding the old DOM node and building a fresh one. Mutate in place to let the element live on.

Multiple update() Calls in One Handler

❌ Problem

Calling update() after every mutation causes redundant DOM passes:

typescript

✅ Solution

Batch all mutations, then call update() exactly once:

typescript

Static Value Where a Dynamic Binding Is Needed

❌ Problem

Interpolating a variable directly captures the value at construction time — it never updates:

typescript

✅ Solution

Wrap in an arrow function so it re-evaluates on every update():

typescript

💡 Tip

If you're ever unsure whether something should be a function: ask yourself — should this value change after the initial render? If yes, wrap it in () =>.

Quick Reference

Concept✅ Do❌ Avoid

Conditional elementswhen()() => condition ? A : B

State changesupdate() after mutatingmutate without update()

List itemsmutate objects in-placereplace with new objects

Batchingone update() per handlerupdate() after each mutation

Dynamic content() => expressionplain interpolation

Next Steps

Core API

Deep dive into update(), list(), when(), and on().

Getting Started

Build your first Nuclo application from scratch.

Examples

See all pitfalls avoided in real working demos.

Styling

Learn the CSS-in-JS system and style helpers.