DEV Community: Nucleify

Dlaczego SSR nadal ma znaczenie (i kiedy faktycznie warto go używać)

Nucleify — Sun, 08 Feb 2026 02:42:28 +0000

Przez ostatnie lata renderowanie po stronie klienta stało się domyślnym wyborem dla wielu projektów frontendowych. Frameworki przyspieszyły, przeglądarki stały się wydajniejsze, a SPA przejęły rynek.

Więc… dlaczego Server-Side Rendering (SSR) nadal ma sens?

Po pracy nad produkcyjnym projektem Nuxt z realnymi wymaganiami wydajnościowymi, oto dlaczego wciąż sięgam po SSR — i kiedy naprawdę warto go używać.

1. Szybszy First Contentful Paint (FCP)

Przy SSR serwer wysyła gotowy do wyrenderowania HTML, zamiast pustego <div id="app">.

Dzięki temu:

przeglądarka może natychmiast wyrenderować treść
użytkownik szybciej widzi coś użytecznego
odczuwalna wydajność znacząco rośnie

Jest to szczególnie istotne na wolnych połączeniach i urządzeniach mobilnych.

2. Lepsze Core Web Vitals (LCP, INP)

SSR pomaga poprawić:

LCP – największy element treści jest dostępny niemal od razu
INP – hydrację można kontrolować lub odroczyć
TTFB – zoptymalizowany render po stronie serwera często wygrywa z bootowaniem SPA

W połączeniu z prerenderingiem i selektywną hydracją SSR daje realne zyski wydajnościowe, a nie tylko lepsze wyniki Lighthouse.

3. SEO bez hacków

Wyszukiwarki mogą indeksować w pełni wyrenderowany HTML bez:

polegania na JavaScript po stronie klienta
czekania na hydrację
crawler-specific workaroundów

Dla stron contentowych, landing pages i stron marketingowych SSR usuwa całą klasę problemów SEO jeszcze zanim się pojawią.

4. Lepsze UX na wolnych lub niestabilnych połączeniach

SSR zapewnia:

widoczną treść nawet gdy JS ładuje się wolno
możliwość natychmiastowego czytania strony
mniejsze przesunięcia layoutu

W wielu przypadkach hydracja może się „nie udać”, a strona nadal pozostaje czytelna jako dokument HTML.

5. Przewidywalne renderowanie i pobieranie danych

Dzięki SSR:

dane są pobierane przed renderem
UI od razu odzwierciedla rzeczywisty stan
mniej spinnerów i „loadingów” na starcie

W połączeniu z cache’owaniem daje to bardzo stabilne i przewidywalne zachowanie aplikacji.

6. SSR + Prerendering = najlepsze z obu światów

Nie każda strona musi być w pełni dynamiczna.

Skuteczne podejście to:

SSR dla stron dynamicznych
Prerendering dla stron statycznych lub pół-statycznych
Async components + odroczona hydracja

Dzięki temu aplikacja jest szybka bez przeciążania serwera.

Kiedy SSR może nie mieć sensu

SSR nie jest darmowy. Wprowadza:

większą złożoność architektury
koszty infrastruktury
więcej elementów operacyjnych

Prawdopodobnie nie potrzebujesz SSR, jeśli:

aplikacja jest wewnętrzna
SEO nie ma znaczenia
wydajność pierwszego wejścia nie jest kluczowa

Podsumowanie

SSR nie jest srebrną kulą — ale używany świadomie nadal jest jednym z najpotężniejszych narzędzi do budowania szybkich i odpornych aplikacji webowych.

Kluczem nie jest „włączyć SSR”, tylko podejmować świadome decyzje architektoniczne.

Jeśli chcesz kolejny wpis o:

strategiach hydracji w SSR
optymalizacji Nuxt
realnych problemach z SSR w produkcji

daj znać w komentarzu 👇

Why SSR Still Matters (and When It’s Actually Worth Using)

Nucleify — Sun, 08 Feb 2026 02:42:07 +0000

In the last few years, client-side rendering became the default choice for many frontend projects. Frameworks got faster, browsers got better, and SPAs took over.

So… why does Server-Side Rendering (SSR) still matter?

After working on a production Nuxt project with real performance constraints, here’s why I still reach for SSR — and when it makes sense.

1. Faster First Contentful Paint (FCP)

With SSR, the server sends ready-to-render HTML instead of an empty <div id="app">.

That means:

the browser can render content immediately
users see something useful faster
perceived performance is dramatically better

This is especially important on slow networks and mobile devices.

2. Better Core Web Vitals (LCP, INP)

SSR helps improve:

LCP – the largest content element is often available immediately
INP – hydration can be deferred or controlled
TTFB – optimized server rendering can beat client-only boot time

When combined with prerendering and selective hydration, SSR provides real-world performance gains, not just better Lighthouse scores.

3. SEO Without Hacks

Search engines can index fully rendered HTML without relying on:

client-side JavaScript execution
hydration timing
crawler-specific workarounds

For content-heavy websites, landing pages, or marketing pages, SSR removes a whole class of SEO problems before they appear.

4. Better UX on Slow or Unstable Connections

SSR ensures:

