Absolutely ✅ — here’s the complete, final README.md for your xianpwa package — fully formatted and ready to publish to npm (no missing sections, includes usage, installation, CLI info, license, and contribution details).

# ⚡ XianPWA

**XianPWA** is a lightweight Progressive Web App (PWA) generator for the **XianFires** Node.js MVC framework.  
It adds offline capabilities, caching, and manifest configuration automatically to your project’s `public` folder.

---

## 🚀 Features

✅ Automatically generates PWA structure (manifest, icons, service worker)  
✅ Enables offline support with intelligent caching  
✅ Injects required `<link>` and `<script>` tags in your XianFires views  
✅ Adds icons and manifest automatically  
✅ Works with **`npm link`** (local) or **npm install** (global)  
✅ Easy to extend or customize for your own framework

---

## 📦 Installation

### 🔹 Option 1 — Local Development (via `npm link`)

If you’re developing `xianpwa` locally:

```bash
# Inside your xianpwa folder
npm link

# Inside your xianfires project root
npm link xianpwa

Then run:

npx xianpwa

This command will automatically create:

• /public/service-worker.js

• /public/manifest.json

• /public/icons/ folder (with example icons)

• It will also modify:

  • views/header.xian → adds <link> tags before </head>
  • views/footer.xian → adds <script> tags before </body>

🔹 Option 2 — Install from npm (once published)

npm install xianpwa
npx xianpwa

That’s it — your XianFires app is now PWA-enabled! 🎉

🧠 What It Adds

📁 /public/service-worker.js

A robust service worker is created with offline caching logic:

const CACHE_NAME = "xianfires-cache-v1";
const ASSETS = [
  "/favicon.ico",
  "/manifest.json",
  "/css/style.css",
  "/js/app.js",
  "/icons/icon-192x192.png",
  "/icons/icon-512x512.png"
];

self.addEventListener("install", event => {
  console.log("✅ XianFire SW installing...");
  event.waitUntil(
    caches.open(CACHE_NAME)
      .then(async cache => {
        for (const url of ASSETS) {
          try {
            const response = await fetch(url);
            if (!response.ok) throw new Error(`${url} – ${response.status}`);
            await cache.put(url, response);
            console.log(`✅ Cached: ${url}`);
          } catch (err) {
            console.warn(`⚠️ Failed to cache ${url}:`, err);
          }
        }
      })
      .then(() => self.skipWaiting())
  );
});

self.addEventListener("activate", event => {
  console.log("🔥 SW activated");
  event.waitUntil(
    caches.keys().then(keys =>
      Promise.all(keys.map(key => {
        if (key !== CACHE_NAME) {
          console.log("🧹 Removing old cache:", key);
          return caches.delete(key);
        }
      }))
    )
  );
  self.clients.claim();
});

self.addEventListener("fetch", event => {
  event.respondWith(
    fetch(event.request)
      .then(response => {
        const clone = response.clone();
        caches.open(CACHE_NAME).then(cache => cache.put(event.request, clone));
        return response;
      })
      .catch(() => caches.match(event.request))
  );
});

📄 /public/manifest.json

An auto-generated web manifest ensures your app can be installed on mobile and desktop:

{
  "name": "XianFires PWA",
  "short_name": "XianFires",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#000000",
  "icons": [
    {
      "src": "/icons/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

🖼️ /public/icons/

Example icons (192x192 and 512x512) will be created automatically if not present. You can replace them with your actual app icons anytime.

🧩 Auto-Injection in Views

To complete the integration, XianPWA modifies your views/header.xian and views/footer.xian.

✨ In views/header.xian (before </head>):

<link rel="manifest" href="/manifest.json" />
<link rel="icon" href="/icons/icon-192x192.png" />

These lines tell browsers your app supports PWA and define the app icon.

✨ In views/footer.xian (before </body>):

<script>
if ("serviceWorker" in navigator) {
  window.addEventListener("load", () => {
    navigator.serviceWorker
      .register("/service-worker.js")
      .then(reg => console.log("✅ SW registered:", reg.scope))
      .catch(err => console.error("❌ SW registration failed:", err));
  });
}
</script>

This registers the service worker as soon as the app loads, ensuring caching works even offline.

🧱 Project Structure After Installation

xianfires/
 ├── public/
 │   ├── service-worker.js
 │   ├── manifest.json
 │   ├── icons/
 │   │   ├── icon-192x192.png
 │   │   └── icon-512x512.png
 ├── views/
 │   ├── header.xian   ← manifest & icon link added
 │   └── footer.xian   ← service worker registration added
 └── ...

🧰 Running the Generator Manually

If you ever need to reapply the configuration, simply run:

npx xianpwa

🔧 Customization

You can edit the generated files:

• Update /public/manifest.json to change app name, colors, or icons
• Modify /public/service-worker.js to implement custom caching strategies (e.g., network-first, cache-first, etc.)
• Replace icons with your real branding images

🧹 Uninstall

To remove XianPWA and its integrations:

npm uninstall xianpwa

You may also remove /public/service-worker.js and /manifest.json if no longer needed.

💡 Troubleshooting

| Issue | Cause | Solution | | ---------------------------------- | -------------------------------- | ----------------------------------------------------- | | Service worker not registering | Missing HTTPS or incorrect path | Ensure you’re serving over HTTPS or localhost | | Offline mode not working | Assets not cached or wrong paths | Verify all paths in ASSETS array exist in /public | | Manifest not detected | Missing <link rel="manifest"> | Ensure header.xian injection is correct |

📘 Example Preview

Once installed, your PWA will:

• Load instantly even when offline 🛰️
• Show your app icon and name when installed on a phone
• Cache important files for reuse
• Provide an installable experience

🧾 License

MIT License

Copyright (c) 2025 Christian Cabrera
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.

👨‍💻 Author

Christian I. Cabrera Instructor I — Mindoro State University 📍 Philippines 🌐 GitHub: @xianfire

🧩 Contributing

Contributions, issues, and feature requests are welcome! Feel free to fork the repository and submit a pull request.

🏁 Final Notes

• Works perfectly with XianFires Framework
• Adds offline-first functionality seamlessly

“Empowering Node.js apps with simplicity and speed — the XianFire way 🔥”