umi-server
TypeScript icon, indicating that this package has built-in type declarations

1.2.3 • Public • Published

umi-server

codecov NPM version NPM downloads CircleCI GitHub Actions status

🚀 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 } --
staticMarkup use renderToStaticMarkup boolean -- false
postProcessHtml handler function for user to modify render html accounding cheerio ($, args) => $ Array --
customRender custom Render function (IResult) => Promise --
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

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

Readme

Keywords

none

Package Sidebar

Install

npm i umi-server

Weekly Downloads

86

Version

1.2.3

License

MIT

Unpacked Size

24.7 kB

Total Files

12

Last publish

Collaborators

  • sorrycc