Ssr3000 NPM | npm.io

SSR3000

A simple framework for server-rendered react applications.

Build with express and webpack >= 4.0.0.

Getting started

npm install --save ssr3000 react react-dom react-hot-loader express lodash.template
add scripts to your package.json

{
  ...
  scripts: {
    "watch": "./node_modules/.bin/ssr3000-watch",
    "build": "./node_modules/.bin/ssr3000-build",
    "serve": "./node_modules/.bin/ssr3000-serve"
  },
  ...
}

create src, src/serverMiddlware and src/components folders
create client entry: src/main.js

import React from 'react';
import { hydrate } from 'react-dom';
import App from './components/App';

hydrate(
  <App />,
  document.getElementById('root'),
);

create html template to serve: src/serverMiddleware/index.ejs

<html>
  <head>
    <title>SSR3000 App</title>
  </head>
  <body>
    <div id="root"><%= app %></div>
    <% chunks.js.forEach((chunk) => { %><script src="<%= chunk %>"></script><% }); %>
  </body>
</html>

create server entry: src/serverMiddleware/index.js

import React from 'react';
import { renderToString } from 'react-dom/server';
import { Router } from 'express';
import compile from 'lodash.template';
import templateContent from './index.ejs';
import App from '../components/App';

const template = compile(templateContent);

export default (chunks) => {
  const router = new Router();
  router.use((req, res) => {
    res.status(200);
    res.send(template({
      chunks,
      app: renderToString(<App />),
    }));
  });
  return router;
};

create your app e.g. src/components/App.js

import React from 'react';
import { hot } from 'react-hot-loader';

const App = () => (
  <div>
    Hello World
  </div>
);

export default hot(module)(App);

SSR3000 uses hot reloading by default when watching your application. See react-hot-loader for more informations.

npm run watch

Serving static assets

SSR3000 comes with a build in solution to serve your static files. Just create folder called static inside your project root directory. From within your components you can now reference those files with /static/ URLs.

<img src="/static/cat.jpg" />

ssr3000.config.js

In order to extends the webpack configuration you can define a ssr3000.config.js file that exports a function, which returns the modified webpack configuration.

Warning: this file is not going to be transpiled with babel. So you need to write it in vanilla JS and/or features that are supported by your Node.js version

const customConfig = (config, { isServer }) => {
  return {
    ...config,
  }
}

module.exports = customConfig;

Since we are always configuring webpack for the client and the server, this function will get called twice. Once for the server and once for the client. You can distinguish between them with the isServer parameter.

.ssr3000rc

Use the .ssr3000rc to configure SSR3000 for your project. The .ssr3000rc files must be a valid JSON file.

{
  "host": "localhost",
  "port": 8000
}

Options

Option	Default	Description
`host`	`"0.0.0.0"`	set the hostname for the server
`port`	`9999`	set the port for the server

The idea

SSR3000 is build around the principle of having two different entry files for your application:

The client entry, which usually calls React.render or React.hydrate
The server entry, that handles requests and serves a response to the client

SSR3000 comes with a default webpack configuration that takes away the pain of setting up webpack. If you need to customize the webpack configuration you can do that with the ssr3000.config.js.

ServerMiddleware

It's important to realize that you are responsible for what get's rendered to your client. Without your middleware the server is running but there is no default way of handling responses — therefore without your middleware you will see no output in the browser. It also gives you the greatest flexibilty, because you can provide additional logic e.g. handle routing, serialize inital data to the browser, etc.

Node.js API

ssr3000

ssr3000()

the default export of the SSR3000 module is an ssr3000 instance ready to be initialized.

import ssr3000 from 'ssr3000';

const SSR3000 = ssr3000();

watch

ssr3000.watch(host, port)

The watch function starts the SSR3000 server for development. When the first bundle is ready it will notify that a server has been started. If no host and/or port parameters are provided it will use the default values (0.0.0.0:9999) or use the values from the .ssr3000rc.

import ssr3000 from 'ssr3000';

const SSR3000 = ssr3000();

SSR3000.watch('0.0.0.0', 9999);

build

ssr3000.build()

The build function will build your application for production.

import ssr3000 from 'ssr3000';

const SSR3000 = ssr3000();

SSR3000.build();

serve

ssr3000.serve(host, port)

The serve function will serve the production build of your application – make sure u have used ssr3000.build() before. If no host and/or port parameters are provided it will use the default values (0.0.0.0:9999) or use the values from the .ssr3000rc..

import ssr3000 from 'ssr3000';

const SSR3000 = ssr3000();

SSR3000.serve('0.0.0.0', 9999);

CLI

SSR3000 comes with a built-in CLI which can be used to watch, build and serve your application from the command line. There three are methods exported to the node_modules/.bin folder. You are free to add npm run scripts to your package.json or execute the cli tools with the relative path instead. You can configure SSR3000 with the .ssr3000rc.

watch

start development server

./node_modules/.bin/ssr3000-watch

build

create a production build

./node_modules/.bin/ssr3000-build

serve

run the production server

./node_modules/.bin/ssr3000-serve

Examples

see examples/simple/ for a simple react application setup. see examples/advanced/ for an example with modified webpack config and react-jss for (server-side) styles

Usage

run npm install from within the examples/simple folder

To demonstrate the usage of the .ssr3000rc the example comes with commands to use the Node.js API and the CLI (npm commands have cli: prefix). You could run both at the same time because CLI and Node.js API start on different ports.

Start development server

To start the dev server, run npm run watch or npm run cli:watch

Build for production

To create a production build run npm run build or npm run cli:build

Serve production build

To start the production server, run npm run serve or npm run cli:serve

A brief digression into webpack

SSR3000 uses weback in the background to bundle your application. You no longer need to provide your own webpack configuration. SSR3000 aims to have a fully functional configuration made for all purpose. If you want to customize the webpack configuration anyway you can do that with the ssr3000.config.js. This section is meant to give you an overview of the most important parts of a webpack configuration. If u want to undestand how webpack works in detail please visit the webpack-website.

Entry

Set the entry points of your application

For full documentation see Webpack Concepts: Entry

{
  target: 'web',
  entry: [
    './src/clientEntry.js',
  ],
  ...
}

{
  target: 'node',
  entry: [
    './src/serverEntry.js',
  ],
  ...
}

Output

Set the output settings for your appliation.

For full documentation see Webpack Concepts: Output

{
  target: 'web',
  output: {
    path: './build/client',
    filename: '[name].[hash:8].js',
    publicPath: '/assets/',
  },
  ...
}

{
  target: 'node',
  output: {
    path: './build/server',
    filename: 'bundle.js',
    publicPath: '/assets/',
    libraryTarget: 'commonjs2',
  },
  ...
}

Loaders

Decide how different file types should be loaded. This is done so u can require any file type in your code.

For full documentation see Webpack Concepts: Loaders

{
  ...
  module: {
    rules: [
      {
        test: /\.js$/,
        include: JS_INCLUDES,
        loader: 'babel-loader',
      },
    ],
  },
  ...
}

Plugins (optional)

While loaders are mandatory for all the file types that you use within your application, plugins are totally optional. "Plugins range from bundle optimization and minification all the way to defining environment-like variables", the webpack docs.

For full documentation see Webpack Concepts: Plugins

{
  plugins: [
    new webpack.optimize.UglifyJsPlugin(),
  ],
}

Target

Because our application is getting bundled for the client and for the server the webpack configs need to set the target option accordingly. target: 'node' or target: 'web'