content is visible even if JavaScript loads slowly
users can start reading immediately
layout shifts are reduced

In many cases, hydration can fail gracefully — the page still works as a readable document.

5. Predictable Rendering and Data Fetching

With SSR:

data is fetched before rendering
the UI reflects real state instantly
fewer loading spinners on first load

When combined with caching, this leads to very stable and predictable behavior.

6. SSR + Prerendering = Best of Both Worlds

Not every page needs to be fully dynamic.

A common and effective strategy:

SSR for dynamic pages
Prerendering for static or semi-static pages
Async components + deferred hydration

This keeps applications fast without overloading the server.

When SSR Might Not Be Worth It

SSR isn’t free. It adds:

server complexity
infrastructure costs
more operational overhead

You may not need SSR if:

your app is purely internal
SEO is irrelevant
first-load performance isn’t critical

Final Thoughts

SSR is not a silver bullet — but when used intentionally, it remains one of the most powerful tools for building fast, resilient web applications.

The key isn’t enabling SSR by default — it’s making conscious architectural decisions.

If you’d like a follow-up post about:

SSR hydration strategies
Nuxt performance patterns
real-world SSR pitfalls

let me know in the comments 👇

Dlaczego warto używać plików index: Wzorzec Folder-as-Component

Nucleify — Tue, 03 Feb 2026 21:25:47 +0000

Czy kiedykolwiek przeszukiwałeś projekt React lub Vue i natrafiłeś na dziesiątki plików typu Button.tsx, Button.vue, ButtonStyles.scss, ButtonTypes.ts, useButton.ts?

W tym artykule pokażę Ci alternatywne podejście – Folder-as-Component – które stosuję w projekcie Nucleify, modularnym frameworku full-stack. Ten wzorzec działa równie dobrze w React, Vue, Nuxt, Next.js czy dowolnej architekturze opartej na komponentach.

🎯 Problem: Chaos w nazewnictwie

Typowy projekt frontend wygląda często tak:

components/
├── Button.tsx
├── Button.vue
├── ButtonProps.ts
├── ButtonStyles.scss
├── Card.tsx
├── CardProps.ts
├── CardStyles.scss
├── Navbar.tsx
├── NavbarLinks.tsx
├── NavbarDrawer.tsx
├── NavbarStyles.scss
...

Co jest nie tak?

Płaska struktura – wszystko w jednym folderze
Redundantne prefixy – Button, Button, Button...
Brak enkapsulacji – trudno stwierdzić, co należy do czego
Problemy ze skalowaniem – przy 50+ komponentach robi się koszmar
IDE tab hell – 10 otwartych tabów z Button* w nazwie

💡 Rozwiązanie: Folder-as-Component

Zamiast nazywać pliki po komponencie, nazywam foldery po komponencie, a pliki wewnątrz zawsze mają te same nazwy:

components/
├── button/
│   ├── index.ts          # eksportuje komponent + typy
│   ├── index.tsx         # komponent React
│   ├── index.vue         # lub komponent Vue
│   ├── _index.scss       # style (underscore = SCSS partial)
│   └── types/
│       ├── index.ts      # barrel export
│       └── interfaces.ts
├── card/
│   ├── index.ts
│   ├── index.tsx
│   └── _index.scss
└── navbar/
    ├── index.ts
    ├── index.tsx
    ├── _index.scss
    └── components/       # zagnieżdżone komponenty
        ├── index.ts
        ├── _index.scss
        ├── Drawer/
        │   ├── index.ts
        │   ├── index.tsx
        │   └── _index.scss
        └── Links/
            ├── index.ts
            ├── index.tsx
            └── _index.scss

🔥 Przykłady z życia

Zobaczmy jak wygląda struktura przycisku w React i Vue:

Przykład React: `components/button/`

index.ts – eksportuje komponent i typy:

export { Button } from './index.tsx'
export * from './types'

index.tsx – komponent React:

import type { ButtonProps } from '.'
import clsx from 'clsx'
import './index.scss'

export const Button = ({ 
  variant, 
  size, 
  icon, 
  label, 
  children,
  className,
  ...props 
}: ButtonProps) => {
  return (
    <button
      className={clsx(
        'button',
        variant && `${variant}-button`,
        size && `${size}-button`,
        className
      )}
      {...props}
    >
      {icon && <Icon name={icon} />}
      {label && <span>{label}</span>}
      {children}
    </button>
  )
}

Przykład Vue: `components/button/`

index.ts – eksportuje komponent i typy:

export { default as Button } from './index.vue'
export * from './types'

index.vue – komponent Vue:

<template>
  <button
    :class="[
      'button',
      variant && `${variant}-button`,
      size && `${size}-button`
    ]"
  >
    <Icon v-if="icon" :name="icon" />
    <span v-if="label">{{ label }}</span>
    <slot />
  </button>
</template>

<script setup lang="ts">
import type { ButtonProps } from '.'  // Import z tego samego folderu!

const props = defineProps<ButtonProps>()
</script>

<style lang="scss">
@import 'index';  // Ładuje _index.scss
</style>

Wspólne: `_index.scss`

