Docs api references strategy #1294
Draft
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This commit adds a proof-of-concept implementation for migrating the API
reference pages from Pages Router to App Router with Server Components.
Two approaches are demonstrated:
1. Transitional approach (/api-reference-v2):
- Maintains compatibility with existing component architecture
- Data is passed from server to client components
- Good starting point for incremental migration
2. Optimized approach (/api-reference-v2/optimized):
- Full server component rendering where possible
- Only interactive elements use client components ('islands')
- OpenAPI spec never leaves the server
- Minimal JavaScript payload
Key files added:
- lib/openApiSpec.server.ts: Cached spec loading with React cache()
- app/(api-reference)/layout.tsx: Shared layout with providers
- app/(api-reference)/providers.tsx: Client-side providers
- app/(api-reference)/api-reference-v2/: Transitional implementation
- app/(api-reference)/api-reference-v2/optimized/: Full server component implementation
Benefits of this approach:
- OpenAPI spec (1MB+) stays on server, not serialized to client
- React cache() deduplicates spec loading across renders
- Streaming support for faster TTFB
- Individual resource sections can be suspended independently
Co-authored-by: chris <chris@knock.app>
|
Cursor Agent can help with this pull request. Just |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Replace proof-of-concept code with a detailed migration plan document that covers: - Problem statement and root cause analysis - Solution overview with App Router and Server Components - Complete architecture design with directory structure and data flow - Six migration phases with estimated effort - Detailed implementation tasks with code examples and acceptance criteria - Component breakdown (reuse, refactor, new) - Testing strategy (unit, integration, E2E, visual regression) - Rollback plan - Success criteria (performance, functionality, DX, SEO) The plan provides a roadmap for migrating the API reference pages from Pages Router (with 2-5MB HTML payloads) to App Router with Server Components (targeting <100KB payloads). Co-authored-by: chris <chris@knock.app>
Co-authored-by: chris <chris@knock.app>
Replace App Router/RSC approach with Pages Router compatible solution: - Split API reference into one page per resource (12 pages) - Use ISR for incremental updates without full rebuilds - Reduce page payload from 2-5MB to 50-150KB per resource - Keep Telegraph components working as-is Key changes in the plan: - Detailed page structure with [resource].tsx dynamic route - Data loading strategy with partial spec extraction - Component refactoring to accept props instead of context - Navigation and UX considerations - Step-by-step migration instructions - Testing checklist and rollout strategy Co-authored-by: chris <chris@knock.app>
Changed approach from one-page-per-resource to individual pages for each method and schema with proper URL paths: - /api-reference/users/get instead of /api-reference/users#get - /api-reference/users/schemas/user for schema pages - Catch-all route [...slug].tsx handles methods, subresources, schemas Key updates: - New URL structure with ~133 pages for API, ~100 for MAPI - Path generation utilities for getStaticPaths - Individual loaders for method, schema, and resource overview pages - Sidebar shows full navigation tree - Breadcrumb navigation on all pages - Page sizes reduced to 20-50KB per method page This gives clean, shareable URLs while maintaining small page sizes and ISR for incremental updates. Co-authored-by: chris <chris@knock.app>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
This PR introduces a proof-of-concept (POC) migration of the API reference documentation from the Next.js Pages Router to the App Router. The primary motivation is to resolve existing build and runtime performance issues, such as large page payloads, high memory consumption during builds, and slow hydration, which stem from loading and embedding the entire OpenAPI specification within
getStaticProps.The App Router approach allows the OpenAPI spec to be processed and rendered entirely on the server, drastically reducing the client-side JavaScript bundle and HTML payload.
Two implementations are provided:
/api-reference-v2): A stepping stone that maintains compatibility with existing client components by passing the spec to a client component after server-side rendering./api-reference-v2/optimized): The recommended long-term solution, fully leveraging Server Components to process the spec on the server and only sending rendered HTML to the client, with "client islands" for interactive elements.Key changes include:
lib/openApiSpec.server.ts: A new module for cached, server-side loading and dereferencing of OpenAPI specs usingReact.cache().app/(api-reference)/.Todos
/api-reference-v2and/api-reference-v2/optimizedto verify rendering.next.config.jsrewrites to map existing API reference URLs to the new App Router paths.pages/api-reference/index.tsx) once validated.Tasks
N/A
Screenshots