Proposal: Component-Level Re-rendering in Waku

[nojaf]

Proposal: Component-Level Re-rendering in Waku

Problem Statement

Currently, unstable_rerenderRoute() triggers a full page re-render, including layout components. This is inefficient when only a specific page component needs to update after a server action, especially when:

1. Layout components (like navigation bars, headers, footers) don't need to change
2. Server actions update only the page component's state
3. Re-rendering the entire route sends unnecessary data over the wire

Use Case: Form Submission in Nested Layout Structure

Consider a typical Waku application structure:

// layouts/AppLayout.jsx
export default function AppLayout({ children }) {
  return (
    <div>
      <Navbar /> {/* Static, rarely changes */}
      <div className="main-content">
        {children} {/* Page components render here */}
      </div>
    </div>
  );
}

// pages/Guess.jsx - Server Component
export default function Guess() {
  const checkGuess = async (formData) => {
    'use server';
    
    // Process form data
    const guess = parseInt(formData.get('guess'));
    const contextData = getContextData();
    contextData.result = guess === 42;
    
    // Current API - re-renders entire route
    unstable_rerenderRoute('/guess'); // ❌ Re-renders AppLayout too!
    
    // Proposed API - re-render only this component
    unstable_rerenderComponent(); // ✅ Only re-renders Guess component
  };

  const contextData = getContextData();

  return (
    <div className="card">
      <h1>Guess the Number</h1>
      
      <form action={checkGuess}>
        <input type="number" name="guess" required />
        <button type="submit">Guess</button>
      </form>

      {contextData.result && (
        <div className={contextData.result === 'correct' ? 'success' : 'error'}>
          {contextData.result === 'correct' ? 'Correct!' : 'Wrong!'}
        </div>
      )}
    </div>
  );
}

// server-entry.jsx
import { createPages } from 'waku';
import AppLayout from './layouts/AppLayout.jsx';
import Guess from './pages/Guess.jsx';

const pages = createPages(async ({ createPage, createLayout }) => {
  createLayout({
    render: 'dynamic',
    path: '/',
    component: AppLayout,
  });

  createPage({
    render: 'dynamic',
    path: '/guess',
    component: Guess,
  });
});

Current Behavior

When unstable_rerenderRoute('/guess') is called:

1. ✅ Page component (Guess) re-renders on server
2. ✅ Layout component (AppLayout) also re-renders on server (unnecessary)
3. ✅ Full RSC payload sent to client (includes layout tree)
4. ✅ React reconciles entire component tree (layout + page)

Problem: Layout components that haven't changed are still re-rendered and sent over the wire.

Proposed Solution

Add a new API unstable_rerenderComponent() that re-renders only the current page component within its layout.

API Design

// In waku/router/server
export function unstable_rerenderComponent(): void;

Behavior

When unstable_rerenderComponent() is called from within a page component:

1. ✅ Only the current page component re-renders on server
2. ✅ Layout components are skipped (use cached/previous render)
3. ✅ Only page component's RSC payload sent to client
4. ✅ React reconciles only the page component subtree

Example Usage

// pages/Guess.jsx
export default function Guess() {
  const submitGuess = async (formData) => {
    'use server';
    
    const guess = parseInt(formData.get('guess'));
    const contextData = getContextData();
    contextData.result = guess === 42 ? 'correct' : 'wrong';
    
    // Re-render only this component, not the layout
    unstable_rerenderComponent();
  };

  const contextData = getContextData();
  const serverTime = new Date().toISOString();

  return (
    <div>
      <h1>Guess the Number</h1>
      <p>Rendered at: {serverTime}</p>
      <form action={submitGuess}>
        <input type="number" name="guess" />
        <button type="submit">Submit</button>
      </form>
      {contextData.result && <div>Result: {contextData.result}</div>}
    </div>
  );
}

Implementation Considerations

1. Component Context Tracking

The framework needs to track which component invoked the re-render:

// Pseudocode
function unstable_rerenderComponent() {
  const currentComponent = getCurrentServerComponent();
  if (!currentComponent) {
    throw new Error('unstable_rerenderComponent must be called from within a page component');
  }
  
  // Re-render only this component and its children
  rerenderComponentTree(currentComponent);
}

2. Layout Component Caching

Layout components should use their cached render when a child component re-renders:

// When rerendering a page component:
// 1. Get cached layout render from previous render
// 2. Re-render only the page component
// 3. Merge: cached layout + new page render
// 4. Send merged RSC payload

3. Context Data Scope

Context data (getContextData()) should remain request-scoped and accessible to both layout and page components during re-render, but layout components won't execute unless they explicitly need to.

4. Error Handling

If unstable_rerenderComponent() is called from outside a page component:

// ❌ Error case
function SomeUtility() {
  const helper = async () => {
    'use server';
    unstable_rerenderComponent(); // Error: Not called from page component
  };
}

// ✅ Valid case
export default function Page() {
  const action = async (formData) => {
    'use server';
    unstable_rerenderComponent(); // OK: Called from page component
  };
}

Benefits

1. Performance: Reduced payload size (only changed components)
2. Efficiency: Layout components don't re-execute unnecessarily
3. Developer Experience: Clear intent - "update this component"
4. Network: Smaller RSC payloads = faster updates
5. Scalability: Better performance for complex layouts with many static elements

Example: Before and After

Before (Current)

// Server action
const action = async (formData) => {
  'use server';
  // ... update context data ...
  unstable_rerenderRoute('/guess');
};

// RSC Payload sent: ~5KB (AppLayout + Navbar + Guess component)
// Layout components re-execute: Yes

After (Proposed)

// Server action
const action = async (formData) => {
  'use server';
  // ... update context data ...
  unstable_rerenderComponent();
};

// RSC Payload sent: ~2KB (Guess component only)
// Layout components re-execute: No (use cached render)

Open Questions

1. Nested Layouts: How should this work with multiple nested layouts?
2. Slices: Should slices within the layout also be excluded from re-render?
3. Cache Invalidation: When should layout cache be invalidated?

Conclusion

This proposal adds a focused API for component-level re-rendering that improves performance and developer experience while maintaining backward compatibility. The use case demonstrates a common pattern where page components update frequently while layouts remain static, making this optimization valuable for real-world applications.

[dai-shi]

Thanks for sharing ideas. At the base, it's our design decision not to rerender at the component level (at least for now). What we do is page/layout/slice level rendering. As I understand it, the request is to selectively rerender some of dynamic page/layout/slices. It's probably a new render type besides "static" and "dynamic". It's reasonable to consider. Though, if it's an additional API that doesn't conflict with current design, I think I'd consider after v1 is released. Meantime, let's discuss about how the API would look like.

[nojaf]

I can understand that at any component level might be too detailed for now.
What I'm after is really a page component versus the entire page (with layout and/or slices)

[dai-shi]

Rerendering only a page is possible technically (because each page has different "slot id" internally), but there are two discussion points:

• The reason it's not allowed is it can easily lead to inconsistencies. So, even if we were to allow it, it will come with a big caveat, and not recommended for non-advanced users.
• What should the public API (to specify the internal "slot id".)

Alternatively, what we may need to consider is having some sort of caching mechanism, and selectively invalidating caches when we rerender a route.

[nojaf]

That could work, if the client sends some hashes of the layout and other slots.
If the server has no newer version of these, it should not send them down.

[dai-shi]

The alternative approach isn't that trivial. By definition, dynamic things should rerender every time.

I'm thinking of adding unstable_rerenderSlice, which is consistent with current design and probably it can be a solution for your use case.