.button {
  display: flex;
  align-items: center;
  justify-content: center;
  gap: 0.5rem;
  transition: all 0.3s ease;

  &.primary-button {
    background: var(--primary);
    color: white;
  }

  &.secondary-button {
    background: transparent;
    border: 1px solid var(--primary);
  }

  &.sm-button {
    padding: 0.25rem 0.5rem;
  }
  &.md-button {
    padding: 0.5rem 1rem;
  }
  &.lg-button {
    padding: 0.75rem 1.5rem;
  }
}

Wspólne: `types/interfaces.ts`

import type { ButtonHTMLAttributes } from 'react' // lub z vue

export type ButtonVariant = 'primary' | 'secondary' | 'ghost'
export type ButtonSize = 'sm' | 'md' | 'lg'

export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: ButtonVariant
  size?: ButtonSize
  label?: string
  icon?: string
}

🌳 Barrel Exports – agregacja modułów

Magia dzieje się w plikach index.ts na wyższych poziomach:

components/atoms/index.ts – eksportuje wszystkie atomy:

export * from './avatar'
export * from './badge'
export * from './button'
export * from './checkbox'
export * from './heading'
export * from './icon'
export * from './image'
// ... itd.

components/sections/index.ts – eksportuje sekcje:

export * from './contact'
export * from './hero'
export * from './faq'
export * from './footer'
export * from './navbar'

Analogicznie dla SCSS:

components/sections/_index.scss:

@import 'contact', 'hero', 'faq', 'footer', 'navbar';

Dzięki temu w głównym pliku stylów wystarczy:

@import 'components/sections';

📁 Zagnieżdżone komponenty

Navbar zazwyczaj ma własne subkomponenty. Oto struktura:

navbar/
├── index.ts
├── index.tsx          # lub index.vue
├── _index.scss
└── components/
    ├── index.ts          # export * from './Drawer'; export * from './Links'
    ├── _index.scss       # @import 'Drawer', 'Links';
    ├── Drawer/
    │   ├── index.ts
    │   ├── index.tsx
    │   └── _index.scss
    └── Links/
        ├── index.ts
        ├── index.tsx
        ├── _index.scss
        └── links.ts      # dane linków

navbar/index.tsx – czyste i czytelne importy:

import { NavbarDrawer, NavbarLinks } from './components'
import './index.scss'

export const Navbar = () => {
  return (
    <nav className="navbar">
      <Logo />
      <NavbarLinks />
      <NavbarDrawer />
    </nav>
  )
}

✅ Zalety wzorca Folder-as-Component

1. Intuicyjne importy

// Zamiast:
import Button from '@/components/Button.tsx'
import { ButtonProps } from '@/components/ButtonTypes'

// Mamy:
import { Button, ButtonProps } from '@/components/button'
// lub z barrel exportu:
import { Button } from '@/components'

2. Enkapsulacja

Wszystko związane z komponentem jest w jednym miejscu. Chcesz usunąć Button? Usuwasz folder button/.

3. Skalowalność

Przy 100+ komponentach nadal masz porządek – każdy komponent to osobny "mikro-pakiet".

4. IDE-friendly

Zakładki pokazują nazwę folderu, nie pliku
Szybkie Ctrl+P / Cmd+P → wpisujesz button/index i od razu wiesz co to
Mniej konfliktów nazw

5. Konsystencja

Każdy developer wie, gdzie szukać:

Komponent → index.tsx / index.vue
Eksporty → index.ts
Style → _index.scss
Typy → types/interfaces.ts

6. Łatwe refaktorowanie

Przenosisz cały folder bez zmiany importów wewnętrznych.

7. Tree-shaking friendly

Bundler może łatwo analizować, co jest używane.

8. Niezależność od frameworka

Ta sama struktura działa w React, Vue, Svelte, Angular – zmienia się tylko rozszerzenie pliku komponentu.

⚙️ Konwencje nazewnictwa plików

`index.ts` vs `index.tsx` vs `index.vue`

Plik	Cel
`index.ts`	Barrel exports (re-eksportuje komponent + typy)
`index.tsx`	Komponent React/Preact z JSX
`index.vue`	Vue Single File Component
`index.svelte`	Komponent Svelte

Konwencja `_index.scss`

Underscore (_) w SCSS oznacza partial – plik, który nie kompiluje się samodzielnie, tylko jest importowany przez inne pliki.

// W komponencie:
@import 'index';  // Ładuje _index.scss z tego samego folderu

// W agregatorze:
@import 'button', 'card', 'navbar';  // Ładuje _index.scss z każdego folderu

🎨 Jak to wygląda w praktyce?

W prawdziwym projekcie cała architektura oparta jest na tym wzorcu:

src/
├── components/
│   ├── atoms/
│   │   ├── index.ts
│   │   ├── _index.scss
│   │   ├── button/
│   │   │   ├── index.ts
│   │   │   ├── index.tsx
│   │   │   ├── _index.scss
│   │   │   └── types/
│   │   │       ├── index.ts
│   │   │       └── interfaces.ts
│   │   ├── icon/
│   │   └── input/
│   ├── molecules/
│   │   ├── index.ts
│   │   ├── search-bar/
│   │   └── form-field/
│   └── organisms/
│       ├── index.ts
│       ├── navbar/
│       ├── footer/
│       └── sidebar/
├── hooks/
│   ├── index.ts
│   ├── use-auth.ts
│   └── use-theme.ts
└── utils/
    ├── index.ts
    ├── format-date.ts
    └── cn.ts

