https://github.com/maerzhase/ssr3000
react server side rendering
https://github.com/maerzhase/ssr3000
babeljs isomorphic nodejs react server-side-rendering ssr universal webpack webpack-concepts
Last synced: 5 months ago
JSON representation
react server side rendering
- Host: GitHub
- URL: https://github.com/maerzhase/ssr3000
- Owner: maerzhase
- License: mit
- Archived: true
- Created: 2017-11-26T21:51:53.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2018-08-12T16:39:24.000Z (almost 7 years ago)
- Last Synced: 2024-12-16T08:15:55.286Z (6 months ago)
- Topics: babeljs, isomorphic, nodejs, react, server-side-rendering, ssr, universal, webpack, webpack-concepts
- Language: JavaScript
- Homepage:
- Size: 972 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# SSR3000
A simple framework for server-rendered react applications.
######
Build with [express](https://github.com/expressjs/express) and [webpack >= 4.0.0](https://github.com/webpack/webpack).________
- [Getting started](#getting-started)
- [Serving static assets](#serving-static-assets)
- [Customizing webpack config](#ssr3000configjs)
- [Customizing ssr3000](#ssr3000rc)
- [The idea](#the-idea)
- [ServerMiddleware](#servermiddleware)
- [Node.js API](#nodejs-api)
- [CLI – Command Line Interface](#cli)
- [Examples](#examples)
- [A short digression into webpack](#a-short-digression-into-webpack
)## Getting started
1. `npm install --save ssr3000 react react-dom react-hot-loader express lodash.template `
2. 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"
},
...
}
```
3. create `src`, `src/serverMiddlware` and `src/components` folders4. create client entry: `src/main.js`
```JavaScript
import React from 'react';
import { hydrate } from 'react-dom';
import App from './components/App';hydrate(
,
document.getElementById('root'),
);
```5. create html template to serve: `src/serverMiddleware/index.ejs`
```
SSR3000 App
<%= app %>
<% chunks.js.forEach((chunk) => { %><% }); %>
```
6. create server entry: `src/serverMiddleware/index.js`
```JavaScript
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(),
}));
});
return router;
};
```7. create your app e.g. `src/components/App.js`
```JavaScript
import React from 'react';
import { hot } from 'react-hot-loader';const App = () => (
Hello World
);export default hot(module)(App);
```
###### SSR3000 uses hot reloading by default when watching your application. See [react-hot-loader](https://github.com/gaearon/react-hot-loader) for more informations.8. `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.
```JavaScript
![]()
```## 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```JavaScript
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 clientSSR3000 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`](#ssr3000configjs).## 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
```JavaScript
ssr3000()
```the default export of the SSR3000 module is an ssr3000 instance ready to be initialized.
```JavaScript
import ssr3000 from 'ssr3000';const SSR3000 = ssr3000();
```### watch
```JavaScript
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`](#ssr3000rc).
```JavaScript
import ssr3000 from 'ssr3000';const SSR3000 = ssr3000();
SSR3000.watch('0.0.0.0', 9999);
```### build
```JavaScript
ssr3000.build()
```The build function will build your application for production.
```JavaScript
import ssr3000 from 'ssr3000';const SSR3000 = ssr3000();
SSR3000.build();
```### serve
```JavaScript
ssr3000.serve(host, port)
```The serve function will serve the production build of your application – make sure u have used [ssr3000.build()](#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`](#ssr3000rc)..
```JavaScript
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](https://docs.npmjs.com/cli/run-script) to your `package.json` or execute the cli tools with the relative path instead. You can configure SSR3000 with the [`.ssr3000rc`](#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`](https://github.com/cssinjs/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`](#ssr3000configjs).
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](https://webpack.js.org).#### Entry
Set the entry points of your application
###### For full documentation see [Webpack Concepts: Entry](https://webpack.js.org/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](https://webpack.js.org/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](https://webpack.js.org/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](https://webpack.js.org/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'`
###### For full documentation see [Webpack Concepts: Target](https://webpack.js.org/concepts/targets/)