Docs deployment review and plan

docs-deployment-plan.md

📋 Docs PR Deployment Plan

Pre-Merge (Critical Only)

• Verify all apps build successfully locally: pnpm build

Vercel Deployment Steps

1. Merge PR

• Merge solana-docs-2 → main
• Vercel auto-deploys all apps (web, docs, media, templates)

2. Verify Deployments

• Web app deploys successfully
• Docs app deploys successfully
• Check Vercel deployment logs for errors

Post-Deployment Verification (First 30 Minutes)

• Smoke test: /docs loads
• Smoke test: /learn loads
• Smoke test: /developers/cookbook loads
• Smoke test: Header navigation works (click docs link from homepage)
• Check Sentry for immediate errors
• Verify assets load (CSS/images not broken)

🚨 Rollback Criteria

Rollback immediately if:

• Complete site outage (503/500 errors on main routes)
• Docs section completely inaccessible (all /docs/*, /learn/*, /developers/cookbook/*, /developers/guides/* routes return 404/500)
• Web app deployment fails completely
• Critical security issue discovered

Do NOT rollback, fix incrementally (monitor via Sentry):

• Individual page 404s (fix broken links)
• Minor asset loading issues (missing images, broken CSS for specific pages)
• Console errors in Sentry (non-breaking JavaScript errors)
• Performance regressions (monitor and optimize)
• i18n translation issues (missing translations, fallback to English is acceptable temporarily)
• Edge case routing issues (specific URL patterns not working)

Post-Deployment Monitoring (First 24-48 Hours)

• Monitor Sentry error rates (compare to baseline)
• Check Vercel analytics for traffic drops
• Monitor proxy latency (should be minimal via Vercel edge)
• Watch for 404 spikes in analytics
• Review user feedback/reports

If Issues Arise

• Non-critical issues: Create hotfix PRs, deploy normally
• Critical issues (meeting rollback criteria): Revert PR, redeploy web app
• Rollback process: git revert <merge-commit>, push to main, let Vercel redeploy

Success Criteria (After 24 Hours)

• No rollback triggered
• Error rates in Sentry within normal range
• All primary routes accessible
• No significant traffic drop
• Docs content accessible and navigable

---

Note: This PR is backward compatible from a user perspective (all URLs remain the same). The main risks are infrastructure-related (routing, asset loading), which should be immediately apparent post-deployment. Incremental fixes can be applied for smaller issues without rollback.

pr-review.md

Pull Request Review Report

Branch: solana-docs-2 → main

---

🔍 PR Overview

Change Type: Major Architectural Refactoring
Scope: Multi-app monorepo migration (extracting docs into separate app)
Files Changed: ~4,754 files (mostly moves, ~113 actual modifications)
Lines Changed: +26,787 insertions, -2,256 deletions
Overall Impact: 🔴 HIGH RISK

Summary

This PR implements a major architectural change to split the Solana.com monorepo into separate Next.js applications. The primary change is extracting documentation content and functionality from apps/web into a new apps/docs application, following the pattern already established for apps/media and apps/templates. The architecture uses Next.js rewrites to proxy requests from the main web app to specialized apps.

Key Commits

• 2179e058 - fix edit on github url
• e2900474 - add missing images
• 7338b0ec - move mdx content from web to docs
• b50b5636 - create apps/docs

---

🏗️ Architectural Changes

1. New App Creation: apps/docs

• Purpose: Handles /docs/*, /learn/*, and /developers/{cookbook,guides}/* routes
• Port: 3003 (development)
• Asset Prefix: /docs-assets (for proper asset routing through proxy)

2. Routing Architecture

The PR implements a proxy-only architecture where:

• All apps are accessed through solana.com (never subdomains)
• The web app uses Next.js rewrites to proxy requests to specialized apps
• Each proxied app uses asset prefixes to namespace static assets

3. URL Configuration (apps/web/apps-urls.js)

• Added DOCS_APP_URL configuration following the same pattern as media/templates
• Uses @vercel/related-projects for production URL resolution
• Falls back to localhost:3003 for development
• ⚠️ ISSUE FOUND: Console.log statements in production code (lines 40-42)

4. Rewrites Configuration (apps/web/rewrites-redirects.mjs)

• Added comprehensive rewrite rules for docs app routes:
  • /docs and /docs/*
  • /learn and /learn/*
  • /developers, /developers/cookbook/*, /developers/guides/*
  • /opengraph/* (for docs-specific OG images)
  • Asset rewrites for /docs-assets/*
• Proper ordering maintained (templates rewrites before general /developers)

5. Header Link Routing (packages/ui-chrome/src/url-config.ts)

• Complete refactor from subdomain-based to app-based routing
• New logic: Uses NEXT_PUBLIC_APP_NAME to determine internal routes
• Web app: Uses Next.js Link for routes NOT handled by other apps
• Other apps: Uses Next.js Link only for routes internal to that app
• Cross-app navigation uses full page loads to trigger proxy

6. Middleware Updates (apps/web/src/middleware.ts)

• Added paths to skip i18n routing:
  • /docs, /learn
  • /developers, /developers/cookbook, /developers/guides
  • /opengraph
• Updated matcher regex to exclude docs routes from web app middleware

7. Internationalization (i18n)

• Docs app merges translations from both web app and its own locales
• Pattern: apps/docs/src/i18n/request.ts loads from apps/web/public/locales/ + app-specific locales
• Allows shared header/footer translations while maintaining app-specific content

8. Content Migration

• Thousands of MDX files moved from apps/web/content/docs/* → apps/docs/content/docs/*
• Content structure preserved with locale prefixes (vi, zh, ko, etc.)
• Meta.json files migrated for navigation structure

9. Dependencies Cleanup

• Removed docs-specific dependencies from apps/web/package.json:
  • @fumadocs/mdx-remote, fumadocs-core, fumadocs-mdx, fumadocs-ui
  • codehike, mermaid
  • @ai-sdk/openai, ai (likely moved to docs if needed)
• Dependencies properly moved to apps/docs/package.json

---

🔒 Security Considerations

✅ Positive Aspects

• No new authentication/authorization logic introduced
• No sensitive data exposure in the changes
• Input validation patterns maintained (handled by Next.js and existing middleware)

⚠️ Areas to Review

1. Proxy Configuration: Ensure rewrites cannot be exploited for SSRF attacks

   • Current implementation uses environment-controlled URLs - ✅ Good
   • @vercel/related-projects is a trusted source - ✅ Good

2. Asset Prefixing: Verify asset routes cannot be used for path traversal

   • Rewrites use :path+ which should be safe in Next.js context
   • No user-controlled input directly affects asset paths - ✅ Good

---

⚡ Performance Impact

Potential Concerns

1. Additional Network Hop: All docs routes now require proxy through web app

   • Impact: Minimal (same Vercel infrastructure, edge locations)
   • Mitigation: Vercel's edge network handles this efficiently

2. Bundle Size Reduction: Removing docs dependencies from web app should improve web app bundle size

   • ✅ Positive: Faster initial load for non-docs pages

3. Asset Loading: Asset prefixing adds /docs-assets prefix to all static assets

   • Impact: Slight increase in request path length (negligible)
   • Benefits: Prevents asset conflicts, enables proper caching strategies

4. Middleware Execution: Multiple middleware functions now handle different route subsets

   • Impact: More efficient (only relevant middleware runs per route)
   • ✅ Positive: Better separation of concerns

Recommendations

• Monitor CDN cache hit rates after deployment
• Consider adding performance monitoring for proxy latency
• Verify asset loading times for docs pages post-deployment

---

💥 Breaking Changes

1. Internal API/Route Changes

• ✅ No public API changes - All URLs remain the same for end users
• Internal routing logic changed significantly
• Build/development workflows affected

2. Environment Variables

• New Required: NEXT_PUBLIC_DOCS_APP_URL (optional, auto-detected in production)
• New Required: NEXT_PUBLIC_APP_NAME (set to "docs" in docs app)
• Existing vars continue to work

3. Development Workflow

• Breaking: Must run all apps simultaneously for full functionality
• Breaking: Direct access to docs app requires understanding of new routing
• New: pnpm dev now starts 4 apps (was 3)

4. Deployment Configuration

• Breaking: Requires Vercel project configuration for apps/docs
• Breaking: Must link docs app as related project in web app's Vercel settings
• Build pipeline now includes docs app build step

5. Content Location

• Breaking: Content editors must now edit files in apps/docs/content/ instead of apps/web/content/docs/
• All content moved - existing bookmarks/scripts may break

---

⚠️ Risk Assessment

🔴 High-Risk Areas

1. Routing Logic Complexity

   • Risk: Incorrect rewrite rules could cause 404s or infinite redirects
   • Impact: Entire docs section inaccessible
   • Mitigation: Extensive testing of all route patterns required
   • Review Focus: rewrites-redirects.mjs rewrite rules and order

2. Header Navigation Link Behavior

   • Risk: Links might use wrong navigation method (Link vs )
   • Impact: Broken navigation, poor UX, SEO issues
   • Mitigation: Test navigation from all app contexts
   • Review Focus: packages/ui-chrome/src/url-config.ts regex patterns

3. Asset Loading

   • Risk: Assets might not load correctly through proxy
   • Impact: Broken styling, missing images, non-functional pages
   • Mitigation: Verify asset rewrites work in all environments
   • Review Focus: Asset prefix configuration and rewrite rules

4. Internationalization

   • Risk: i18n routing might break for docs routes
   • Impact: Non-English docs inaccessible
   • Mitigation: Test all locale combinations
   • Review Focus: Middleware skip logic and locale handling

🟡 Medium-Risk Areas

1. Build Dependencies

   • Risk: Missing dependencies in docs app could cause build failures
   • Impact: Deployment failures
   • Mitigation: Verify all dependencies migrated correctly

2. Environment Variable Configuration

   • Risk: Missing or incorrect env vars in production
   • Impact: Proxy failures, app routing issues
   • Mitigation: Document all required env vars, verify in Vercel config

3. Content Migration Completeness

   • Risk: Some content files might not have been migrated
   • Impact: Missing pages, broken links
   • Mitigation: Audit content directory structure

🟢 Low-Risk Areas

1. Code Quality

   • Well-structured refactoring
   • Follows existing patterns (media/templates apps)
   • Good documentation in MULTI_APP_ARCHITECTURE.md

2. Type Safety

   • TypeScript configuration appears correct
   • No obvious type issues in reviewed files

---

✅ Positive Aspects

1. Excellent Documentation

• Comprehensive MULTI_APP_ARCHITECTURE.md explains the entire system
• Clear patterns for adding new apps
• Well-documented routing logic

2. Consistent Patterns

• Follows established patterns from media/templates apps
• Consistent asset prefixing strategy
• Unified URL resolution logic

3. Proper Separation of Concerns

• Docs-specific code now isolated in docs app
• Web app lighter weight
• Better maintainability long-term

4. Backward Compatibility (User-Facing)

• All public URLs remain unchanged
• No breaking changes for end users
• SEO-friendly (no URL changes)

5. Development Experience

• Clear multi-app structure
• Proper Turbo configuration
• Well-organized monorepo structure

---

🎯 Review Focus Areas

Critical (Must Review Before Merge)

1. 🔴 apps/web/apps-urls.js - Lines 40-42

   console.log("MEDIA_APP_URL", MEDIA_APP_URL);
   console.log("DOCS_APP_URL", DOCS_APP_URL);
   console.log("TEMPLATES_APP_URL", TEMPLATES_APP_URL);

   Issue: Console.log statements in production code Recommendation: Remove or wrap in development-only check Priority: HIGH - Should be fixed before merge

2. 🔴 Rewrite Rule Order (apps/web/rewrites-redirects.mjs)

   • Verify templates rewrites come before general /developers rewrites
   • Confirm asset rewrites are in correct position
   • Test that more specific routes match before general patterns

3. 🔴 Regex Patterns (packages/ui-chrome/src/url-config.ts)

   • Review regex for docs app: /^\/(?:docs|learn)(?:\/|$)|^\/developers(?:$|\/(?:cookbook|guides)(?:\/|$))/
   • Test edge cases: /developers, /developers/, /developers/other
   • Verify templates regex doesn't conflict: /^\/developers\/templates(?:\/|$)/

4. 🔴 Middleware Skip Logic (apps/web/src/middleware.ts)

   • Verify all proxied paths are properly excluded
   • Check locale handling doesn't break for docs routes
   • Test case-insensitive redirect logic

High Priority (Review Thoroughly)

5. 🟡 Asset Prefix Configuration

   • Verify assetPrefix: "/docs-assets" in apps/docs/next.config.ts
   • Confirm internal rewrites work: /docs-assets/_next/:path+ → /_next/:path+
   • Test asset loading in production-like environment

6. 🟡 Environment Variable Setup

   • ✅ turbo.json already includes NEXT_PUBLIC_DOCS_APP_URL in globalEnv (verified)
   • Confirm Vercel project configuration
   • Test URL resolution in all environments (dev, preview, production)

7. 🟡 i18n Translation Loading

   • Test translation merging works correctly
   • Verify fallback to English works
   • Check that web app translations are accessible from docs app

8. 🟡 Content Migration Completeness

   • Spot-check that all MDX files were migrated
   • Verify meta.json files are complete
   • Check for any hardcoded paths that reference old location

Medium Priority (Review if Time Permits)

9. 🟢 Dependency Cleanup

   • Verify removed dependencies aren't needed elsewhere
   • Check that docs app has all required dependencies
   • Review pnpm-lock.yaml for any issues

10. 🟢 Type Definitions

    • Check TypeScript compilation for all apps
    • Verify type exports from shared packages
    • Review any new type definitions

---

🧪 Testing Recommendations

Pre-Merge Testing

1. Route Testing

   • Test all docs routes: /docs, /docs/intro, /docs/:locale/docs/intro
   • Test learn routes: /learn, /learn/:path
   • Test developer routes: /developers, /developers/cookbook, /developers/guides
   • Test templates routes still work: /developers/templates
   • Test direct app access vs proxy access

2. Navigation Testing

   • Test header links from web app → docs app (should use tag)
   • Test header links within docs app (should use Next.js Link)
   • Test footer links
   • Test breadcrumb navigation
   • Test "Edit on GitHub" links

3. Asset Loading

   • Verify CSS loads correctly
   • Verify JavaScript bundles load
   • Test images and other static assets
   • Check favicon and meta images
   • Verify fonts load correctly

4. Internationalization

   • Test all supported locales: /en/docs, /es/docs, /zh/docs, etc.
   • Verify locale switching works
   • Check RTL languages (if applicable)
   • Test fallback to English for missing translations

5. Build & Deployment

   • Verify all apps build successfully
   • Test production build locally
   • Verify Vercel deployment configuration
   • Test related projects integration

6. Performance Testing

   • Measure page load times (before/after if possible)
   • Check Lighthouse scores
   • Verify no regression in Core Web Vitals
   • Test with slow network conditions

Post-Merge Monitoring

1. Error Tracking

   • Monitor Sentry for 404s or routing errors
   • Watch for asset loading failures
   • Track middleware errors

2. Analytics

   • Verify analytics tracking still works
   • Check conversion funnels
   • Monitor user flow between apps

3. Performance Monitoring

   • Track proxy latency
   • Monitor CDN cache hit rates
   • Watch for slow page loads

---

📋 Action Items

Before Merge (Critical)

• Remove console.log statements from apps/web/apps-urls.js (lines 40-42)
• Test all route patterns with comprehensive manual testing
• Verify Vercel configuration for docs app deployment
• Test navigation from all app contexts (web → docs, docs → web, etc.)

After Merge (Important)

• Monitor error rates for first 24-48 hours
• Verify SEO - check sitemap generation, meta tags, structured data
• Update deployment documentation if needed
• Train content team on new content location (apps/docs/content/)
• Update any CI/CD scripts that reference old content paths

Follow-up (Nice to Have)

• Performance optimization if proxy latency is noticeable
• Consider caching strategy for proxy responses
• Document common issues and troubleshooting steps
• Add integration tests for cross-app navigation

---

💡 Questions for PR Author

1. Testing Coverage: What testing has been performed? Any automated tests added?
2. Deployment Plan: Is the Vercel project for docs app already created and linked?
3. Rollback Strategy: What's the plan if issues arise post-deployment?
4. Performance Baseline: Are there performance benchmarks from before this change?
5. Content Verification: Has all content been verified to migrate correctly?
6. Browser Testing: Has this been tested across different browsers/devices?
7. Error Handling: How are proxy failures handled? What happens if docs app is down?

---

📊 Risk Summary

Risk Level	Count	Areas
🔴 High	4	Routing logic, navigation, assets, i18n
🟡 Medium	3	Dependencies, env vars, content migration
🟢 Low	2	Code quality, type safety

Overall Risk Rating: 🔴 HIGH
Recommendation: ✅ APPROVE WITH CONDITIONS

This is a well-executed architectural refactoring that follows good patterns. However, the high risk rating is due to:

1. Complexity of routing/proxy system
2. Large scope of changes
3. Critical production paths affected
4. Potential for subtle bugs that only appear in production

The PR should be merged after addressing the critical issues (console.log removal, testing) and with careful monitoring post-deployment.

---

🎉 Conclusion

This PR represents a significant architectural improvement that will improve maintainability and scalability of the Solana.com codebase. The separation of concerns is well-designed, documentation is excellent, and the patterns are consistent.

Primary Concerns:

• Console.log statements need removal
• Comprehensive testing required before merge
• Post-deployment monitoring essential

Strengths:

• Excellent documentation
• Consistent patterns
• Clean separation of concerns
• Backward compatible (user-facing)

With proper testing and addressing of the console.log issue, this PR is ready for merge.

---

Report generated for PR review of branch solana-docs-2