Każdy komponent ma tę samą strukturę. Nowy developer od razu wie, gdzie co znaleźć.

🚀 Quick Start

Chcesz wdrożyć to w swoim projekcie? Oto minimalna struktura:

React

src/
└── components/
    └── button/
        ├── index.ts        # export { Button } from './index.tsx'; export * from './types'
        ├── index.tsx       # export const Button = () => <button>...</button>
        ├── _index.scss
        └── types/
            ├── index.ts
            └── interfaces.ts

Vue

src/
└── components/
    └── button/
        ├── index.ts        # export { default as Button } from './index.vue'; export * from './types'
        ├── index.vue       # <template>...</template>
        ├── _index.scss
        └── types/
            ├── index.ts
            └── interfaces.ts

Import

import { Button } from '@/components/button'
// lub z barrel:
import { Button } from '@/components'

📚 Podsumowanie

Aspekt	Tradycyjne	Folder-as-Component
Struktura	Płaska	Hierarchiczna
Nazewnictwo plików	`ComponentName.*`	`index.*`
Enkapsulacja	Słaba	Silna
Skalowalność	❌	✅
Importy	Długie ścieżki	Krótkie, z barrel
Refaktoring	Trudny	Łatwy
Framework	Specyficzny	Agnostyczny

🔗 Linki

Nucleify demo
Nucleify na GitHubie – sprawdź pełną implementację
Atomic Design – metodologia, która świetnie współgra z tym wzorcem
Barrel Exports Pattern – więcej o agregacji eksportów

Masz pytania? Zostaw komentarz! 👇

A jeśli podoba Ci się ta konwencja, daj ⭐ na GitHubie Nucleify 🚀

Why You Should Use index Files: The Folder-as-Component Pattern

Nucleify — Tue, 03 Feb 2026 21:23:19 +0000

Have you ever browsed through a React or Vue project and stumbled upon dozens of files like Button.tsx, Button.vue, ButtonStyles.scss, ButtonTypes.ts, useButton.ts? And then realized half of them belong to a completely different module?

In this article, I'll show you an alternative approach – Folder-as-Component – which I use in Nucleify, a modular full-stack framework. This pattern works equally well in React, Vue, Nuxt, Next.js, or any component-based architecture.

🎯 The Problem: Naming Chaos

A typical frontend project often looks like this:

components/
├── Button.tsx
├── Button.vue
├── ButtonProps.ts
├── ButtonStyles.scss
├── Card.tsx
├── CardProps.ts
├── CardStyles.scss
├── Navbar.tsx
├── NavbarLinks.tsx
├── NavbarDrawer.tsx
├── NavbarStyles.scss
...

What's wrong with this?

Flat structure – everything dumped in one folder
Redundant prefixes – Button, Button, Button...
Poor encapsulation – hard to tell what belongs to what
Scaling issues – at 50+ components it becomes a nightmare
IDE tab hell – 10 open tabs all starting with Button*

💡 The Solution: Folder-as-Component

Instead of naming files after components, I name folders after components, while files inside always have the same names:

components/
├── button/
│   ├── index.ts          # exports component + types
│   ├── index.tsx         # React component
│   ├── index.vue         # or Vue component
│   ├── _index.scss       # styles (underscore = SCSS partial)
│   └── types/
│       ├── index.ts      # barrel export
│       └── interfaces.ts
├── card/
│   ├── index.ts
│   ├── index.tsx
│   └── _index.scss
└── navbar/
    ├── index.ts
    ├── index.tsx
    ├── _index.scss
    └── components/       # nested components
        ├── index.ts
        ├── _index.scss
        ├── Drawer/
        │   ├── index.ts
        │   ├── index.tsx
        │   └── _index.scss
        └── Links/
            ├── index.ts
            ├── index.tsx
            └── _index.scss

🔥 Real-World Examples

Let's see how a button component is structured in both React and Vue:

React Example: `components/button/`

index.ts – exports the component and types:

export { Button } from './index.tsx'
export * from './types'

index.tsx – the React component:

import type { ButtonProps } from '.'
import clsx from 'clsx'
import './index.scss'

export const Button = ({ 
  variant, 
  size, 
  icon, 
  label, 
  children,
  className,
  ...props 
}: ButtonProps) => {
  return (
    <button
      className={clsx(
        'button',
        variant && `${variant}-button`,
        size && `${size}-button`,
        className
      )}
      {...props}
    >
      {icon && <Icon name={icon} />}
      {label && <span>{label}</span>}
      {children}
    </button>
  )
}

Vue Example: `components/button/`

index.ts – exports the component and types:

export { default as Button } from './index.vue'
export * from './types'

index.vue – the Vue component:

<template>
  <button
    :class="[
      'button',
      variant && `${variant}-button`,
      size && `${size}-button`
    ]"
  >
    <Icon v-if="icon" :name="icon" />
    <span v-if="label">{{ label }}</span>
    <slot />
  </button>
