ProxmoxVE_Scripts/frontend/README.md

Proxmox VE Helper-Scripts Frontend

🚀 Modern frontend for the Community-Scripts Proxmox VE Helper-Scripts repository

A comprehensive, user-friendly interface built with Next.js that provides access to 300+ automation scripts for Proxmox Virtual Environment management. This frontend serves as the official website for the Community-Scripts organization's Proxmox VE Helper-Scripts repository.

🌟 Features

Core Functionality

• 📜 Script Management: Browse, search, and filter 300+ Proxmox VE scripts
• 📱 Responsive Design: Mobile-first approach with modern UI/UX
• 🔍 Advanced Search: Fuzzy search with category filtering
• 📊 Analytics Integration: Built-in analytics for usage tracking
• 🌙 Dark/Light Mode: Theme switching with system preference detection
• ⚡ Performance Optimized: Static site generation for lightning-fast loading

Technical Features

• 🎨 Modern UI Components: Built with Radix UI and shadcn/ui
• 📈 Data Visualization: Charts and metrics using Chart.js
• 🔄 State Management: React Query for efficient data fetching
• 📝 Type Safety: Full TypeScript implementation
• 🚀 Static Export: Optimized for GitHub Pages deployment

🛠️ Tech Stack

Frontend Framework

• Next.js 15.2.4 - React framework with App Router
• React 19.0.0 - Latest React with concurrent features
• TypeScript 5.8.2 - Type-safe JavaScript

Styling & UI

• Tailwind CSS 3.4.17 - Utility-first CSS framework
• Radix UI - Unstyled, accessible UI components
• shadcn/ui - Re-usable components built on Radix UI
• Framer Motion - Animation library
• Lucide React - Icon library

Data & State Management

• TanStack Query 5.71.1 - Powerful data synchronization
• Zod 3.24.2 - TypeScript-first schema validation
• nuqs 2.4.1 - Type-safe search params state manager

Development Tools

• Vitest 3.1.1 - Fast unit testing framework
• React Testing Library - Simple testing utilities
• ESLint - Code linting and formatting
• Prettier - Code formatting

Additional Libraries

• Chart.js - Data visualization
• Fuse.js - Fuzzy search
• date-fns - Date utility library
• Next Themes - Theme management

🚀 Getting Started

Prerequisites

• Node.js 18+ (recommend using the latest LTS version)
• npm, yarn, pnpm, or bun package manager
• Git for version control

Installation

1. Clone the repository

   git clone https://github.com/community-scripts/ProxmoxVE.git
   cd ProxmoxVE/frontend
   

2. Install dependencies

   # Using npm
   npm install
   
   # Using yarn
   yarn install
   
   # Using pnpm
   pnpm install
   
   # Using bun
   bun install
   

3. Start the development server

   npm run dev
   # or
   yarn dev
   # or
   pnpm dev
   # or
   bun dev
   

4. Open your browser

   Navigate to http://localhost:3000 to see the application running.

Environment Configuration

The application uses the following environment variables:

• BASE_PATH: Set to "ProxmoxVE" for GitHub Pages deployment
• Analytics configuration is handled in src/config/siteConfig.tsx

🧪 Development

Available Scripts

# Development
npm run dev          # Start development server with Turbopack
npm run build        # Build for production
npm run start        # Start production server (after build)

# Code Quality
npm run lint         # Run ESLint
npm run typecheck    # Run TypeScript type checking
npm run format:write # Format code with Prettier
npm run format:check # Check code formatting

# Deployment
npm run deploy       # Build and deploy to GitHub Pages

Development Workflow

1. Feature Development

   • Create a new branch for your feature
   • Follow the established TypeScript and React patterns
   • Use the existing component library (shadcn/ui)
   • Ensure responsive design principles

2. Code Standards

   • Follow TypeScript strict mode
   • Use functional components with hooks
   • Implement proper error boundaries
   • Write descriptive variable and function names
   • Use early returns for better readability

3. Styling Guidelines

   • Use Tailwind CSS utility classes
   • Follow mobile-first responsive design
   • Implement dark/light mode considerations
   • Use CSS variables from the design system

4. Testing

   • Write unit tests for utility functions
   • Test React components with React Testing Library
   • Ensure accessibility standards are met
   • Run tests before committing

Component Development

The project uses a component-driven development approach:

// Example component structure
import { cn } from "@/lib/utils";
import { Button } from "@/components/ui/button";

interface ComponentProps {
  title: string;
  className?: string;
}

export const Component = ({ title, className }: ComponentProps) => {
  return (
    <div className={cn("default-classes", className)}>
      <Button>{title}</Button>
    </div>
  );
};

Configuration for Static Export

The application is configured for static export in next.config.mjs:

const nextConfig = {
  output: "export",
  basePath: `/ProxmoxVE`,
  images: {
    unoptimized: true // Required for static export
  }
};

🤝 Contributing

We welcome contributions from the community! Here's how you can help:

Getting Started

1. Fork the repository on GitHub
2. Clone your fork locally
3. Create a new branch for your feature or bugfix
4. Make your changes following our coding standards
5. Submit a pull request with a clear description

Contribution Guidelines

Code Style

• Follow the existing TypeScript and React patterns
• Use descriptive variable and function names
• Implement proper error handling
• Write self-documenting code with appropriate comments

Component Guidelines

• Use functional components with hooks
• Implement proper TypeScript types
• Follow accessibility best practices
• Ensure responsive design
• Use the existing design system components

Pull Request Process

1. Update documentation if needed
2. Update the README if you've added new features
3. Request review from maintainers

Areas for Contribution

• 🐛 Bug fixes: Report and fix issues
• ✨ New features: Enhance functionality
• 📚 Documentation: Improve guides and examples
• 🎨 UI/UX: Improve design and user experience
• ♿ Accessibility: Enhance accessibility features
• 🚀 Performance: Optimize loading and runtime performance

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• tteck - Original creator of the Proxmox VE Helper-Scripts
• Community-Scripts Organization - Maintaining and expanding the project
• Proxmox Community - For continuous feedback and support
• All Contributors - Thank you for your valuable contributions!

📚 Additional Resources

• Proxmox VE Documentation
• Community Scripts Repository
• Discord Community
• GitHub Discussions

🔗 Links

• 🌐 Live Website: https://community-scripts.github.io/ProxmoxVE/
• 💬 Discord Server: https://discord.gg/2wvnMDgdnU
• 📝 Change Log: https://github.com/community-scripts/ProxmoxVE/blob/main/CHANGELOG.md

---

Made with ❤️ by the Community-Scripts team and contributors