--- name: server-app-shell description: App Shell architecture — the cached HTML/CSS/JS skeleton (header, nav, footer) served instantly via Service Worker while dynamic content streams in. Use when building PWAs, wiring service-worker caches, inlining critical CSS, or adding offline fallbacks and skeleton loading states. when_to_use: Designing the root layout and service-worker cache strategy for a PWA; separating static shell from dynamic content; adding offline fallback pages; optimising first-paint with inlined critical CSS. paths: - "**/shell/**/*.{jsx,tsx,js,ts}" - "**/layout/**/*.{jsx,tsx}" - "**/app/**/*.{jsx,tsx}" --- # App Shell ## What is an App Shell? App Shell is the minimal HTML/CSS/JS for your UI framework—header, navigation, footer—cached by Service Worker for instant loading (<200ms). Dynamic content loads separately. Core to PWA architecture. ## Key Principles 1. **Separate Static Shell from Dynamic Content**: Shell (nav, layout, critical CSS) cached forever. Content fetched per request via API. 2. **Service Worker Caching**: First visit caches shell assets. Subsequent loads serve from cache instantly, fetch only data. 3. **Instant Perceived Load**: Show shell immediately with skeleton content. Fill with data as it arrives. ## Best Practices ✅ **DO**: - Cache shell assets with Service Worker - Inline critical CSS in `` - Use skeleton screens while content loads - Version shell assets for cache invalidation - Prioritize above-fold content ❌ **DON'T**: - Include personalized content in shell - Skip Service Worker registration - Forget offline fallback page - Cache API responses with shell (different strategy) - Block render on non-critical resources ## Code Patterns ### App Shell Component ```jsx // AppShell.jsx const AppShell = ({ children }) => (
{/* Static - cached */} {/* Static - cached */}
}> {children} {/* Dynamic - loaded per route */}
); ``` ### Service Worker Caching ```javascript // sw.js const SHELL_CACHE = 'app-shell-v1'; const SHELL_ASSETS = [ '/', '/index.html', '/styles/main.css', '/scripts/app.js', '/images/logo.svg' ]; // Cache shell on install self.addEventListener('install', (event) => { event.waitUntil( caches.open(SHELL_CACHE).then(cache => cache.addAll(SHELL_ASSETS)) ); }); // Serve shell from cache self.addEventListener('fetch', (event) => { // Shell assets: cache-first if (SHELL_ASSETS.includes(new URL(event.request.url).pathname)) { event.respondWith( caches.match(event.request).then(response => response || fetch(event.request) ) ); } // API calls: network-first else if (event.request.url.includes('/api/')) { event.respondWith( fetch(event.request).catch(() => caches.match('/offline.html')) ); } }); ``` ### Critical CSS Inlining ```html
``` ### Offline Fallback ```jsx // OfflinePage.jsx - Cached for offline access const OfflinePage = () => (

You're Offline

Check your internet connection and try again.

); ``` ## Related Terminologies - **PWA** - App Shell is core PWA pattern - **Template** (UI) - Shell is the root template - **Skeleton** (UI) - Used in shell while loading - **Router** (Server) - Routes within shell ## Quality Gates - [ ] Shell cached by Service Worker - [ ] Critical CSS inlined - [ ] Skeleton screens for loading - [ ] Offline fallback page - [ ] Shell loads in <200ms - [ ] Assets versioned for cache invalidation **Source**: `/docs/server/app-shell.md`