</template>

<script setup lang="ts">
import type { ButtonProps } from '.'  // Import from the same folder!

const props = defineProps<ButtonProps>()
</script>

<style lang="scss">
@import 'index';  // Loads _index.scss
</style>

Shared: `_index.scss`

.button {
  display: flex;
  align-items: center;
  justify-content: center;
  gap: 0.5rem;
  transition: all 0.3s ease;

  &.primary-button {
    background: var(--primary);
    color: white;
  }

  &.secondary-button {
    background: transparent;
    border: 1px solid var(--primary);
  }

  &.sm-button {
    padding: 0.25rem 0.5rem;
  }
  &.md-button {
    padding: 0.5rem 1rem;
  }
  &.lg-button {
    padding: 0.75rem 1.5rem;
  }
}

Shared: `types/interfaces.ts`

import type { ButtonHTMLAttributes } from 'react' // or from vue

export type ButtonVariant = 'primary' | 'secondary' | 'ghost'
export type ButtonSize = 'sm' | 'md' | 'lg'

export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: ButtonVariant
  size?: ButtonSize
  label?: string
  icon?: string
}

🌳 Barrel Exports – Module Aggregation

The magic happens in index.ts files at higher levels:

components/atoms/index.ts – exports all atoms:

export * from './avatar'
export * from './badge'
export * from './button'
export * from './checkbox'
export * from './heading'
export * from './icon'
export * from './image'
// ... etc.

components/sections/index.ts – exports sections:

export * from './contact'
export * from './hero'
export * from './faq'
export * from './footer'
export * from './navbar'

Same pattern for SCSS:

components/sections/_index.scss:

@import 'contact', 'hero', 'faq', 'footer', 'navbar';

This means in your main stylesheet, you only need:

@import 'components/sections';

📁 Nested Components

A Navbar typically has its own subcomponents. Here's the structure:

navbar/
├── index.ts
├── index.tsx          # or index.vue
├── _index.scss
└── components/
    ├── index.ts          # export * from './Drawer'; export * from './Links'
    ├── _index.scss       # @import 'Drawer', 'Links';
    ├── Drawer/
    │   ├── index.ts
    │   ├── index.tsx
    │   └── _index.scss
    └── Links/
        ├── index.ts
        ├── index.tsx
        ├── _index.scss
        └── links.ts      # link data

navbar/index.tsx – clean and readable imports:

import { NavbarDrawer, NavbarLinks } from './components'
import './index.scss'

export const Navbar = () => {
  return (
    <nav className="navbar">
      <Logo />
      <NavbarLinks />
      <NavbarDrawer />
    </nav>
  )
}

✅ Benefits of the Folder-as-Component Pattern

1. Intuitive Imports

// Instead of:
import Button from '@/components/Button.tsx'
import { ButtonProps } from '@/components/ButtonTypes'

// You have:
import { Button, ButtonProps } from '@/components/button'
// or from barrel export:
import { Button } from '@/components'

2. Encapsulation

Everything related to a component is in one place. Want to delete Button? Just delete the button/ folder.

3. Scalability

Even with 100+ components, you maintain order – each component is its own "micro-package".

4. IDE-Friendly

Tabs show the folder name, not the file name
Quick Ctrl+P / Cmd+P → type button/index and you know exactly what it is
Fewer naming conflicts

5. Consistency

Every developer knows where to look:

Component → index.tsx / index.vue
Exports → index.ts
Styles → _index.scss
Types → types/interfaces.ts

6. Easy Refactoring

Move the entire folder without changing internal imports.

7. Tree-shaking Friendly

Bundlers can easily analyze what's being used.

8. Framework Agnostic

The same structure works in React, Vue, Svelte, Angular – only the component file extension changes.

⚙️ File Naming Conventions

`index.ts` vs `index.tsx` vs `index.vue`

File	Purpose
`index.ts`	Barrel exports (re-exports component + types)
`index.tsx`	React/Preact component with JSX
`index.vue`	Vue Single File Component
`index.svelte`	Svelte component

`_index.scss` Convention

The underscore (_) in SCSS denotes a partial – a file that doesn't compile on its own but is imported by other files.

// In a component:
@import 'index';  // Loads _index.scss from the same folder

// In an aggregator:
@import 'button', 'card', 'navbar';  // Loads _index.scss from each folder

🎨 What Does It Look Like in Practice?

In a real project, the entire architecture is built on this pattern:

src/
├── components/
│   ├── atoms/
│   │   ├── index.ts
│   │   ├── _index.scss
│   │   ├── button/
│   │   │   ├── index.ts
│   │   │   ├── index.tsx
│   │   │   ├── _index.scss
│   │   │   └── types/
│   │   │       ├── index.ts
│   │   │       └── interfaces.ts
│   │   ├── icon/
│   │   └── input/
│   ├── molecules/
│   │   ├── index.ts
│   │   ├── search-bar/
│   │   └── form-field/
│   └── organisms/
│       ├── index.ts
│       ├── navbar/
│       ├── footer/
│       └── sidebar/
├── hooks/
│   ├── index.ts
│   ├── use-auth.ts
│   └── use-theme.ts
└── utils/
    ├── index.ts
    ├── format-date.ts
    └── cn.ts

