Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/normancarcamo/express-react-middleware
A middleware able to render react components in your server with node.js as views, it is also able to render routes in an array of routes in react-router.
https://github.com/normancarcamo/express-react-middleware
hot-module-replacement hot-reload hot-reloading html middleware node nodejs react react-app react-component react-components react-redux react-router reactjs router
Last synced: 2 days ago
JSON representation
A middleware able to render react components in your server with node.js as views, it is also able to render routes in an array of routes in react-router.
- Host: GitHub
- URL: https://github.com/normancarcamo/express-react-middleware
- Owner: normancarcamo
- Created: 2017-07-08T22:29:02.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2017-10-06T06:52:18.000Z (about 7 years ago)
- Last Synced: 2024-10-18T19:01:20.209Z (28 days ago)
- Topics: hot-module-replacement, hot-reload, hot-reloading, html, middleware, node, nodejs, react, react-app, react-component, react-components, react-redux, react-router, reactjs, router
- Language: JavaScript
- Size: 401 KB
- Stars: 3
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Authors: AUTHORS
Awesome Lists containing this project
README
# express-react-middleware
A middleware able to render react components in your server with node.js as views, it is also able to render routes in an array of routes in react-router.
## Why?
Have you ever saw that whenever you're making a new project or when an existing project have to be updated you must to follow and do a lot of steps to achieve the desired outcome in the server when you want to apply SSR? Well, this middleware avoid having to remember all those steps even react-router.
## What are the target projects?
- For existing projects.
- For new projects.
- Projects who want to have better control of what components needs to be rendered in a specific resource.
- Projects who want to update their old configurations.
## Pre-requisites
1. A html file to use as template.
2. The html file must include a div or any element with an id attribute to mount the component.
3. The components path or a file with all the routes. (see react-router v4 docs)
## Installation
``npm install --save express-react-middleware``
or
``yarn add express-react-middleware``
## Usage
There are 2 ways to use it in and is using a routes config file or by resolving the components.
#### template
The template is just an html file with a basic markup like this:
```html
Default template, this doesn't render any component
```
This is an example of how to require a template *(synchronous, recommended way)*:
```javascript
import { readFileSync } from 'fs'
import { resolve } from 'path'
const root = (path) => resolve(__dirname, path)
let template = (() => {
try {
return readFileSync(root('./index.html'), { encoding: 'UTF-8' });
} catch (err) {
// If the template file *.html is not found then it throws an error instead of continuing the flow.
throw err;
}
})();
```
#### options
| name | type | optional | required | sync render | async render | description |
| ---- | ---- | -------- | -------- | ----------- | ------------ | ----------- |
| **templateHTML** | string | x | √ | √ | √ | The instance of the html file
| **mountId** | object | x | √ | √ | √ | The id of the element where the component or components will be rendered
| **componentsPath** | string | √ | (√/x) | √ | √ | Here you have to pass the absolute path to locate the components. (required if **routes** option is not set) If routes option is present this option is ignored.
| **routes** | array | √ | (√/x) | √ | √ | the routes file used in react-router to match and render the components. (required if **componentsPath** is not set)
Example of how the options should be written:
```javascript
import { resolve } from 'path'
const root = (path) => resolve(__dirname, path)
let options = {
templateHTML: template,
mountId: "root",
componentsPath: root("path/to/your/components")
};
// or with a file with the routes used in react-router:
import routes from './routes'
// ...
let options = {
templateHTML: template,
mountId: "root",
routes: { collection: routes, /*extractComponent: boolean, default false*/ }
};
```
#### Use it in your app, router or elsewhere you want:
```javascript
import reactMiddleware from 'express-react-middleware'
// ...
app.use(reactMiddleware(options));
```
#### Render:
When the middleware has already been set you will find a new function property with the name **render** in the *request* object.
###### Arguments:
The `req.render` could take some arguments:
| name | type | optional | used in sync render | used in async render |
| -------------- | -------- | -------- | ------------------- | -------------------- |
| **component** | string | √ | √ | √ |
| **props** | object | √ | √ | √ |
| **callback** | function | √ | x | √ |
###### Returns:
When you have used the `req.render` function it will return an object with almost 6 properties:
| name | type | description |
| ------------- | -------- | ----------- |
| **html** | string | value containing the template html with the component rendered, the initial state and props. |
| **context** | object | used in redirections or to set customs status code to the response. |
| **component** | object | The component found. |
| **props** | object | The properties that you passed before the render process |
| **template** | string | The original template value without any modification. |
| **changes** | object | Contains almost all the changes occurred |
###### Synchronous:
```javascript
app.get('/contact', (req, res) => {
// 1.
let { html, context } = req.render('contact');
// ...
// 2.
let { html, context } = req.render('contact', { title: 'Contact', msg: 'Welcome!' });
// ...
// 3.
let { html, context } = req.render('contact', null);
// ...
// 4. This maner is only valid if you have set the "routes" option in the middleware cause it uses "req.url" to find the component instead of having to write the name of a component react file:
let { html, context } = req.render();
// ...
});
```
###### Asynchronous:
```javascript
app.get('/contact', (req, res) => {
// 1. contact is the name of a component and it is resolved with "componentsPath" (Only if routes option is not set).
req.render('contact', ({html, context}) => {
// ...
});
// 2.
req.render('contact', {title: 'Contact', msg: 'Welcome!'}, ({html, context}) => {
// ...
});
// 3.
req.render('contact', null, ({html, context}) => {
// ...
});
// 4. This maner is only valid if you have set the `routes` option in the middleware cause it uses `req.url` to find the component instead of having to write the name of a component react file:
req.render(({html, context}) => {
// ...
});
})
```
###### Response:
``` javascript
app.get('/contact', (req, res) => {
// ... {html, context}
if (context.url) {
res.redirect(context.status, context.url);
// context.url is used to redirect or context.status when you need to send a specific status in your routes.
} else {
res.status(context.status).send(html);
// html is a string value containing the template html also it contains the component rendered.
}
});
```
## Tests:
``` bash
npm run test
```
:+1:
## Examples:
See [examples folder](https://github.com/normancarcamo/express-react-middleware/tree/master/examples)
## Maintainers:
[Norman Carcamo](https://github.com/normancarcamo)
[NPM - modules](https://www.npmjs.com/~normanfx)