react-material-vscode-icons/README.md

React components for VSCode Material Icon Theme - file and folder icons for your React applications

# React Material VSCode Icons

A comprehensive React component library that brings the beautiful VSCode Material Icon Theme to your React applications. Get file and folder icons that match the popular VSCode extension.

## Features

- 🎨 **1000+ Icons** - Complete icon set from VSCode Material Icon Theme
- ⚛️ **React Components** - TypeScript-first React components
- 🎯 **Smart Detection** - Automatic icon selection based on file names and extensions
- 📁 **Folder Icons** - Special folder icons for common directory names
- 🔧 **Customizable** - Easy styling with className and size props
- 📦 **Tree Shakable** - Import only what you need
- 🎨 **CSS Framework Agnostic** - Works with Tailwind, styled-components, CSS modules, etc.

## Installation

```bash
npm install react-material-vscode-icons
# or
yarn add react-material-vscode-icons
# or
pnpm add react-material-vscode-icons
```

## Quick Start

### Basic Usage

```tsx
import { FileIcon } from 'react-material-vscode-icons'

function FileExplorer() {
  return (
    <div>
      <FileIcon fileName="package.json" size={24} />
      <FileIcon fileName="src" isFolder size={24} />
      <FileIcon fileName="components" isFolder isExpanded size={24} />
      <FileIcon fileName="App.tsx" size={24} />
      <FileIcon fileName="styles.css" size={24} />
    </div>
  )
}
```

### Using Helper Functions

```tsx
import { getFileIcon, getFolderIcon } from 'react-material-vscode-icons'
import { Javascript } from 'react-material-vscode-icons/icons'

function CustomComponent() {
  const iconName = getFileIcon('script.js') // Returns 'Javascript'
  const folderIconName = getFolderIcon('src', false) // Returns 'FolderSrc'
  
  return (
    <div>
      <Javascript size={20} className="text-blue-500" />
      Icon for script.js: {iconName}
    </div>
  )
}
```

### Direct Icon Import

```tsx
import { 
  Javascript, 
  Typescript, 
  ReactIcon, 
  FolderSrc, 
  FolderComponents 
} from 'react-material-vscode-icons/icons'

function IconShowcase() {
  return (
    <div className="flex gap-4">
      <Javascript size={32} className="text-yellow-400" />
      <Typescript size={32} className="text-blue-500" />
      <ReactIcon size={32} className="text-cyan-400" />
      <FolderSrc size={32} className="text-blue-600" />
      <FolderComponents size={32} className="text-purple-600" />
    </div>
  )
}
```

## API Reference

### FileIcon Component

The main component for displaying file and folder icons.

```tsx
interface FileIconProps {
  fileName: string      // File or folder name
  isFolder?: boolean    // Whether this is a folder
  isExpanded?: boolean  // Whether folder is expanded (for folder icons)
  className?: string    // Additional CSS classes
  size?: number        // Icon size in pixels (default: 16)
}
```

### Helper Functions

#### `getFileIcon(fileName: string): string`

Returns the appropriate icon name for a given file name.

```tsx
getFileIcon('package.json')     // 'Npm'
getFileIcon('App.tsx')          // 'ReactIcon'
getFileIcon('styles.css')       // 'Css'
getFileIcon('README.md')        // 'Readme'
```

#### `getFolderIcon(folderName: string, isExpanded?: boolean): string`

Returns the appropriate icon name for a given folder name.

```tsx
getFolderIcon('src')            // 'FolderSrc'
getFolderIcon('components')     // 'FolderComponents'
getFolderIcon('node_modules')   // 'FolderNode'
getFolderIcon('src', true)      // 'FolderSrcOpen' (if available)
```

## Supported File Types

The library automatically detects icons for hundreds of file types and names:

### Programming Languages
- JavaScript (`.js`, `.jsx`, `.mjs`, `.cjs`)
- TypeScript (`.ts`, `.tsx`)
- Python (`.py`, `.pyw`, `.pyx`)
- Java (`.java`)
- C/C++ (`.c`, `.cpp`, `.h`, `.hpp`)
- Go (`.go`)
- Rust (`.rs`)
- PHP (`.php`)
- Ruby (`.rb`)
- And many more...

### Frameworks & Libraries
- React (`.jsx`, `.tsx`)
- Vue (`.vue`)
- Angular (`.component.ts`, `.service.ts`)
- Svelte (`.svelte`)
- Astro (`.astro`)

### Configuration Files
- `package.json`, `yarn.lock`, `pnpm-lock.yaml`
- `tsconfig.json`, `webpack.config.js`, `vite.config.ts`
- `.eslintrc.js`, `.prettierrc`, `babel.config.js`
- `Dockerfile`, `docker-compose.yml`
- `.gitignore`, `.env` files

### Special Folders
- `src`, `lib` → Source folder icon
- `test`, `tests`, `__tests__` → Test folder icon
- `docs`, `documentation` → Documentation folder icon
- `components` → Components folder icon
- `assets`, `static`, `public` → Assets folder icon
- `node_modules` → Node modules folder icon

## Styling

### With Tailwind CSS

```tsx
<FileIcon 
  fileName="App.tsx" 
  className="text-blue-500 hover:text-blue-700 transition-colors" 
  size={24} 
/>
```

### With CSS Modules

```tsx
import styles from './FileTree.module.css'

<FileIcon 
  fileName="package.json" 
  className={styles.fileIcon} 
  size={20} 
/>
```

### With styled-components

```tsx
import styled from 'styled-components'
import { FileIcon } from 'react-material-vscode-icons'

const StyledFileIcon = styled(FileIcon)`
  color: #3b82f6;
  transition: color 0.2s;
  
  &:hover {
    color: #1d4ed8;
  }
`
```

## Advanced Usage

### Building a File Tree

```tsx
import { FileIcon } from 'react-material-vscode-icons'

interface FileNode {
  name: string
  isFolder: boolean
  isExpanded?: boolean
  children?: FileNode[]
}

function FileTree({ nodes }: { nodes: FileNode[] }) {
  return (
    <ul className="space-y-1">
      {nodes.map((node, index) => (
        <li key={index} className="flex items-center gap-2">
          <FileIcon
            fileName={node.name}
            isFolder={node.isFolder}
            isExpanded={node.isExpanded}
            size={16}
          />
          <span>{node.name}</span>
          {node.children && node.isExpanded && (
            <FileTree nodes={node.children} />
          )}
        </li>
      ))}
    </ul>
  )
}
```

### Custom Icon Mapping

```tsx
import { fileIconMapping } from 'react-material-vscode-icons'

// Extend or modify the default mapping
const customMapping = {
  ...fileIconMapping,
  fileExtensions: {
    ...fileIconMapping.fileExtensions,
    'myext': 'custom-icon-name'
  }
}
```

## Generating Icons

This library includes a generator script to update icons from the VSCode Material Icon Theme repository:

```bash
npm run generate
```

This will:
1. Clone the latest VSCode Material Icon Theme
2. Generate React components for all SVG icons
3. Update the file mapping configuration
4. Clean up temporary files

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

MIT License - see the [LICENSE](LICENSE) file for details.

## Credits

- Icons from [VSCode Material Icon Theme](https://github.com/material-extensions/vscode-material-icon-theme)
- Built with [tsup](https://tsup.egoist.dev/) for fast TypeScript compilation

## Changelog

### 0.1.0
- Initial release
- 1000+ Material Design icons
- FileIcon component
- Smart file/folder detection
- TypeScript support
- Tree-shakable exports