Every component follows the same structure. New developers immediately know where to find things.

🚀 Quick Start

Want to implement this in your project? Here's a minimal structure:

React

src/
└── components/
    └── button/
        ├── index.ts        # export { Button } from './index.tsx'; export * from './types'
        ├── index.tsx       # export const Button = () => <button>...</button>
        ├── _index.scss
        └── types/
            ├── index.ts
            └── interfaces.ts

Vue

src/
└── components/
    └── button/
        ├── index.ts        # export { default as Button } from './index.vue'; export * from './types'
        ├── index.vue       # <template>...</template>
        ├── _index.scss
        └── types/
            ├── index.ts
            └── interfaces.ts

Import

import { Button } from '@/components/button'
// or from barrel:
import { Button } from '@/components'

📚 Summary

Aspect	Traditional	Folder-as-Component
Structure	Flat	Hierarchical
File naming	`ComponentName.*`	`index.*`
Encapsulation	Weak	Strong
Scalability	❌	✅
Imports	Long paths	Short, via barrel
Refactoring	Difficult	Easy
Framework	Specific	Agnostic

🔗 Links

Nucleify demo
Nucleify on GitHub – check out the full implementation
Atomic Design – a methodology that pairs perfectly with this pattern
Barrel Exports Pattern – more on export aggregation

Got questions? Leave a comment below! 👇

If you like this convention, give a ⭐ on Nucleify's GitHub 🚀

Atomic Design: Should You Use It to Build Scalable UIs?

Nucleify — Sat, 24 Jan 2026 10:23:41 +0000

Nucleify implements the Atomic Design methodology to create UI systems that are consistent, maintainable, and scalable.

What is Atomic Design?

Atomic Design, created by Brad Frost, breaks user interfaces into fundamental building blocks. Inspired by chemistry, it organizes components in a hierarchy from the smallest elements to complete pages.

Key Benefits:

Consistency – reusable components ensure a unified look
Maintainability – changes propagate automatically across the system
Scalability – easily extend functionality without breaking existing components
Collaboration – clear structure improves teamwork

Core Principle: No Business Logic

Atomic Design components should not contain business logic. Components only handle functionality related to their UI behavior:

✅ Allowed	❌ Not Allowed
Input validation (format, length)	Hardcoded API calls
Animations and transitions	Direct data fetching
Local component state	Store mutations
Event emission	Hardcoded URLs or endpoints
Render based on props	Auth checks or domain-specific logic
Accessibility functions	Domain-specific calculations
Configurable callbacks via props	Rigid business rules
Generic event handlers	Hardcoded configuration

Business logic belongs to:

Stores (Pinia)
Composables
Services

Nucleify Extensions

Nucleify extends standard Atomic Design with modules where business logic is allowed:

Module	Purpose
`nuc_templates`	Reusable component templates (cards, forms, modals)
`nuc_sections`	Page sections with layout logic, data handling, and section-specific behavior
`nuc_pages`	Full page components with API calls, store access, and business rules

These modules are separated from nuxt/atomic/ to keep UI components clean and reusable.

Hierarchy Overview

Nucleify introduces an additional Bosons layer for types and utilities.

Bosons     → Interfaces, utility functions, constants (invisible layer)
Atoms      → Basic UI elements (Button, Input, Icon)
Molecules  → Simple atom combinations (FloatLabel, Tile)
Organisms  → Complex UI sections (DataTable, Dialog, Menu)
Templates  → Reusable component layouts (nuc_templates)
Sections   → Page sections with logic (nuc_sections)
Pages      → Full pages with API calls and store access (nuc_pages)

Bosons – The Invisible Foundation

Bosons are the smallest, indivisible units of reusable logic. They don’t render anything but form the foundation for all components:

// types/interfaces.ts
export interface ButtonInterface {
  label?: string
  variant?: 'primary' | 'secondary' | 'danger'
  disabled?: boolean
}

// utils/format_date.ts
export function formatDate(date: Date): string {
  return new Intl.DateTimeFormat('en-US').format(date)
}

// constants/breakpoints.ts
export const BREAKPOINTS = {
  mobile: 768,
  tablet: 1024,
  desktop: 1440,
} as const

Atoms – Basic Visual Elements

Atoms are the smallest UI components that can’t be broken down further without losing meaning. Examples: Button, Input, Icon, Label, Badge, Checkbox, Avatar.

Allowed logic:

Handle click/focus/hover events
Manage internal state (e.g., input value)
Conditional styling based on props
Emit events to parent

<template>
  <button :class="[$style['ad-button'], variant && $style[variant]]" :disabled="disabled" @click="$emit('click', $event)">
    <slot />
  </button>
</template>

<script setup lang="ts">
import type { ButtonInterface } from './types'
defineProps<ButtonInterface>()
defineEmits<{ click: [event: MouseEvent] }>()
</script>

Molecules – Simple Combinations

Molecules combine atoms into functional units while maintaining simplicity. Examples: FloatLabel, Anchor, Tile.

Allowed logic:

