Nucleify

Posted on Feb 3

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

#webdev #nuxt #typescript #vue

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 🚀

Top comments (3)

Brooks Rockett • Feb 3

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 • Feb 3

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.

Brooks Rockett • Feb 5

Makes sense! Thanks for sharing!