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

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?

1. Flat structure – everything dumped in one folder
2. Redundant prefixes – Button, Button, Button...
3. Poor encapsulation – hard to tell what belongs to what
4. Scaling issues – at 50+ components it becomes a nightmare
5. 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 🚀

Comments

[Brooks Rockett]

This seems like a cool approach, and I recognize the benefits especially for refactoring and scaling.

I just have this bad habit of always wanting to "CTRL+P" to find a file by name and it's bad enough with a number of index.ts files in different subfolders of /pages - this seems like it would turn that up a few notches.

[Nucleify]

It's not that big problem in my opinion, when you write "button" or other component it shows you files based on folder names. So it's really just matter of habits.