Coordinate child atom states
Simple computed values
Local validation (format only, no business rules)

Organisms – Complex Sections

Organisms are composed of molecules, atoms, or other organisms. They are still purely presentational. Examples: DataTable, Dialog, Menu, Card.

Allowed logic:

Render data passed via props
Local filtering/sorting of provided data
Manage open/close states
Emit user interaction events

Not allowed: API calls or store access.

Templates, Sections, and Pages

Templates (nuc_templates) – reusable layouts for cards, forms, modals; business logic allowed
Sections (nuc_sections) – page blocks combining templates and organisms with layout and data logic
Pages (nuc_pages) – full pages connecting UI components with stores and API calls

Best Practices

Keep components clean – predictable outputs, no side effects
Props down, events up – parent handles business logic
Single responsibility – each component does one thing well
Use TypeScript interfaces – type-safe props and data

Atomic Design – czy warto używać go do budowy skalowalnych UI?

Nucleify — Sat, 24 Jan 2026 10:10:57 +0000

Czym jest Atomic Design?

Atomic Design, stworzony przez Brada Frosta, dzieli interfejsy użytkownika na fundamentalne bloki budulcowe. Zainspirowany chemią, organizuje komponenty w hierarchię od najmniejszych elementów do pełnych stron.

Kluczowe zalety:

Spójność – komponenty wielokrotnego użytku zapewniają jednolity wygląd
Łatwość utrzymania – zmiany propagują się automatycznie w całym systemie
Skalowalność – łatwe rozszerzanie funkcjonalności bez łamania istniejących komponentów
Współpraca – przejrzysta struktura usprawnia pracę zespołową

Główna zasada: Brak logiki biznesowej

Komponenty Atomic Design nie powinny zawierać logiki biznesowej. Komponenty obsługują tylko funkcjonalność związaną z ich zachowaniem UI:

✅ Dozwolone	❌ Niedozwolone
Walidacja wejścia (format, długość)	Zakodowane na stałe wywołania API
Animacje i przejścia	Bezpośrednie pobieranie danych
Lokalny stan komponentu	Mutacje store'a
Emitowanie zdarzeń	Zakodowane na stałe URL-e lub endpointy
Renderowanie na podstawie propsów	Sprawdzanie autoryzacji lub logika domenowa
Funkcje dostępności	Obliczenia specyficzne dla domeny
Konfigurowalne callbacki przez propsy	Sztywne reguły biznesowe
Generyczne handlery zdarzeń	Zakodowana na stałe konfiguracja

Logika biznesowa należy do:

Store'ów (Pinia)
Composables
Serwisów

Rozszerzenia Nucleify

Nucleify rozszerza standardowy Atomic Design o moduły, w których logika biznesowa jest dozwolona:

Moduł	Przeznaczenie
`nuc_templates`	Szablony komponentów wielokrotnego użytku (karty, formularze, modale)
`nuc_sections`	Sekcje strony z logiką layoutu, obsługą danych i zachowaniem specyficznym dla sekcji
`nuc_pages`	Pełne komponenty stron z wywołaniami API, dostępem do store'a i regułami biznesowymi

Te moduły są oddzielone od nuxt/atomic/, aby utrzymać komponenty UI czystymi i wielokrotnego użytku.

Przegląd hierarchii

Nucleify wprowadza dodatkową warstwę Bosons dla typów i narzędzi.

Bosons     → Interfejsy, funkcje pomocnicze, stałe (niewidoczna warstwa)
Atoms      → Podstawowe elementy UI (Button, Input, Icon)
Molecules  → Proste kombinacje atomów (FloatLabel, Tile)
Organisms  → Złożone sekcje UI (DataTable, Dialog, Menu)
Templates  → Szablony komponentów wielokrotnego użytku (nuc_templates)
Sections   → Sekcje strony z logiką (nuc_sections)
Pages      → Pełne strony z wywołaniami API i dostępem do store'a (nuc_pages)

Bosons – Niewidoczny fundament

Bosony to najmniejsze, niepodzielne jednostki logiki wielokrotnego użytku. Nie renderują niczego, ale stanowią fundament dla wszystkich komponentów:

// types/interfaces.ts
export interface ButtonInterface {
  label?: string
  variant?: 'primary' | 'secondary' | 'danger'
  disabled?: boolean
}

// utils/format_date.ts
export function formatDate(date: Date): string {
  return new Intl.DateTimeFormat('en-US').format(date)
}

// constants/breakpoints.ts
export const BREAKPOINTS = {
  mobile: 768,
  tablet: 1024,
  desktop: 1440,
} as const

Atoms – Podstawowe elementy wizualne

Atomy to najmniejsze komponenty UI, których nie można dalej rozbić bez utraty znaczenia. Przykłady: Button, Input, Icon, Label, Badge, Checkbox, Avatar.

Dozwolona logika:

Obsługa zdarzeń click/focus/hover
Zarządzanie stanem wewnętrznym (np. wartość inputa)
Warunkowe stylowanie na podstawie propsów
Emitowanie zdarzeń do rodzica

<template>
  <button :class="[$style['ad-button'], variant && $style[variant]]" :disabled="disabled" @click="$emit('click', $event)">
    <slot />
  </button>
