Skip to content

Commit 9b7dca4

Browse files
markfingermarkfinger
committed
Docs
Fixes markfinger#14
1 parent 1fb59cf commit 9b7dca4

File tree

1 file changed

+88
-49
lines changed

1 file changed

+88
-49
lines changed

‎README.md

Lines changed: 88 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -3,20 +3,19 @@ python-react
33

44
[![Build Status](https://travis-ci.org/markfinger/python-react.svg?branch=master)](https://travis-ci.org/markfinger/python-react)
55

6-
Python utils for server-side rendering with React.
6+
Server-side rendering of React components with data from your Python system
77

88
```python
99
from react.render import render_component
1010

1111
rendered = render_component(
1212
'/path/to/component.jsx',
13-
props={
13+
{
1414
'foo': 'bar',
1515
'woz': [1,2,3],
1616
}
1717
)
1818

19-
# The rendered markup
2019
print(rendered)
2120
```
2221

@@ -26,9 +25,10 @@ Documentation
2625

2726
- [Installation](#installation)
2827
- [Basic usage](#basic-usage)
29-
- [API](#api)
30-
- [render_component](#render_component)
31-
- [RenderedComponent](#renderedcomponent)
28+
- [render_component](#render_component)
29+
- [Render server](#render-server)
30+
- [Usage in development](#usage-in-development)
31+
- [Usage in production](#usage-in-production)
3232
- [Django integration](#django-integration)
3333
- [Settings](#settings)
3434
- [Running the tests](#running-the-tests)
@@ -41,11 +41,13 @@ Installation
4141
pip install react
4242
```
4343

44+
**TODO: once the example's settled add links**
45+
4446

4547
Basic usage
4648
-----------
4749

48-
python-react provides a high-level interface to a server which is capable of rendering React components.
50+
python-react provides an interface to a render server which is capable of rendering React components.
4951

5052
To start the server, run
5153

@@ -61,112 +63,149 @@ rendered = render_component('path/to/component.jsx')
6163
print(rendered)
6264
```
6365

64-
The object returned can be passed directly into your template layer.
65-
66+
The object returned has two properties:
6667

68+
- `markup` - the rendered markup
69+
- `props` - the JSON serialized props (if any were provided)
6770

68-
API
69-
---
71+
The object can be coerced to a string to output the markup. Hence you can dump the object directly into
72+
your template layer.
7073

7174

72-
### render_component
75+
render_component
76+
----------------
7377

7478
Renders a component to its initial HTML. You can use this method to generate HTML on the server
7579
and send the markup down on the initial request for faster page loads and to allow search engines
7680
to crawl your pages for SEO purposes.
7781

78-
Returns a [RenderedComponent](#renderedcomponent) instance which can be passed directly into your
79-
front end to output the component's markup and to mount the component for client-side interactivity.
80-
8182

8283
#### Usage
8384

8485
```python
8586
from react.render import render_component
8687

8788
render_component(
88-
# A absolute path to a file which exports your React component
89+
# A path to a file which exports your React component
8990
path='...',
9091

9192
# An optional dictionary of data that will be passed to the renderer
92-
# and can be reused on the client-side
93-
props = {
93+
# and can be reused on the client-side.
94+
data={
9495
'foo': 'bar'
9596
},
9697

9798
# An optional boolean indicating that React's `renderToStaticMarkup` method
9899
# should be used, rather than `renderToString`
99-
to_static_markup = False,
100+
to_static_markup=False,
100101

101-
# An optional class which is used to encode the props to JSON
102-
json_encoder=None,
102+
# An optional object which will be used instead of the default renderer
103+
renderer=None,
103104
)
104105
```
105106

106107
If you are using python-react in a Django project, relative paths to components will be resolved
107108
via Django's static file finders.
108109

110+
By default, render_component relies on access to a render server that exposes an endpoint compatible
111+
with [react-render's API](https://github.com/markfinger/react-render). If you want to use a different
112+
renderer, pass in an object as the `renderer` arg. The object should expose a `render` method which
113+
accepts the `path`, `data`, and `to_static_markup` arguments.
109114

110-
### RenderedComponent
111115

112-
An object representing the output from the rendering process
116+
Render server
117+
-------------
113118

114-
```
115-
rendered = render_component(
116-
'path/to/component.jsx',
117-
props={
118-
# ...
119-
},
120-
)
119+
Earlier versions of this library used to run the render server as a subprocess, this tended to make
120+
development easier, but tended to introduce instabilities and inexplicable behaviour. The library
121+
now relies on externally managed process.
121122

122-
# The markup generated from rendering the component with the provided props
123-
rendered.markup
123+
If you only want to run the render server in particular environments, change the `RENDER` setting to
124+
False. When `RENDER` is False, the render server is not used, but the similar objects are returned.
125+
This enables you to easily build a codebase that supports both development and production environments.
124126

125-
# The value of the `props` argument serialized to JSON. You can pass this directly
126-
# into your template layer
127-
rendered.props
128127

129-
# Equivalent to `rendered.markup`
130-
str(rendered)
131-
unicode(rendered)
132-
```
128+
### Usage in development
129+
130+
In development environments, it's often easiest to set `RENDER` to False. This ensures that the render
131+
server will not be used, hence you only need to manage your python process.
132+
133+
Be aware that the render servers provided in the example and elsewhere rely on Node.js's module system
134+
which - similarly to Python - caches all modules as soon as they are imported. If you use the render
135+
server in a development environment, your code is cached and your changes will **not** effect the
136+
rendered markup until you reset the render server.
137+
138+
139+
### Usage in production
140+
141+
In production environments, you should ensure that `RENDER` is set to True.
142+
143+
You will want to run the render server under whatever supervisor process suits your need. Depending on
144+
your setup, you may need to change the `RENDER_URL` setting to reflect your setup.
145+
146+
Requests are sent to the render server as POST requests.
147+
148+
The render server connector that ships with python-react adds a `?hash=<SHA1>` parameter to the url. The
149+
hash parameter is generated from the serialized data that is sent in the request's body and is intended
150+
for consumption by caching layers.
151+
152+
Depending on your load, you may want to put a reverse proxy in front of the render server. Be aware that
153+
many reverse proxies are configured by default to **not** cache POST requests.
133154

134155

135156
Settings
136157
--------
137158

138-
Settings can be defined by calling `react.conf.settings.configure` with keyword arguments matching
139-
the setting that you want to define. For example
159+
If you are using python-react in a non-django project, settings can be defined by calling
160+
`react.conf.settings.configure` with keyword arguments matching the setting that you want to define.
161+
For example:
140162

141163
```python
142164
from react.conf import settings
143165

166+
DEBUG = True
167+
144168
settings.configure(
145-
RENDER_URL='http://127.0.0.1:8001/render',
169+
RENDER=not DEBUG,
170+
RENDER_URL='http://127.0.0.1:9009/render',
146171
)
147172
```
148173

149-
If you are using python-react in a Django project, add `'react'` to your `INSTALLED_APPS`
174+
If you are using python-react in a Django project, add `'react'` to your `INSTALLED_APPS` and define
175+
settings in a `REACT` dictionary.
150176

151177
```python
152178
INSTALLED_APPS = (
153179
# ...
154180
'react',
155181
)
156-
```
157-
158-
To configure python-react, place a dictionary named `REACT` into your settings file. For example
159182

160183
REACT = {
161-
'RENDER_URL': 'http://127.0.0.1:8001/render'
184+
'RENDER': not DEBUG,
185+
'RENDER_URL': 'http://127.0.0.1:8001/render',
162186
}
187+
```
188+
189+
190+
### RENDER
191+
192+
A flag denoting that the render server should be used. If set to `False`, the renderer will return
193+
objects with an empty string as the `markup` attribute.
194+
195+
Pre-rendering your components is only intended for environments where serving markup quickly is a must.
196+
In a live development environment, running multiple processes overly complicates your setup and can lead
197+
to inexplicable behaviour due to the render server's file caches. Setting this to `False` will remove the
198+
need to run a render server next to your python server.
199+
200+
Default: `True`
163201

164202

165203
### RENDER_URL
166204

167-
A complete url to an endpoint which accepts POST requests conforming to react-render's configuration API.
205+
A complete url to an endpoint which accepts POST requests conforming to
206+
[react-render's API](https://github.com/markfinger/react-render).
168207

169-
Default: `'http://127.0.0.1:9009`
208+
Default: `'http://127.0.0.1:9009/render'`
170209

171210

172211
Running the tests

0 commit comments

Comments
 (0)