🚀 XUI Framework

XUI is a lightweight JavaScript frontend framework generator built with:

• ⚡ Vite
• 🎨 TailwindCSS
• 🔥 Firebase (Auth + Firestore + Messaging)
• 📱 Progressive Web App (PWA)
• 🌐 Offline-first Service Worker
• 🔐 Google Authentication
• 📡 Real-time CRUD
• 📲 Push Notifications
• 📊 Charts
• 🧩 Modular Architecture

Designed for students learning:

• SPA Architecture
• Firebase Integration
• PWA Development
• Real-time Applications
• IoT + Web Integration

📦 Installation

Install globally:

npm install -g xui

Create new project:

xui my-app
cd my-app
npm install
npm run xui

Open in browser:

http://localhost:5173

📁 Project Structure

my-app/
│
├── public/
│   ├── manifest.json
│   └── icons/
│
├── src/
│   ├── app.js
│   ├── router.js
│   ├── styles.css
│   │
│   ├── components/
│   │   ├── Layout.js
│   │   └── Navbar.js
│   │
│   ├── pages/
│   │   ├── Home.js
│   │   ├── Login.js
│   │   └── Crud.js
│   │
│   └── firebase/
│       ├── config.js
│       ├── auth.js
│       ├── db.js
│       └── crudService.js
│
├── sw.js
├── tailwind.config.js
├── vite.config.js
└── package.json

🧠 Core Concepts

XUI follows:

• Component-based architecture
• Hash-based routing
• Layout wrapper system
• Modular Firebase services
• Offline-first PWA structure

🛠 Available Commands

Create Project

xui <project-name>

Add Modules

xui add layout
xui add router
xui add g-auth
xui add crud
xui add charts
xui add push
xui add roles
xui add offline
xui add iot-dashboard
xui add esp32

Doctor (Project Validator)

xui doctor

Deploy to Firebase Hosting

xui deploy firebase

🔐 Google Authentication

After running:

xui add g-auth

Enable Google Provider in Firebase Console:

Authentication → Sign-in method → Google → Enable

Open:

#/login

The login page automatically:

• Hides Sign In when logged in
• Hides Logout when not logged in
• Displays user email

🔄 CRUD (Real-time Firestore)

Add CRUD module:

xui add crud

Open:

#/crud

Features:

• Create
• Read (Realtime)
• Update
• Delete
• Server timestamp
• Offline sync support

Example Service:

createItem("xui-items", { name: "Sample" });

🌐 Offline Mode

Enable Firestore offline persistence:

xui add offline

Service worker handles:

• App shell caching
• Offline navigation fallback
• Static asset caching

To test:

1. Open DevTools
2. Application → Service Workers
3. Toggle "Offline"
4. Refresh page

📱 PWA Installation

XUI includes:

• Manifest
• Service worker
• Install prompt support

To install:

1. Run production build:

   npm run build
   npm run preview

2. Open in Chrome
3. Click Install App

📊 Charts

xui add charts
npm install chart.js

Example:

new Chart(document.getElementById("chart"), {
  type: "line",
  data: {
    labels: ["Jan", "Feb"],
    datasets: [{ label: "Sales", data: [10, 20] }]
  }
});

📡 Push Notifications

xui add push

Then:

1. Enable Cloud Messaging in Firebase
2. Generate VAPID key
3. Replace YOUR_PUBLIC_VAPID_KEY

🔒 Roles (Access Control)

xui add roles

Usage:

requireRole("admin", () => {
  console.log("Access granted");
});

📡 IoT Dashboard

xui add iot-dashboard

Listens to Firestore collection:

iot-data

Example document:

{
  "temperature": 25,
  "humidity": 70
}

Useful for ESP32 → Firebase integration.

🔥 Firebase Deployment

Run:

npm run build
xui deploy firebase
firebase login
firebase deploy

🎓 Educational Goals

Students will learn:

• SPA routing
• Modular JS architecture
• Firebase Auth
• Firestore real-time database
• Offline-first development
• Service Workers
• PWA installation
• Cloud deployment
• IoT + Web integration

🏗 Recommended Learning Path

1. Create project
2. Add layout + router
3. Add Google Auth
4. Protect routes
5. Add CRUD
6. Enable offline mode
7. Convert to PWA
8. Deploy to Firebase

🧪 Sample Navigation

#/           → Home
#/login      → Google Login
#/crud       → CRUD Page
#/dashboard  → IoT Dashboard

🚀 XUI Philosophy

Lightweight. Educational. Real-world ready. Offline-first. Firebase-native.

👨‍🏫 For Instructors

XUI is ideal for courses in:

• Web Development
• IoT Systems
• Mobile & PWA Development
• Cloud Integration
• Event-Driven Programming

📄 License

MIT License Copyright (c) 2025 Christian I. Cabrera || XUI Framework Mindoro State University - Philippines Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

⭐ Contributing

Pull requests are welcome.

🎉 Built for Learning

XUI is designed to help students move from:

"Hello World"
to
"Production-ready PWA with Firebase + IoT"