🎮 BloxMania - Digital Goods Marketplace

A high-performance, modern Shopify theme designed specifically for digital goods marketplaces, with a focus on gaming items, Roblox assets, and Fortnite cosmetics.

🚀 Quick Start

# Clone and setup
git clone https://github.com/kzndotsh/bloxmania.git
cd bloxmania
npm install

# Configure environment
npm run env:setup
# Edit .env with your Shopify store credentials

# Start development
npm run dev

📋 Table of Contents

✨ Features
📁 Project Structure
🔄 Development Workflow
🛠️ Build System
📜 Commands Reference
⚙️ Configuration
⚡ Performance
♿ Accessibility
🤝 Contributing
📚 Documentation
🛠️ Tech Stack

✨ Features

🎯 Core Features

Gaming-First Design: Optimized UI/UX for Roblox, Fortnite, and gaming communities
Digital Marketplace: Streamlined purchasing flow for virtual goods and game items
Performance Optimized: Advanced build system with incremental builds and asset optimization
Mobile-First Responsive: Seamless experience across all devices and screen sizes
Modern Tech Stack: Tailwind CSS 3.4+, ES6 modules, PostCSS pipeline

🛍️ E-commerce Features

Advanced Product Gallery: Image zoom, lightbox, and media optimization
Quick Purchase Flow: Streamlined add-to-cart and checkout experience
Intelligent Search: Real-time search with filtering and predictive results
Customer Dashboard: Complete account management and order history
Review System: Product ratings and customer feedback integration

🎨 Design System

Modular CSS Architecture: Organized component-based styling system
Design Tokens: Consistent colors, typography, and spacing variables
Theme Customization: Full Shopify theme editor integration
Animation System: Smooth CSS transitions and scroll-based animations
Dark Theme Ready: Built-in support for dark/light mode switching

🔧 Developer Experience

Hot Reload Development: Instant file changes with live browser updates
Custom Build System: Optimized bundling for JavaScript and CSS
Code Quality Tools: Prettier, Stylelint, and Theme Check integration
Unused Code Detection: Knip integration for dead code elimination
Comprehensive Documentation: Detailed guides and component documentation

📁 Project Structure

bloxmania/
├── 🛠️ Development Environment
│   ├── dev/                     # Source files for development
│   │   ├── js/                  # JavaScript modules
│   │   │   ├── core/           # Core utilities (api, dom, constants)
│   │   │   ├── features/       # Feature modules (cart, search, product)
│   │   │   ├── ui/             # UI components (header, modals, mobile-menu)
│   │   │   ├── helpers/        # Helper utilities (accessibility, keyboard)
│   │   │   └── system/         # System files (service-worker, analytics)
│   │   ├── css/                 # Modular CSS architecture
│   │   │   ├── main.css        # Main entry point with imports
│   │   │   ├── design-tokens.css # CSS custom properties
│   │   │   ├── base/           # Reset, typography, accessibility
│   │   │   ├── layout/         # Grid, header, footer, spacing
│   │   │   ├── components/     # Reusable UI components
│   │   │   ├── sections/       # Shopify section styles
│   │   │   └── utilities/      # Utility classes and responsive helpers
│   │   ├── images/             # Source images and assets
│   │   ├── sections/           # Shopify liquid sections
│   │   ├── snippets/           # Reusable liquid snippets
│   │   ├── templates/          # Shopify page templates
│   │   ├── layout/             # Theme layout files
│   │   ├── config/             # Shopify theme configuration
│   │   ├── locales/            # Translation files
│   │   └── utils/              # Build utilities and processors
│   │
├── 🚀 Production Output
│   ├── theme/                   # Compiled Shopify theme
│   │   ├── assets/             # Optimized CSS, JS, and images
│   │   ├── sections/           # Compiled Shopify sections
│   │   ├── snippets/           # Compiled snippets
│   │   ├── templates/          # Compiled templates
│   │   ├── layout/             # Theme layouts
│   │   ├── config/             # Theme configuration
│   │   └── locales/            # Localization files
│   │
├── 📚 Documentation & Configuration
│   ├── docs/                    # Comprehensive documentation
│   │   ├── GETTING_STARTED.md  # Setup and installation guide
│   │   ├── DEVELOPMENT.md      # Development workflow
│   │   ├── BUILD_SYSTEM.md     # Build system documentation
│   │   ├── PROJECT_STRUCTURE.md # Architecture overview
│   │   └── sections/           # Section-specific documentation
│   │
├── 🔧 Configuration Files
│   ├── build.js                # Custom build system
│   ├── package.json            # Project dependencies and scripts
│   ├── tailwind.config.js      # Tailwind CSS configuration
│   ├── postcss.config.js       # PostCSS processing pipeline
│   ├── nodemon.json            # File watching configuration
│   ├── knip.ts                 # Unused code detection
│   └── .env                    # Environment variables (local)

