fix(website): broken doc links, WASM SW cache versioning (#398, #403)

[ajitpratap0]

Summary

Addresses issues #397, #398, #403. Issue #397 (soft 404) was investigated and confirmed not an issue — app/not-found.tsx in Next.js App Router automatically returns HTTP 404 for unmatched routes.

Changes

#398 — Broken .md relative links in docs content

Fixed relative .md file references in all 7 docs served by the website (files in docs/ at repo root). Replaced with correct website paths or GitHub URLs:

Old reference	New link
LINTING_RULES.md	/docs/linting-rules
LSP_GUIDE.md	/docs/lsp-guide
CONFIGURATION.md	/docs/configuration
GETTING_STARTED.md	/docs/getting-started
USAGE_GUIDE.md	/docs/usage-guide
CLI_GUIDE.md	/docs/cli-guide
API_REFERENCE.md	/docs/api-reference
MCP_GUIDE.md	/docs/mcp-guide
SQL_COMPATIBILITY.md	/docs/sql-compatibility
ERROR_CODES.md	/docs/error-codes
../examples/	GitHub URL
MIGRATION.md	GitHub URL
../CONTRIBUTING.md	GitHub URL

#403 — WASM service worker cache versioning

Updated website/public/wasm-sw.js (already registered via ServiceWorkerRegister.tsx):

• Versioned cache key: gosqlx-wasm-v2 (easy to bump on each WASM binary deploy)
• Added self.clients.claim() on activate so the new SW takes over existing clients immediately
• Scoped old cache cleanup to gosqlx-wasm-* prefix only (previously deleted all caches indiscriminately)
• Added response.ok guard before caching fetch responses to prevent caching error responses

Test plan

• Navigate to a docs page → click all cross-reference links → should not 404
• Load /playground → open DevTools → Application → Service Workers → confirm wasm-sw.js registered and gosqlx-wasm-v2 cache present
• Navigate to /this-does-not-exist → check Network tab → confirm 404 status code

Closes #397, #398, #403

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
gosqlx-website	Ready	Preview, Comment	Mar 19, 2026 3:46pm

[github-actions]

Claude finished @ajitpratap0's task —— View job

---

PR Review Complete ✅

Reviewing PR #415 for code quality, potential issues, performance, security, and test coverage.

Review Tasks

• Read and analyze all 8 changed files
• Review documentation link fixes for correctness
• Analyze WASM service worker changes for security and performance
• Check alignment with project standards
• Provide comprehensive feedback

📋 Overall Assessment: APPROVED ✅

This is a high-quality PR that addresses legitimate infrastructure issues with clean, well-thought-out solutions.

🔗 Documentation Link Fixes ✅

Issue #398: All broken .md relative links have been systematically fixed across 7 docs files.

Changes Made

• Internal doc links: Converted to website paths (e.g., LINTING_RULES.md → /docs/linting-rules)
• External repo links: Converted to GitHub URLs (e.g., ../CONTRIBUTING.md → full GitHub URL)
• Consistent format: All links now follow the /docs/{kebab-case} pattern

Quality Assessment

• ✅ Systematic: All 7 docs files updated consistently
• ✅ Correct patterns: Links follow established website routing
• ✅ No broken links: All new paths align with website structure
• ✅ Future-proof: Generic /docs/ paths that won't break with repo changes

⚡ WASM Service Worker Improvements ✅

Issue #403: Significant improvements to service worker cache management.

Key Improvements

1. Versioned Cache Strategy 🎯

const CACHE_VERSION = 'v2';
const CACHE_NAME = `gosqlx-wasm-${CACHE_VERSION}`;

• Previous: Hardcoded hash-based cache name
• New: Configurable version-based approach
• Benefit: Easy cache invalidation on WASM binary updates

2. Immediate Service Worker Activation 🚀

self.clients.claim();

• Added: Forces new SW to take control immediately
• Impact: Users get latest WASM binary without refresh

3. Scoped Cache Cleanup 🧹

.filter((name) => name.startsWith('gosqlx-wasm-') && name !== CACHE_NAME)

• Previous: Deleted ALL caches indiscriminately
• New: Only removes GoSQLX WASM caches
• Benefit: Won't interfere with other site caches

4. Response Validation 🛡️

if (response.ok) cache.put(event.request, response.clone());

• Added: Only caches successful responses (2xx status)
• Benefit: Prevents caching of error responses

Performance & Security Analysis

Performance Impact ⚡

• Positive: More efficient cache management
• Positive: Immediate SW activation reduces cache inconsistency
• Neutral: No performance regression expected

Security Assessment 🔒

• Secure: No security vulnerabilities introduced
• Improvement: Better error handling prevents bad response caching
• Best Practice: Scoped cache deletion follows SW best practices

🏗️ Code Quality Assessment

Strengths

• Consistent: All changes follow established patterns
• Well-documented: Clear variable naming and logical structure
• Production-ready: No console.log or debug code
• Standards-compliant: Follows modern Service Worker patterns

Minor Observations

• Documentation: All changes are properly documented in PR description
• Testing: Changes are low-risk infrastructure improvements
• Backwards compatible: No breaking changes to existing functionality

🎯 Project Standards Alignment ✅

Documentation Standards

• ✅ Links follow website routing conventions
• ✅ Consistent formatting across all files
• ✅ Proper markdown syntax maintained

Code Standards

• ✅ Clean, readable JavaScript
• ✅ Modern ES6+ syntax
• ✅ No linting issues observed
• ✅ Follows service worker best practices

🚀 Recommendations

Accept This PR ✅

1. Low Risk: Infrastructure-only changes with high benefit
2. High Quality: Well-executed fixes with attention to detail
3. Immediate Value: Fixes user-facing broken links
4. Performance Benefit: Improved WASM caching strategy

Future Considerations

• Consider adding cache size limits for long-term cache management
• Monitor cache hit rates after deployment to validate improvements

📊 Test Coverage

Manual testing suggested:

• ✅ Verify doc links work on deployed website
• ✅ Test playground WASM loading with cache inspection
• ✅ Confirm 404 status codes for non-existent routes

Areas not requiring tests:

• Documentation link changes (infrastructure)
• Service worker improvements (browser-level functionality)

---

Verdict: This PR addresses legitimate issues with clean, production-ready solutions. The systematic approach to fixing doc links and thoughtful service worker improvements demonstrate good engineering practices. Recommend merging.

---

Job Run

[github-actions]

Claude finished @ajitpratap0's task —— View job

---

PR Review Complete ✅

Reviewing PR #415 for code quality, potential issues, performance, security, and test coverage.

Review Tasks

• Read and analyze all 8 changed files
• Review documentation link fixes for correctness
• Analyze WASM service worker changes for security and performance
• Check alignment with project standards
• Provide comprehensive feedback

📋 Overall Assessment: APPROVED ✅

This is a high-quality PR that addresses legitimate infrastructure issues with clean, well-thought-out solutions.

🔗 Documentation Link Fixes ✅

Issue #398: All broken .md relative links have been systematically fixed across 7 docs files.

Changes Made

• Internal doc links: Converted to website paths (e.g., LINTING_RULES.md → /docs/linting-rules)
• External repo links: Converted to GitHub URLs (e.g., ../CONTRIBUTING.md → full GitHub URL)
• Consistent format: All links now follow the /docs/{kebab-case} pattern

Quality Assessment

• ✅ Systematic: All 7 docs files updated consistently
• ✅ Correct patterns: Links follow established website routing
• ✅ No broken links: All new paths align with website structure
• ✅ Future-proof: Generic /docs/ paths that won't break with repo changes

⚡ WASM Service Worker Improvements ✅

Issue #403: Significant improvements to service worker cache management.

Key Improvements

1. Versioned Cache Strategy 🎯

const CACHE_VERSION = 'v2';
const CACHE_NAME = `gosqlx-wasm-${CACHE_VERSION}`;

• Previous: Hardcoded hash-based cache name
• New: Configurable version-based approach
• Benefit: Easy cache invalidation on WASM binary updates

2. Immediate Service Worker Activation 🚀

self.clients.claim();

• Added: Forces new SW to take control immediately
• Impact: Users get latest WASM binary without refresh

3. Scoped Cache Cleanup 🧹

.filter((name) => name.startsWith('gosqlx-wasm-') && name !== CACHE_NAME)

• Previous: Deleted ALL caches indiscriminately
• New: Only removes GoSQLX WASM caches
• Benefit: Won't interfere with other site caches

4. Response Validation 🛡️

if (response.ok) cache.put(event.request, response.clone());

• Added: Only caches successful responses (2xx status)
• Benefit: Prevents caching of error responses

Performance & Security Analysis

Performance Impact ⚡

• Positive: More efficient cache management
• Positive: Immediate SW activation reduces cache inconsistency
• Neutral: No performance regression expected

Security Assessment 🔒

• Secure: No security vulnerabilities introduced
• Improvement: Better error handling prevents bad response caching
• Best Practice: Scoped cache deletion follows SW best practices

🏗️ Code Quality Assessment

Strengths

• Consistent: All changes follow established patterns
• Well-documented: Clear variable naming and logical structure
• Production-ready: No console.log or debug code
• Standards-compliant: Follows modern Service Worker patterns

Minor Observations

• Documentation: All changes are properly documented in PR description
• Testing: Changes are low-risk infrastructure improvements
• Backwards compatible: No breaking changes to existing functionality

🎯 Project Standards Alignment ✅

Documentation Standards

• ✅ Links follow website routing conventions
• ✅ Consistent formatting across all files
• ✅ Proper markdown syntax maintained

Code Standards

• ✅ Clean, readable JavaScript
• ✅ Modern ES6+ syntax
• ✅ No linting issues observed
• ✅ Follows service worker best practices

🚀 Recommendations

Accept This PR ✅

1. Low Risk: Infrastructure-only changes with high benefit
2. High Quality: Well-executed fixes with attention to detail
3. Immediate Value: Fixes user-facing broken links
4. Performance Benefit: Improved WASM caching strategy

Future Considerations

• Consider adding cache size limits for long-term cache management
• Monitor cache hit rates after deployment to validate improvements

📊 Test Coverage

Manual testing suggested:

• ✅ Verify doc links work on deployed website
• ✅ Test playground WASM loading with cache inspection
• ✅ Confirm 404 status codes for non-existent routes

Areas not requiring tests:

• Documentation link changes (infrastructure)
• Service worker improvements (browser-level functionality)

---

Verdict: This PR addresses legitimate issues with clean, production-ready solutions. The systematic approach to fixing doc links and thoughtful service worker improvements demonstrate good engineering practices. Recommend merging.

---

Job Run