Egg-ssr-pages NPM

egg-ssr-pages

Create roe/egg route definitions to host server-side rendered pages by using next or others.

By using next(the default renderer) as the renderer, your roe/egg application should has a next property on the instance.

Install

$ npm i egg-ssr-pages

Usage

app/router.js

const ssrPages = require('egg-ssr-pages')
const pages = {
    // Then if we can access the pages/index.js by
    //   visiting the page http://localhost:8888/en-US
    '/:lang': 'index'
}

const config = {
  cache: {
    maxAge: 0
  },
  guard: ssrPages.memoryGuardian({
    max: 100
  }),

  // By default, it renders pages by using next
  // renderer: 'next'
}

module.exports = ssrPages(pages, config)

guard guardian is used to validate the each result of server-side rendered pages, and fetch staled value from cache when the server fails to render the page to improves availability.
cache to specify max-age of the cache-controll header.

Override default `SSRConfig` for a certain pagePath

module.exports = ssrPages({
  '/:lang': 'index',

  // We can override a certain property of `SSRConfig` by
  //   defining a new value in each `PageDef`
  '/about': {
    entry: 'about',
    cache: {
      // http://localhost:8888/about
      // -> max-age: 1h
      maxAge: 60 * 60 * 1000
    }
  }
}, {
  cache: {
    maxAge: 0
  }
})

Custom middleware for a certain entry

module.exports = ssrPages({
  '/:lang': {
    entry: 'index',
    middleware: [myCustomMiddleware]
  }
})

module.exports = ssrPages({
  '/:lang': [
    myCustomMiddleware,  // <- koa middleware
    // <- We can define more koa middlewares here
    'index'   // <- entry
  ]
})

Different entries for desktop and mobile devices

const diverge = (desktopEntry, mobileEntry) => ctx =>
  isMobileUserAgent(ctx.headers['user-agent'])
    ? mobileEntry
    : desktopEntry

module.exports = ssrPages({
  '/': diverge('index', 'mobile-index')
})

ssrPages(pages, config: SSRConfig)

pages {[path: string]: PageDef} pages
config SSRConfig the default ssr configurations

Returns a roe/egg router function which accepts app as the only one parameter.

type EntryGetter = function (ctx): string

type PageDef =
  // Just an entry
  string
  | EntryGetter
  // An entry and koa middleware functions for the entry
  | [...Array<Function>, string]
  | ObjectPageDef

// So that we can override the default ssr configurations
interface ObjectPageDef extends OptionalSSRConfig {
  entry: string | EntryGetter
}

interface OptionalSSRConfig {
  // Disable CDN cache by setting to `false`,
  // Defaults to `false`
  cache?: CachePolicy | false
  // Set the `guard` to `false` to disable server-side guardians.
  // - GuardPolicy: your custom policy
  // - `false`(the default value): turn off the guardians
  guard?: GuardPolicy | false,

  // New in 1.1.0
  // Set one or more middlewares for all entries or for a certain entry.
  middleware?: Function | Array<Function>
}

// Preflight checker is used to make sure
//  if the prerequisites are installed or configured,
//  such as egg plugins and extentions
type PreflightChecker = (app): Object | undefined throws Error

interface SSRenderer {
  precheck: PreflightChecker
  async render (ctx, pagePath): string throws Error
}

interface SSRConfig extends OptionalSSRConfig {
  // Method to render the page
  // - SSRenderer: your custom renderer
  // - string: the name of built-in renderers: 'next'
  // Defaults to `'next'`
  renderer: SSRenderer | string = 'next'
}

interface CachePolicy {
  // max-age of cache-control in milliseconeds
  maxAge: number
}

interface GuardPolicy {
  // Preflight checking to see
  //   if the `app` (roe/egg instance) meets certain requirements.
  //   if not, an error could be thrown inside this function.
  // If the function returns an object,
  //   then the object will be used to extend the koa context object,
  //   so that we can access them from all methods below.
  precheck? (app): Object | undefined throws Error

  // Generates the cache key
  key (ctx): string

  // If this function is rejected or returns `false`
  // then it will goes into `fallback`
  async validateSSRResult? (ctx, key, html, time): boolean throws Error

  // If `render` method has been invoked and validated successfully,
  //    `onSuccess` will be called and skip all the following.
  // Most usually, all logic inside `onSuccess` should be catched,
  //   or if there is an error or rejection,
  //   it will goes to `fallback`
  async onSuccess? (ctx, key, html): void

  // If `fallback` succeeded to return a string,
  //   the string will be used instead of the return value of `render`
  async fallback (ctx, key, html, error): string throws Error

ctx KoaContext the koa context, if precheck returns an object, then it will be the extended koa context which has the return value as its own properties
key string the key generated by GuardPolicy::key
html string | undefined the html content which rendered by SSRConfig::render
time number the milliseconds how much the renderer takes to render the page
error Error | null

Built-in guardian `ssrPages.memoryGuardian(options)`

options Object the options of lru-cache

The built-in guardian to cache successfully rendered result in an LRU cache instance with ${hostname}/${pathname} as the key, and try to return the cached value if the request fails to render in the future.