This project is not actively maintained. Proceed at your own risk!
-
Render [React](http://www.github.com/facebook/react/) pages on the server or client - _effortlessly_.
-
Use CommonJS to build and share UI components.
-
Develop rapidly - instant reloading.
##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?
- Faster Pages: Markup displayed before downloading JS (with SEO benefits)
- Page generation on a fast server vs. low power client devices.
- Instantly refresh while developing.
- Static content sites: As easy as a single
wgetcommand.
Why React?
- React is a client/server rendering framework from the ground up.
- When performance constraints change, simply change where you render it - don't change your app.
- React is functional. Explore the documentation on the React Github Page.
- Server rendering optional - you can always just use React as a declarative client side framework.
##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
- Currently, every
htmlrouting must map to a.jsfile that exports a single React component, that renders the page, includinghtml/bodytags. - Routing is customizable (more later).
How Does Server Rendering Work?
react-pagecomputes page markup on the server, sends it to the client so the user can see it quickly.- The corresponding JavaScript is then packaged and sent.
- The browser runs that JavaScript, so that all of the event handlers, interactions and update code will run seamlessly on top of the server generated markup.
- From the developer's (and the user's) perspective, it's just as if the rendering occurred on the client, only faster.
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.
-
You must ensure that a proper server sandbox is enforced. However,
react-pagedoes run your UI rendering code inside of contextify as a preliminary sandbox. -
In production, the js packaging features of
react-pageshould be performed ahead of time and stored in a CDN. However, dynamic server rendering is a compelling production feature. -
Additional connect middleware should be added to prevent stack traces from showing up in browser.
TODO:
- Windows support (depends on fixing facebookarchive/node-haste#2)
- Allow sharing of css/images through npm packages.
- Experiments with optimizing page load time - incremental streaming of markup/resources.
- Advanced packaging such as splitting projects into several independently cacheable sub-packages.
- require('image/path/img.jpg') should resolve to image path.
- A way to automatically package/bundle css, regardless of file path of depending js resource. (using require('commonJSPath/to/css.css'))