Rax Server Driver

Common errors

• ReferenceError: window is not defined

  cause Attempting to access browser-specific global objects (like `window`, `document`, `localStorage`) in Rax components that are being rendered on the Node.js server.
  fix Ensure that Rax components intended for universal rendering check the execution environment (e.g., using `isNode` from `universal-env` or `typeof window === 'undefined'`) before accessing browser-only APIs. Mock browser globals on the server if absolutely necessary.

• Warning: Prop `className` did not match. Server: "foo" Client: "bar"

  cause A common 'hydration mismatch' error in SSR where the HTML rendered on the server differs from the HTML generated by the client-side JavaScript for the initial render.
  fix Verify that server-side and client-side rendering logic is identical. This often involves ensuring consistent data fetching, environment-specific rendering (e.g., different styles or components for server vs. client), and deterministic ID generation.

• Module not found: Can't resolve 'driver-server' in 'your-project/src'

  cause The 'driver-server' package is not correctly installed, or the import path is incorrect, or a module bundler is misconfigured.
  fix Run `npm install driver-server` or `yarn add driver-server`. Check your `package.json` for its presence. Ensure your bundler (Webpack, Rollup) is configured to resolve node_modules correctly and that the import statement `import ServerDriver from 'driver-server';` uses the correct package name and default import.

Warnings

• breaking Version 1.2.1 included a refactor to change output result format, avoiding mixing IIFE and CJS. This could potentially break existing build configurations or environments that relied on specific CommonJS or IIFE bundling patterns.
  Fix: Review existing build configurations and module loading strategies. Adjust bundler settings (e.g., Webpack, Rollup) or Node.js module resolution if experiencing issues with module format compatibility after upgrading.
• gotcha The Rax framework, and by extension `driver-server`, appears to be an abandoned project with no significant updates or active maintenance since September 2021. This implies a lack of new features, security patches, or compatibility fixes for newer Node.js versions, browser standards, or JavaScript language features.
  Fix: Proceed with caution. Be prepared to fork the repository and maintain it yourself for any critical issues or necessary updates. Evaluate the long-term viability of Rax for new projects. Consider migrating to more actively maintained frameworks if stability and ongoing support are crucial.
• gotcha The Rax ecosystem is significantly smaller and less supported than mainstream frameworks like React. Finding community help, comprehensive documentation, or third-party libraries might be challenging, especially for complex or niche use cases.
  Fix: Rely heavily on the existing (though potentially outdated) official documentation and source code. Be prepared for self-support and extensive debugging. Consider the limited ecosystem when designing architecture or choosing additional libraries.

Install

• npm install driver-server npm
• yarn add driver-server yarn
• pnpm add driver-server pnpm

Imports

• ServerDriver
  wrong:

  import { ServerDriver } from 'driver-server';

  correct:

  import ServerDriver from 'driver-server';

  This package exports ServerDriver as a default export, not a named one.
• render
  wrong:

  const { render } = require('rax');

  correct:

  import { render } from 'rax';

  The Rax core `render` function is used to initiate the rendering process with the server driver.
• isNode
  wrong:

  import isNode from 'universal-env';

  correct:

  import { isNode } from 'universal-env';

  isNode is a named export from universal-env, crucial for environment-specific code execution in universal applications.

Quickstart

This example demonstrates how to use `driver-server` to perform server-side rendering (SSR) of a Rax component. It shows the setup of a basic Rax component and its rendering using `ServerDriver` conditioned on the execution environment.

import {createElement, Component, render} from 'rax';
import ServerDriver from 'driver-server';
import {isNode} from 'universal-env';

class Example extends Component {
  render() {
    return (
      <div>
        <img width="560" height="560" src="https://img.alicdn.com/tps/TB1z.55OFXXXXcLXXXXXXXXXXXX-560-560.jpg" alt="Example Image" />
      </div>
    );
  }
}

// Render the Rax component, specifying ServerDriver for Node.js environments
// In a real application, you would capture the output and send it as HTML.
const serverRenderResult = render(<Example />, null, {
  driver: isNode ? ServerDriver : null
});

if (isNode) {
  console.log('Server-rendered HTML output:');
  // In a typical SSR setup, this output would be sent to the client as the initial HTML.
  // The exact method to get the string might vary depending on Rax version, but render() handles it.
  // For simplicity, we assume render() directly returns a string in server context here.
  // You might need to check Rax's documentation for specific server-side output retrieval.
  // For illustration, assuming serverRenderResult holds the rendered content.
  // This exact output format of `render` in server context needs to be confirmed with Rax docs.
  // Rax's render for SSR usually directly outputs HTML to a stream or returns it.
  // The provided example shows `render(<Example />, null, { driver: ServerDriver })`
  // which implies ServerDriver intercepts the rendering and provides server-specific output.
  // Without more context on `render`'s server-side return, we'll demonstrate basic usage.
  // A common pattern is `ReactDOMServer.renderToString(element)` in React, for Rax it's part of the render function.
  console.log(serverRenderResult); // Placeholder, actual output retrieval might differ.
} else {
  console.log('This code path is for browser rendering, not active in this quickstart.');
}