search

facebookarchive / react-page

Easy Application Development with React JavaScript
Apache License 2.0
797 stars 72 forks source link

readme

This project is not actively maintained. Proceed at your own risk!


Install (Mac/Linux - requires a recent version of node/npm)

Clone this project

git clone https://github.com/facebook/react-page
cd react-page
npm install                            # install dependencies.

Try out the server rendering

node server.js
# open http://localhost:8080/index.html
# Make changes to src/index.js, and refresh instantly!

Philosophy

Why Server Rendering?
Why React?

Developing

Default Project Structure

The included directory structure suggests a way to organize a single or multi-page app. npm install other components/libraries and they automatically work. It's the same commonJS that you know and love.

react-page/
 ├── package.json                # Add npm dependencies here.
 ├── server.js                   # Start web server with `node server.js`
 ├── ...                         # Create more pages/directories here
 └── src                         # All your application JS.
     ├── elements/               # Shared React components.
     │   ├── SiteBoilerPlate.js  # Reusable html/body component
     │   └── Banner.js           # An example component for displaying text
     │
     ├── index.js                # localhost:8080/index.html routed here
     └── pages                   # Make your site structure
         └── about.js            # localhost:8080/pages/about.html

Everything Is A Component

React's philosophy is that mutation-minimal functions and composition are the best tools for building sophisticated applications with low complexity. In React, "components" are the tool for composing. react-page embraces this simplicity, even allowing the entire page to be expressed as an arbitrarily deep composition of components.

react-page/src/index.js corresponds to index.html. index.js is a React component that renders the <html>,<body>, and all the contents of the page.

If you look at index.js, you'll notice that it doesn't output all the <div>s and <span>s directly - it composes other components that take on much of that responsibility. index.js composes a <Banner> component, and inside of Banner.js, you'll see that the implementation of <Banner> outputs an <h1> DOM component. Even DOM representations such as <h1> are components in React

To build out your app, just add or install more components with npm.

Simple Default Page Routing

Requests to path/file.html are routed to your React component located at src/path/file.js. By default all page requests are routed to the src directory, but you can customize that behavior via the pageRouteRoot setting.

Here are a couple of examples of the default configuration:

http://localhost:8080/index.html => react-page/src/pages/index.js
http://localhost:8080/docs/hello.html => react-page/src/pages/docs/hello.js
http://localhost:8080/pages/about.html => react-page/src/pages/about/index.js
http://localhost:8080/path/img.png => react-page/src/path/img.png

How Does Server Rendering Work?

Command Line Usage:

# --useSourceMaps=true        # default:true
# --useBrowserBuiltins=false  # Allow node modules (util)  - default:false
# --logTiming=true            # Shows colored timing metrics - default:true
# --pageRouteRoot=<root_dir>  # page URLs root - default: react-page/src

# for example:
node server.js --useSourceMaps=true

Node Modules in the Browser: You can use modules installed via npm, but if anything requires builtin modules (such as util), make sure to enable the useBrowserBuiltins option.

React As A Blogging Engine:

React can power dynamic, network-connected apps. But with react-page, React can also be used to build a static blog, Github documentation, or any other static site. Because react-page uses server rendering, creating a static site is as easy as a single wget command.

node server.js
wget -mpck --user-agent="" -e robots=off http://localhost:8080/index.html

Get wget on OS X: try http://osxdaily.com/2012/05/22/install-wget-mac-os-x/ or if you have brew: brew install wget

This prebuilds your entire interactive site, so it can be served from a file server or github etc. Don't forget to enable gzip on your file server! React markup is large but compresses very well.

Motivations/Next-Steps:

-react-page is a rapid development environment for experimenting with new ways of building production web apps powered by React. It provides a common environment that allows sharing of modules client/server architecture prototypes.

In order to use this technology in a production environment, you must audit and verify that the server rendering strategy is safe and suitable for your purposes.

TODO: