PWA and Offline Behavior

What makes this a PWA

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 in next.config.js.

Important: Offline Support Only Works in Production

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:

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:

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.