Server-Side Rendering

Server-Side Rendering (SSR) is a powerful technique for rendering WordPress blocks on the server before sending the resulting HTML to the client. This guide covers how to implement SSR with the WP Block to HTML library, optimizing performance and SEO.

Benefits of Server-Side Rendering

Using SSR with WordPress blocks offers several advantages:

Improved Performance: Reduces client-side processing time, especially for complex blocks
Better SEO: Search engines can parse the fully rendered content immediately
Faster First Contentful Paint: Users see content more quickly
Reduced JavaScript Overhead: Less client-side JavaScript processing required
Better Core Web Vitals: Helps improve Largest Contentful Paint (LCP) and Cumulative Layout Shift (CLS)

Basic SSR Implementation

Node.js Environment

Here's a basic implementation of SSR with Node.js:

typescript

// server.js
import express from 'express';
import { convertBlocks } from 'wp-block-to-html';

const app = express();
const port = 3000;

app.get('/post/:id', async (req, res) => {
  try {
    // Fetch WordPress post data (example implementation)
    const postData = await fetchPostFromWordPress(req.params.id);
    
    // Convert blocks to HTML on the server
    const htmlContent = convertBlocks(postData.blocks, {
      ssrOptions: {
        enabled: true,
        optimizationLevel: 'balanced'
      }
    });
    
    // Render a complete HTML page
    const html = `
      <!DOCTYPE html>
      <html>
        <head>
          <title>${postData.title}</title>
          <meta name="description" content="${postData.excerpt}">
          <link rel="stylesheet" href="/styles.css">
        </head>
        <body>
          <header>
            <h1>${postData.title}</h1>
          </header>
          <main id="content">
            ${htmlContent}
          </main>
          <script src="/client.js"></script>
        </body>
      </html>
    `;
    
    // Send the rendered HTML to the client
    res.send(html);
  } catch (error) {
    console.error('Error rendering post:', error);
    res.status(500).send('Error rendering post');
  }
});

// Example function to fetch post data from WordPress
async function fetchPostFromWordPress(postId) {
  const response = await fetch(`https://your-wordpress-site.com/wp-json/wp/v2/posts/${postId}?_fields=id,title,excerpt,blocks`);
  return response.json();
}

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

Next.js Implementation

Next.js provides built-in support for SSR, making it easy to integrate with WP Block to HTML:

typescript

// pages/posts/[id].tsx
import { GetServerSideProps } from 'next';
import Head from 'next/head';
import { convertBlocks } from 'wp-block-to-html';

interface PostProps {
  title: string;
  excerpt: string;
  htmlContent: string;
}

export default function Post({ title, excerpt, htmlContent }: PostProps) {
  return (
    <>
      <Head>
        <title>{title}</title>
        <meta name="description" content={excerpt} />
      </Head>
      <main>
        <h1>{title}</h1>
        <div 
          className="post-content"
          dangerouslySetInnerHTML={{ __html: htmlContent }}
        />
      </main>
    </>
  );
}

export const getServerSideProps: GetServerSideProps = async (context) => {
  try {
    const postId = context.params?.id as string;
    
    // Fetch post data from WordPress
    const response = await fetch(
      `https://your-wordpress-site.com/wp-json/wp/v2/posts/${postId}?_fields=id,title,excerpt,blocks`
    );
    const postData = await response.json();
    
    // Convert blocks to HTML on the server
    const htmlContent = convertBlocks(postData.blocks, {
      ssrOptions: {
        enabled: true,
        optimizationLevel: 'balanced'
      }
    });
    
    return {
      props: {
        title: postData.title.rendered,
        excerpt: postData.excerpt.rendered,
        htmlContent
      }
    };
  } catch (error) {
    console.error('Error fetching post:', error);
    return {
      notFound: true
    };
  }
};

Advanced SSR Configuration

The library provides several options to fine-tune SSR behavior:

typescript

import { convertBlocks } from 'wp-block-to-html';

const htmlContent = convertBlocks(blocks, {
  ssrOptions: {
    enabled: true,                 // Enable SSR
    optimizationLevel: 'maximum',  // Optimization level: 'minimal', 'balanced', or 'maximum'
    lazyLoadMedia: true,           // Add loading="lazy" to images and iframes
    criticalPathOnly: false,       // Only render above-the-fold content
    deferNonCritical: false,       // Defer rendering of below-the-fold content
    preconnect: true,              // Add preconnect for external resources
    removeDuplicateStyles: true,   // Deduplicate inline styles
    minifyOutput: true             // Minify the output HTML
  }
});

Optimization Levels

The optimizationLevel option determines how aggressively the library optimizes the output:

minimal: Basic optimizations with focus on correctness
balanced: Moderate optimizations balancing performance and feature parity
maximum: Aggressive optimizations focused on performance, may simplify some blocks

Hydration Strategies

Hydration is the process of attaching JavaScript event listeners and React/Vue components to server-rendered HTML. The WP Block to HTML library supports several hydration strategies:

Full Hydration

typescript

// server.js
const htmlContent = convertBlocks(blocks, {
  ssrOptions: {
    enabled: true,
    prepareForHydration: true // Add data attributes for hydration
  }
});

// Return HTML with block data for hydration
const fullPage = `
  <!DOCTYPE html>
  <html>
    <head>...</head>
    <body>
      <div id="content">${htmlContent}</div>
      <script>
        // Serialize block data for client-side hydration
        window.__INITIAL_BLOCKS__ = ${JSON.stringify(blocks)};
      </script>
      <script src="/client.js"></script>
    </body>
  </html>
`;

// client.js
import { hydrate } from 'wp-block-to-html/hydration';

document.addEventListener('DOMContentLoaded', () => {
  // Hydrate server-rendered content
  hydrate(
    window.__INITIAL_BLOCKS__, 
    document.getElementById('content')
  );
});

Partial Hydration

For better performance, you can selectively hydrate only interactive blocks:

typescript

// server.js
const htmlContent = convertBlocks(blocks, {
  ssrOptions: {
    enabled: true,
    identifyInteractiveBlocks: true // Mark interactive blocks for selective hydration
  }
});

// client.js
import { hydrateInteractive } from 'wp-block-to-html/hydration';

document.addEventListener('DOMContentLoaded', () => {
  // Only hydrate interactive blocks
  hydrateInteractive(
    window.__INITIAL_BLOCKS__,
    document.getElementById('content')
  );
});

Progressive Hydration

Progressive hydration loads and hydrates blocks based on visibility:

typescript

// server.js
const htmlContent = convertBlocks(blocks, {
  ssrOptions: {
    enabled: true,
    prepareForProgressiveHydration: true
  }
});

// client.js
import { hydrateProgressively } from 'wp-block-to-html/hydration';

document.addEventListener('DOMContentLoaded', () => {
  // Set up progressive hydration with IntersectionObserver
  hydrateProgressively(
    window.__INITIAL_BLOCKS__,
    document.getElementById('content'),
    {
      rootMargin: '200px', // Start hydrating when within 200px of viewport
      threshold: 0.1        // Hydrate when at least 10% visible
    }
  );
});