</template>

<script setup lang="ts">
import type { ButtonInterface } from './types'

defineProps<ButtonInterface>()
defineEmits<{ click: [event: MouseEvent] }>()
</script>

Molecules – Proste kombinacje

Molekuły łączą atomy w funkcjonalne jednostki, zachowując prostotę. Przykłady: FloatLabel, Anchor, Tile.

Dozwolona logika:

Koordynacja stanów atomów potomnych
Proste wartości obliczane
Lokalna walidacja (tylko format, bez reguł biznesowych)

Organisms – Złożone sekcje

Organizmy składają się z molekuł, atomów lub innych organizmów. Nadal są czysto prezentacyjne. Przykłady: DataTable, Dialog, Menu, Card.

Dozwolona logika:

Renderowanie danych przekazanych przez propsy
Lokalne filtrowanie/sortowanie dostarczonych danych
Zarządzanie stanami otwórz/zamknij
Emitowanie zdarzeń interakcji użytkownika

Niedozwolone: wywołania API lub dostęp do store'a.

Templates, Sections i Pages

Templates (nuc_templates) – szablony wielokrotnego użytku dla kart, formularzy, modali; logika biznesowa dozwolona
Sections (nuc_sections) – bloki strony łączące szablony i organizmy z logiką layoutu i danych
Pages (nuc_pages) – pełne strony łączące komponenty UI ze store'ami i wywołaniami API

Najlepsze praktyki

Utrzymuj komponenty czyste – przewidywalne wyjścia, brak efektów ubocznych
Propsy w dół, zdarzenia w górę – rodzic obsługuje logikę biznesową
Pojedyncza odpowiedzialność – każdy komponent robi jedną rzecz dobrze
Używaj interfejsów TypeScript – propsy i dane bezpieczne typowo

DEV Community: Nucleify

Dlaczego SSR nadal ma znaczenie (i kiedy faktycznie warto go używać)

1. Szybszy First Contentful Paint (FCP)

2. Lepsze Core Web Vitals (LCP, INP)

3. SEO bez hacków

4. Lepsze UX na wolnych lub niestabilnych połączeniach

5. Przewidywalne renderowanie i pobieranie danych

6. SSR + Prerendering = najlepsze z obu światów

Kiedy SSR może nie mieć sensu

Podsumowanie

Why SSR Still Matters (and When It’s Actually Worth Using)

1. Faster First Contentful Paint (FCP)

2. Better Core Web Vitals (LCP, INP)

3. SEO Without Hacks

4. Better UX on Slow or Unstable Connections

5. Predictable Rendering and Data Fetching

6. SSR + Prerendering = Best of Both Worlds

When SSR Might Not Be Worth It

Final Thoughts

Dlaczego warto używać plików index: Wzorzec Folder-as-Component

🎯 Problem: Chaos w nazewnictwie

Co jest nie tak?

💡 Rozwiązanie: Folder-as-Component

🔥 Przykłady z życia

Przykład React: components/button/

Przykład Vue: components/button/

Wspólne: _index.scss

Wspólne: types/interfaces.ts

🌳 Barrel Exports – agregacja modułów

Analogicznie dla SCSS:

📁 Zagnieżdżone komponenty

✅ Zalety wzorca Folder-as-Component

1. Intuicyjne importy

2. Enkapsulacja

3. Skalowalność

4. IDE-friendly

5. Konsystencja

6. Łatwe refaktorowanie

7. Tree-shaking friendly

8. Niezależność od frameworka

⚙️ Konwencje nazewnictwa plików

index.ts vs index.tsx vs index.vue

Konwencja _index.scss

🎨 Jak to wygląda w praktyce?

🚀 Quick Start

React

Vue

Import

📚 Podsumowanie

🔗 Linki

Why You Should Use index Files: The Folder-as-Component Pattern

🎯 The Problem: Naming Chaos

What's wrong with this?

💡 The Solution: Folder-as-Component

🔥 Real-World Examples

React Example: components/button/

Vue Example: components/button/

Shared: _index.scss

Shared: types/interfaces.ts

🌳 Barrel Exports – Module Aggregation

Same pattern for SCSS:

📁 Nested Components

✅ Benefits of the Folder-as-Component Pattern

1. Intuitive Imports

2. Encapsulation

3. Scalability

4. IDE-Friendly

5. Consistency

6. Easy Refactoring

7. Tree-shaking Friendly

8. Framework Agnostic

⚙️ File Naming Conventions

index.ts vs index.tsx vs index.vue

_index.scss Convention

🎨 What Does It Look Like in Practice?

🚀 Quick Start

React

Vue

Import

📚 Summary

Przykład React: `components/button/`

Przykład Vue: `components/button/`

Wspólne: `_index.scss`

Wspólne: `types/interfaces.ts`

`index.ts` vs `index.tsx` vs `index.vue`

Konwencja `_index.scss`

React Example: `components/button/`

Vue Example: `components/button/`

Shared: `_index.scss`

Shared: `types/interfaces.ts`

`index.ts` vs `index.tsx` vs `index.vue`

`_index.scss` Convention