🔄 Development Workflow

1. Initial Setup

# Install dependencies
npm install

# Setup environment file
npm run env:setup

# Edit .env with your Shopify store details
SHOPIFY_STORE=your-store.myshopify.com
SHOPIFY_THEME_ID=auto

2. Development Process

# Start development server with hot reload
npm run dev

# The build system automatically:
# - Watches for file changes in dev/
# - Compiles CSS with Tailwind and PostCSS
# - Bundles JavaScript modules
# - Copies assets and liquid files to theme/
# - Syncs changes with Shopify store

Key Development Rules:

✅ Always edit files in dev/ directory
❌ Never edit files in theme/ directory (auto-generated)
🔄 Changes in dev/ trigger automatic rebuilds
📱 Test on multiple devices and browsers

3. Production Deployment

# Build optimized theme
npm run build

# Deploy to Shopify
npm run push

# Create theme package
npm run package

🛠️ Build System

JavaScript Processing

Custom Bundler: dev/utils/bundler.js
Source: Modular ES6 files in dev/js/
Output: Single optimized main.js in theme/assets/
Features: Tree shaking, minification, source maps (dev mode)

CSS Processing Pipeline

Tailwind CSS → PostCSS → Autoprefixer → CSSnano (prod) → theme/assets/main.css

Framework: Tailwind CSS 3.4+ with custom configuration
Architecture: Modular CSS with design tokens and component-based organization
Optimization: Unused CSS purging, minification, and duplicate removal

Asset Optimization

Images: Automatic compression and format optimization
Fonts: Preload with font-display: swap for performance
Critical Resources: Optimized loading order and lazy loading

File Watching & Live Reload

Nodemon: Watches dev/ directory for changes
Debounced Builds: Prevents excessive rebuilds during rapid changes
Shopify CLI: Provides live reload functionality during development

📜 Commands Reference

🚀 Development Commands

Command	Description	Live Reload
`npm run dev`	Start development server	Hot reload (default)
`npm run dev:hot`	CSS and sections only	Hot reload
`npm run dev:full`	Full page refresh	Full page
`npm run dev:off`	No live reload	Manual refresh
`npm run dev:open`	Auto-open browser	Hot reload
`npm run dev:watch`	File watching only	No Shopify sync

🔨 Build Commands

Command	Description	Mode
`npm run build`	Production build	Minified, optimized
`npm run build:dev`	Development build	Source maps, faster
`npm run build:css:dev`	CSS only (dev)	Readable output
`npm run build:css:prod`	CSS only (prod)	Minified, purged
`npm run build:js:dev`	JavaScript only (dev)	Source maps
`npm run build:js:prod`	JavaScript only (prod)	Minified, tree-shaken

📦 Deployment Commands

Command	Description
`npm run push`	Build and deploy to Shopify
`npm run pull`	Download theme from Shopify
`npm run package`	Create .zip theme package

✅ Quality & Maintenance

Command	Description
`npm run check`	Shopify theme validation
`npm run check:fix`	Auto-fix theme issues
`npm run format`	Format code with Prettier
`npm run lint:css`	Lint CSS with Stylelint
`npm run lint:css:fix`	Auto-fix CSS issues
`npm run knip`	Find unused code

🧹 Cleanup Commands

Command	Description
`npm run clean`	Remove build/ and theme/
`npm run clean:build`	Remove build/ only
`npm run clean:theme`	Remove theme/ only

⚙️ Setup Commands

Command	Description
`npm run setup`	Install all dependencies
`npm run env:setup`	Create .env from template
`npm run backfill`	Guide for merchant changes

⚙️ Configuration

Environment Setup

Create .env file with your Shopify store details:

# Copy template
npm run env:setup

# Required variables
SHOPIFY_STORE=your-store.myshopify.com
SHOPIFY_PASSWORD=your-private-app-password
SHOPIFY_THEME_ID=auto

Build Configuration Files

File	Purpose
`build.js`	Custom build system with incremental builds
`tailwind.config.js`	Tailwind CSS configuration and custom theme
`postcss.config.js`	PostCSS plugins and optimization
`nodemon.json`	File watching and build triggering
`knip.ts`	Unused code detection configuration

Code Quality Configuration

File	Purpose
`.prettierrc`	Code formatting rules
`.stylelintrc.json`	CSS linting and style rules
`.theme-check.yml`	Shopify theme validation

Tailwind CSS Theme

Custom color palette and design tokens:

Primary: #ffd800 (Gaming Yellow)
Secondary: #4791f0 (Gaming Blue)  
Background: #1d1e26 (Dark Theme)
Accent: #59bab9 (Teal)

