Kube
Universal React Express middleware package. A universal react dev environment provided through npm install
What's included?
Kube comes with with a middleware that will,
- render your components serverside
- webpack dev server
- webpack hot module reloader server
- webpack module loaders from the server
Webpack module loaders for the server
Webpack module loaders are awesome and brings lot of value to your react development. You can now compose a package with all it's depedencies together. However, problems rise when you attempt to use module loaders for server side rendering purposes. Normal implementations of SSR uses the React-DOMServer to render a component to string. When the DOMServer attempts to require in a file(like an image) normally handled by a webpack loader, it will error out. Node's require expects all loaded files to be a JSON.
Using Kube, components rendered from the server are also prebuilt using webpack. Meaning all the module loaders have parsed through the require statements already. This results in a clean translation between client/server, allowing you to easily use module loaders on react universally.
Use as a standalone server
npm install -g kube
New Project
kube init testing-kube
cd testing-kube
kube up
Existing Project
cd your-project
kube init
kube up
Visit localhost:3000
Use as a Middleware
npm install --save-dev kube
Express App - Server side rendering
// /index.jsconst express = ;const app = /*Loads middleware and provides1. the webpack dev server2. the webpack hot moldule reloader3. res.kube.render*/app src_path: "src" public_path: "public" debug: false app
kube CLI
Kube CLI, installed through npm install -g kube
provides an easy way to get Kube setup on an existing project or a new project.
Commands
init
Calling kube init
will generate the default .kuberc and directories for you. It also includes a sample React Component to demonstrate a simple use case.
Files/directories generated
up
Calling 'kube up' will start the server and you can browse by visiting http://localhost:3000
Currently unfinshed are the -p and -d option flags to change the listening port and to run in the background.
Files
There are 5 files that are mandatory to use kube. These are automatically generated for you if you've used kube init
.
client.js
This is the entry point for your client-side javascript. Normally this will initialize and mount your app to the dom.
sample
const selector = documentconst state = window__INITIAL_STATE
server.js
The component to make available to the server for rendering. The server.js must export an object to be used by the server. This could be an simple single Component or a React Routes component.
sample
moduleexports =
or, if you want to use routes
moduleexports =
layout.js
A file to make updates to the main layout file being rendered from the server. This file should export a function that the server will call to generate the html string. The server passes,
- renderString: This is the rendered component
- bundlePath: This is where the bundle.js exists for the browser to consume
- stylePath: This is where the styles.css exists for the browser to consume
- stateString: This is an optional state object converted to string through
JSON.stringify
that can be passed to the browser.
sample
module { return ` <html> <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/latest/css/bootstrap.min.css"> <link rel="stylesheet" href=""> <body> <div id='root'></div> <script> window.__INITIAL_STATE = </script> <script src=""></script> </body> </html> `}
express_handler.js
The express handler defines how your component will be rendered to string, and is used by res.kube.render
. The express_handler exports a function and receives these 3 parameters,
- Component: Component is the exported module from
server.js
- url: the current url path the browser hit, directly from
req.url
- state: the state passed from
res.kube.render
sample
const React = ReactDOMServer = match RouterContext = module{ const componentString = return componentString} /** * if your server.js exports a single component * @param Component * @returns String * @constructor */{ const element = React return ReactDOMServer} /** * if your server.js exports routes from react-router * @param Component * @constructor */{ let string = '' return string}
.kuberc
Configuration of the paths and toggling debug mode.
Only mandatory if using the standalone server through kube up
. The middleware implementation takes in options during initialization.
default
moduleexports = src_path: "src" public_path: "public" debug: false
src_path
Tells kube where the main files are located.
public_path
Tells kube where to place bundles and static assets for serving to the browser.
debug
Turns on additional debug information from kube.
Todo
- production mode
- improve cli options
- ability to configure webpack