# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.betterbugs.io/contributing-to-betterbugs/design-of-our-code/pwa-and-offline-behavior.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.