Documentation

# Clone the repository
git clone https://github.com/your-username/pwa-template-2025.git

# Navigate to project directory
cd pwa-template-2025

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

pwa-template-2025/
├── src/
│   ├── js/
│   │   ├── app.js                 # Main application entry
│   │   ├── state-manager.js       # State management
│   │   ├── navigation.js          # Navigation controller
│   │   ├── security.js            # Security utilities
│   │   └── ...                    # Other modules
│   ├── css/
│   │   ├── main.css              # Main styles
│   │   ├── design-tokens.css     # Design system tokens
│   │   └── view-transitions.css  # Transition styles
│   ├── index.html                # Main HTML template
│   ├── sw.js                     # Service worker
│   └── ...                       # Other HTML pages
├── public/
│   ├── manifest.json             # PWA manifest
│   └── icons/                    # App icons
├── webpack.config.js             # Webpack configuration
└── package.json                  # Dependencies

{
  "name": "Your App Name",
  "short_name": "YourApp",
  "description": "Your app description",
  "theme_color": "#3b82f6",
  "background_color": "#ffffff"
}

:root {
  --color-primary: #3b82f6;
  --color-secondary: #8b5cf6;
  --spacing-unit: 4px;
  --font-family-base: system-ui, sans-serif;
}

// 1. Registration (in app.js)
navigator.serviceWorker.register('/sw.js')

// 2. Installation (in sw.js)
self.addEventListener('install', (event) => {
  // Cache critical assets
  event.waitUntil(
    caches.open(CACHE_NAME).then(cache =>
      cache.addAll(urlsToCache)
    )
  );
});

// 3. Activation (in sw.js)
self.addEventListener('activate', (event) => {
  // Clean up old caches
  event.waitUntil(
    caches.keys().then(cacheNames =>
      Promise.all(
        cacheNames
          .filter(name => name !== CACHE_NAME)
          .map(name => caches.delete(name))
      )
    )
  );
});

// 4. Fetch Interception (in sw.js)
self.addEventListener('fetch', (event) => {
  // Apply caching strategy
  event.respondWith(
    caches.match(event.request)
      .then(response => response || fetch(event.request))
  );
});

// Example: Add custom routes to cache
const CACHE_NAME = 'my-app-v2';
const urlsToCache = [
  '/',
  '/index.html',
  '/about',
  '/features',
  '/css/main.css',
  '/js/app.bundle.js'
];

// Cache images separately with size limit
const IMAGE_CACHE = 'images-v1';
const MAX_IMAGE_CACHE_SIZE = 50; // 50 images max

// Queue an operation for when online
const queue = window.app.getModule('offlineQueue');
await queue.add({
  url: '/api/save',
  method: 'POST',
  data: { name: 'example' }
});

// Get state
const state = window.app.getState();

// Update state
state.user.name = 'John Doe';

// Subscribe to changes
window.app.state.subscribe((newState, oldState) => {
  console.log('State changed:', newState);
});

<a href="/about" data-transition="fade">About</a>
<a href="/contact" data-transition="slide">Contact</a>

// Webpack automatically splits vendor code
// app.bundle.js    - Your application code (~50KB)
// vendor.bundle.js - Third-party libraries (~150KB)

// Dynamic imports for route-based splitting
async function loadFeature() {
  const { FeatureModule } = await import('./feature.js');
  return new FeatureModule();
}

// This creates a separate chunk loaded on-demand

<!-- Preconnect to API domain -->
<link rel="preconnect" href="https://api.example.com">

<!-- Prefetch next likely page -->
<link rel="prefetch" href="/about">

<!-- Preload critical fonts -->
<link rel="preload" href="/fonts/main.woff2" as="font"
      type="font/woff2" crossorigin>

<!-- DNS prefetch for third-party resources -->
<link rel="dns-prefetch" href="https://analytics.example.com">

<!-- Native lazy loading -->
<img src="image.jpg" loading="lazy"
     width="800" height="600" alt="Description">

<!-- Responsive images with srcset -->
<img srcset="small.jpg 400w, medium.jpg 800w, large.jpg 1200w"
     sizes="(max-width: 600px) 400px, (max-width: 900px) 800px, 1200px"
     src="medium.jpg" alt="Description">

<!-- Modern formats with fallback -->
<picture>
  <source srcset="image.webp" type="image/webp">
  <source srcset="image.jpg" type="image/jpeg">
  <img src="image.jpg" alt="Description">
</picture>

// Automatically prefetch links user hovers over
// Configured in speculation-rules.js
{
  "prerender": [
    {"source": "list", "urls": ["/about", "/features"]}
  ],
  "prefetch": [
    {"source": "document", "where": {"href_matches": "/*"}}
  ]
}

// RUM collector tracks:
// - Core Web Vitals (LCP, FID, CLS)
// - Navigation timing
// - Resource loading times
// - User interactions
// - Network conditions

// Access performance data
const rum = window.app.getModule('rum');
const metrics = rum.getMetrics();

<!-- Recommended CSP configuration -->
<meta http-equiv="Content-Security-Policy" content="
  default-src 'self';
  script-src 'self';
  style-src 'self' 'unsafe-inline';
  img-src 'self' data: https:;
  font-src 'self' data:;
  connect-src 'self' https://api.example.com;
  worker-src 'self';
  manifest-src 'self';
