umi-server

🚀 A runtime render tool for Umijs Server-Side Rendering.

Quick Start

(config + ctx) => htmlString

npm install umi-server -S

const server = require('umi-server');
const http = require('http');
const { createReadStream } = require('fs');
const { join, extname } = require('path');

const root = join(__dirname, 'dist');
const render = server({
  root,
})
const headerMap = {
  '.js': 'text/javascript',
  '.css': 'text/css',
  '.jpg': 'image/jpeg',
  '.png': 'image/jpeg',
}

http.createServer(async (req, res) => {
  const ext = extname(req.url);
  const header = {
    'Content-Type': headerMap[ext] || 'text/html'
  }
  res.writeHead(200, header);

  if (!ext) {
    // url render
    const ctx = {
      req,
      res,
    }
    const { ssrHtml } = await render(ctx);
    res.write(ssrHtml);
    res.end()
  } else {
    // static file url
    const path = join(root, req.url);
    const stream = createReadStream(path);
    stream.on('error', (error) => {
      res.writeHead(404, 'Not Found');
      res.end();
    });
    stream.pipe(res);
  }

}).listen(3000)

console.log('http://localhost:3000');

Visit http://localhost:3000.

Usage

First, you need require/import umi-server.

const server = require('umi-server');
// ES6 / TypeScript
import server from 'umi-server';

Enable SSR config

set ssr: true in Umi's configuration file.

// .umirc.js
export default {
+  ssr: true
}

then run umi build to generate the files by default:

.
├── dist
│   ├── index.html
│   ├── ssr-client-mainifest.json
│   ├── umi.js
│   └── umi.server.js
└── pages
    └── index.js

Initialize render

You need to configure the resources needed for SSR.

server([options])

const server = require('umi-server');
const render = server({
  // you should make sure that `umi.server.js` and `ssr-client-mainifest.json` in the same location.
  root: join(__dirname, 'dist'),
});

Client utils

umi-server provide the following utils like isBrowser:

import React from 'react';
import { isBrowser } from 'umi-server';

export default () => {
  const env = isBrowser() ? 'client' : 'server';
  return (
    <p>current env {env}</p>
  )
}

options

| Parameter | Description | Type | Optional Value | Default | | :--- | :--- | :--- | :--- | :--- | | root | prefix path for filename and manifest, if both in the same directory | string | -- | undefined | | filename | umi ssr server-side file | string | -- | ${root}/umi.server.js | | manifest | umi ssr manifest file | string | -- | ${root}/ssr-client-mainifest.json | | dev | whether in development env | boolean | -- | process.env.NODE_ENV === 'development' | | polyfill | whether use polyfill for server-render | boolean | { host: string } | -- | false | | staticMarkup | use renderToStaticMarkup | boolean | -- | false | | postProcessHtml | handler function for user to modify render html accounding cheerio | ($, args) => $ | Array | -- | $ => $ | | customRender | custom Render function | (IResult) => Promise | | -- | ReactDOMServer.renderToString | | stream | use renderToNodeStream, better perf | Boolean | -- | false |

render Component/Page

server-side render using current req.url to match the current page or component.

Result = render(ctx, renderOpts)

(req, res) => {
  const ctx = {
    req: {
      url: req.url,
    },
    res,
  }
  const { ssrHtml } = await render(ctx);
  res.write(ssrHtml);
}

Custom Render

umi-server supports custom render function by user. see ssr-customRender/index.test.ts.

ctx

the request and reponse render context, req and res will pass down into getInitialProps.

| Parameter | Description | Type | Optional Value | Default | | :--- | :--- | :--- | :--- | :--- | | req | http Request obj, must include url | Request | -- | undefined | | res | http Reponse obj | | -- | |

renderOpts

the render runtime opts like default polyfill for different pages.

| Parameter | Description | Type | Optional Value | Default | | :--- | :--- | :--- | :--- | :--- | | polyfill | same as the options#polyfill | | -- | false | | runInMockContext | runtime global object mock, for mock window.location, etc. | | -- | false |

more example usages in test cases.

TODO

• [x] Serverless
• [x] Support stream render
• [ ] Support react-helmet and react-document-title handler
• [ ] Better performance