# PWA and Offline Behavior

What is PWA Support?

This app is a Progressive Web App (PWA). Users can:

* Install it on their home screen (mobile or desktop)
* Use it fully offline
* Get faster load times due to service worker caching

PWA is configured using [next-pwa](https://github.com/shadowwalker/next-pwa) in [next.config.js](https://github.com/betterbugs/dev-tools/blob/main/next.config.js).

{% hint style="info" %}

#### Important: Offline Support Only Works in Production

{% endhint %}

**Offline support is ONLY active in production builds**, not in local development.

* **Local dev** (`npm run dev`): PWA disabled, no offline support
* **Production build** (`npm run build && npm start`): PWA enabled, offline works

This is by design:

```javascript
if (process.env.NEXT_ENV !== 'local') {
  const withPWA = require('next-pwa')({ ... });
  module.exports = withPWA(nextConfig);
}
```

### Why Offline Support Matters

Developers use these tools on flights, trains, or without stable internet. Since all our current tools process data locally (no API calls), they work fully offline.

### How It Works

**What gets cached:**

* JavaScript bundles
* CSS and images
* Fonts and icons
* Service worker (auto-generated at build time by next-pwa)

**Caching strategy:**

* All static assets are cached on first visit
* Updates are checked in the background
* Users get updates on their next visit
* Cache invalidation is handled automatically

### Testing Offline Support

Since offline only works in production builds, you must build and run production:

```bash
npm run build
npm start
```

Then test offline:

1. Open DevTools → Application → Service Workers
2. Check "Offline"
3. Reload the page
4. Your tool should work normally

### When Adding a New Tool

Test that your tool works offline:

1. Run the production build: `npm run build && npm start`
2. Open DevTools → Application → Service Workers
3. Enable "Offline" mode
4. Reload and verify the tool functions correctly

Since tools should only process local data (no API calls), they should work offline automatically.

### Guidelines for New Tools

#### Offline-Safe Tools (Recommended)

Most tools in this repo process data locally:

* Input from user → Process locally → Output result
* No network requests needed
* Works fully offline
* Best user experience

**Examples:** JSON formatter, base64 encoder, text converters, etc.

#### Building Tools with Network Features?

Network requests are fine, but make them **optional and documented**:

**If your tool uses APIs:**

* Make the feature gracefully degrade if API is unavailable
* Document which APIs are needed
* Show clear error messages if network is missing
* Provide a fallback or placeholder
* Example: If API key is missing, disable that feature but keep core tool working

**Examples:**

* Tools that fetch from public APIs (with fallback)
* Tools with AI features using user-provided API keys
* Tools that benefit from network but still work without it

#### The Only Hard Rule

**Never do this:**

* Require user login or authentication
* Store personal user data
* Collect user information

Everything else is negotiable. We want great tools, not perfection!

#### Best Practice

If unsure, ask us in your PR/GitHub discussion/Discord. We're here to help and want to say "yes" to good ideas.