">

import { SecurityManager } from './js/security.js';

const security = new SecurityManager();

// Sanitize HTML to prevent XSS
const userInput = '<script>alert("xss")</script>';
const safe = security.sanitize(userInput);
// Result: &lt;script&gt;alert("xss")&lt;/script&gt;

// Validate and sanitize URLs
const url = security.sanitizeURL(userProvidedURL);

// Escape special characters for safe display
const escaped = security.escapeHTML(userContent);

// Good: Use StorageManager for non-sensitive data
const storage = window.app.getModule('storage');
await storage.set('preferences', { theme: 'dark' });

// Bad: Don't store sensitive data
// localStorage.setItem('password', 'secret123'); ❌

const api = window.app.getAPI();

// Automatically includes CSRF tokens
// Validates response content types
// Sanitizes responses before processing
const data = await api.get('/user/profile');

// Use proper authentication headers
api.setHeader('Authorization', `Bearer ${token}`);

// Create new module
class MyModule {
  constructor() {
    this.init();
  }

  init() {
    console.log('Module initialized');
  }
}

// Register in app.js
this.modules.myModule = new MyModule();

npm run build

// Access global app instance
window.app

// Core Methods
app.getState()           // Get current application state
app.getAPI()             // Get API adapter instance
app.getModule(name)      // Get registered module by name
app.toggleTheme()        // Toggle between dark/light mode
app.promptInstall()      // Show PWA install prompt

const state = window.app.getState();

// Read state
console.log(state.user.name);
console.log(state.app.theme);

// Update state (triggers observers)
state.user = { name: 'John', role: 'admin' };
state.app.isOnline = false;

// Subscribe to state changes
window.app.state.subscribe((newState, oldState) => {
  console.log('State changed:', newState);
});

// Get entire state object
const fullState = window.app.state.getState();

const api = window.app.getAPI();

// GET request
const user = await api.get('/users/123');

// POST request
const newUser = await api.post('/users', {
  name: 'Jane',
  email: '[email protected]'
});

// PUT request
const updated = await api.put('/users/123', { name: 'John Doe' });

// DELETE request
await api.delete('/users/123');

// Set custom headers
api.setHeader('Authorization', `Bearer ${token}`);

const storage = window.app.getModule('storage');

// LocalStorage operations
await storage.set('key', { data: 'value' });
const data = await storage.get('key');
await storage.remove('key');
await storage.clear();

// IndexedDB for larger data
await storage.setIDB('largeDataset', bigArray);
const bigData = await storage.getIDB('largeDataset');

const queue = window.app.getModule('offlineQueue');

// Add request to queue
await queue.add({
  url: '/api/save',
  method: 'POST',
  data: { title: 'Draft', content: '...' },
  priority: 1  // Higher = more important
});

// Check queue status
const pending = queue.getPending();
console.log(`${pending.length} requests queued`);

// Queue automatically syncs when online
// Manual sync if needed
await queue.sync();

const a11y = window.app.getModule('accessibility');

// Announce to screen readers
a11y.announce('Form submitted successfully');

// Focus management
a11y.focusElement(document.querySelector('#result'));
a11y.trapFocus(modalElement);
a11y.releaseFocus();

// Keyboard navigation
a11y.enableKeyboardShortcuts({
  'Ctrl+K': () => openSearch(),
  'Escape': () => closeModal()
});

const media = window.app.getModule('media');

// Initialize lazy loading on images
media.lazyLoad('.lazy-image');

// Dynamically add responsive image
const img = media.createResponsiveImage({
  src: 'image.jpg',
  srcset: 'small.jpg 400w, large.jpg 800w',
  alt: 'Description',
  loading: 'lazy'
});

const analytics = window.app.getModule('analytics');

// Track page view (only if user consented)
analytics.track('page_view', {
  url: window.location.pathname,
  referrer: document.referrer
});

// Track custom event
analytics.track('button_click', {
  buttonId: 'signup',
  location: 'header'
});

// Get analytics status
console.log(analytics.isEnabled()); // false if no consent

const vt = window.app.getModule('viewTransitions');

// Transitions automatically work on links with data-transition
// <a href="/page" data-transition="fade">Link</a>

// Programmatic transition
await vt.transition(() => {
  // Update DOM here
  document.querySelector('#content').innerHTML = newContent;
}, 'slide');

const rum = window.app.getModule('rum');

// Get all collected metrics
const metrics = rum.getMetrics();

// Core Web Vitals
console.log('LCP:', metrics.lcp);  // Largest Contentful Paint
console.log('FID:', metrics.fid);  // First Input Delay
console.log('CLS:', metrics.cls);  // Cumulative Layout Shift

// Navigation timing
console.log('DOM Load:', metrics.domContentLoaded);
console.log('Page Load:', metrics.loadComplete);

const errors = window.app.getModule('errorBoundary');

// Errors are automatically caught and logged
// Access error history
const recentErrors = errors.getErrors();

// Custom error handler
errors.onError((error, errorInfo) => {
  // Send to error tracking service
  console.error('App error:', error);
});