⚡ Performance

Build Performance

Incremental Builds: Only rebuilds changed files
Fast Development: ~200ms rebuild times
Debounced Compilation: Prevents excessive rebuilds
Parallel Processing: CSS and JS built concurrently

Runtime Performance

Core Web Vitals Optimized: LCP, FID, and CLS optimization
Lazy Loading: Images and non-critical resources
Critical CSS: Above-the-fold styles inlined
Tree Shaking: Unused JavaScript eliminated
Asset Optimization: Minified CSS/JS, optimized images

Caching Strategy

Browser Caching: Proper cache headers for static assets
Shopify CDN: Global content delivery network
Service Worker: Offline functionality and asset caching

♿ Accessibility

WCAG 2.1 AA Compliance

Semantic HTML: Proper heading hierarchy and landmark elements
ARIA Support: Screen reader compatibility and dynamic content announcements
Keyboard Navigation: Full tab-based navigation support
Color Contrast: Minimum 4.5:1 ratio for all text elements
Focus Management: Visible focus indicators and logical tab order

Inclusive Design Features

Skip Links: Quick navigation for keyboard users
Alt Text: Descriptive image alternatives
Form Labels: Proper labeling and error handling
Responsive Design: Usable on all devices and orientations

🤝 Contributing

Development Guidelines

Source Control: Only edit files in dev/ directory
Modular Architecture: Follow established CSS and JavaScript patterns
Accessibility First: Test with keyboard navigation and screen readers
Code Quality: Use Prettier and Stylelint before committing
Documentation: Update relevant docs when adding features

Code Standards

CSS: Alphabetical property ordering, modular architecture
JavaScript: ES6+, meaningful naming, proper error handling
Liquid: Semantic HTML, proper indentation, accessibility attributes
Performance: Optimize images, minimize HTTP requests, use lazy loading

Testing Checklist

✅ Cross-browser compatibility (Chrome, Firefox, Safari, Edge)
✅ Mobile responsiveness across screen sizes
✅ Accessibility with keyboard navigation and screen readers
✅ Performance monitoring with Lighthouse
✅ Shopify theme validation with npm run check

📚 Documentation

Core Documentation

docs/README.md - Documentation index and overview
docs/GETTING_STARTED.md - Complete setup guide
docs/DEVELOPMENT.md - Development workflow and best practices
docs/BUILD_SYSTEM.md - Build system architecture
docs/PROJECT_STRUCTURE.md - Detailed project organization

Component Documentation

docs/sections/README.md - Shopify sections overview
docs/snippets/README.md - Reusable snippets guide
docs/templates/README.md - Template system documentation

Style Guide

docs/style-guide/README.md - Design system and coding standards

🛠️ Tech Stack

Frontend Technologies

CSS Framework: Tailwind CSS 3.4+ with custom configuration
CSS Architecture: Modular CSS with design tokens and component organization
JavaScript: ES6+ modules with custom bundling system
Build System: Custom Node.js build pipeline with incremental compilation
Package Management: npm with lock file for dependency consistency

Shopify Integration

Shopify CLI: 3.82+ for theme development and deployment
Theme Check: Automated Shopify theme validation
Liquid Templates: Shopify's templating language for dynamic content
Section Groups: Modern Shopify 2.0 theme architecture

Development Tools

Code Formatting: Prettier with Liquid plugin
CSS Linting: Stylelint with Shopify-specific rules
PostCSS: CSS processing pipeline with autoprefixer and minification
File Watching: Nodemon for automatic rebuilds
Dead Code Detection: Knip for unused code identification

Performance Tools

Image Optimization: Sharp for image processing and compression
CSS Optimization: CSSnano for production minification
JavaScript Optimization: Terser for minification and tree shaking
Bundle Analysis: Custom bundler with dependency tracking

📄 License

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

🆘 Support & Resources

Issues: GitHub Issues
Documentation: Complete Documentation
Development Guide: Development Workflow
Shopify Resources: Shopify Theme Development

Built with ❤️ for the gaming community

BloxMania Theme v1.0.0 - Empowering digital goods marketplaces with modern web technology

Name		Name	Last commit message	Last commit date
Latest commit History 294 Commits
.cursor/rules		.cursor/rules
.kiro		.kiro
.vscode		.vscode
dev		dev
docs		docs
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
.stylelintignore		.stylelintignore
.stylelintrc.json		.stylelintrc.json
.theme-check.yml		.theme-check.yml
README.md		README.md
build.js		build.js
dev-script.js		dev-script.js
knip.ts		knip.ts
nodemon.json		nodemon.json
nodemon.stable.json		nodemon.stable.json
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js

kzndotsh/bloxmania

Folders and files

Latest commit

History

Repository files navigation