Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    rndr-mepublic

    rndr.me is a tiny http server that eats urls and poops html. It has only one dependency, PhantomJS, which it uses evaluate each incoming url in a headless browser window, and output the html of the resulting DOM.

    Build Status

    Having an easy, framework-agnostic way to create html snapshots helps solve two problems in single-page JavaScript app deployment:

    1. Single-page apps suffer from poor crawlability, because Google/Bing are less likely to discover content rendered on the client. In this case, use rndr.me to render the _escape_fragment_ urls that these crawlers want, by redirecting from your backend.

    2. Single-page apps suffer from slow startup times, due to multiple round trips between the app and API. In this case, you can use rndr.me to pre-render hot pages, so that they can be inlined as HTML to improve perceived performance.

    Of course, this is just one approach for folks looking for way to improve SEO and performance when rendering single-page apps. If you're using Backbone.js and want a more tightly coupled solution, check out @airbnb's rendr. If you're looking for something a bit higher-level that'll run a cluster for you, check out @bfirsh's otter.

    Installation

    1. Install PhantomJS.
    2. Download server.js from this repo OR npm install rndr-me

    Sample setup

    In this example shell script, we:

    • create a simple JavaScript app,
    • serve it on port 8000,
    • run rndr.me on port 8001, and
    • verify the app html as rendered by rndr.me.
    #!/bin/sh 
     
    # Create and save a simple JavaScript app 
    echo "<script>document.write(location)</script>" > ./index.html
     
    # Spin up a server to serve it 
    python -m SimpleHTTPServer 8000 &
    APP_PID=$!
     
    # Spin up the rndr.me server, wait until ready 
    phantomjs ./server.js &
    rndrme_PID=$!
    sleep 1
     
    # Pick an app URL to be rendered 
    URL='http://127.0.0.1:8000/#!/TESTING'
     
    # Get the results rendered by the rndr.me server 
    HTML=`curl 127.0.0.1:8001 -s -G --data-urlencode href=$URL`
     
    # Check whether the rendered file contains the random URL 
    echo $HTML | grep -q $URL
    NOT_FOUND=$?
     
    # Spin down, clean up, and exit 
    rm ./index.html
    kill -9 $rndrme_PID
    kill -9 $APP_PID
    exit $NOT_FOUND

    Quickstart on Heroku

    Because rndr.me depends only on PhantomJS, it's easy to set up and run yourself. This example shell script shows you everything you need to start your own instance running on Heroku.

    # Create a place for your renderer to live 
    mkdir my_renderer
    cd my_renderer
     
    # Create a git repo with rndr.me and a Procfile 
    git init
    git submodule add git://github.com/jed/rndr.me.git
    echo "web: phantomjs rndr.me/server.js" > Procfile
     
    # Create a new Heroku app with the PhantomJS buildpack 
    heroku apps:create
    heroku config:add BUILDPACK_URL=https://github.com/stomita/heroku-buildpack-phantomjs.git
     
    # Push your code 
    git add .
    git commit -m "first commit"
    git push heroku master
     
    # Scale your app 
    heroku ps:scale web=1

    API

    To spin up the server, run the following from the command line:

    phantomjs ./server.js <config-path>
    

    Note that config-path is optional, and if omitted will default to the provided config.js file. You may also override any options from the config file using options on the command line:

    phantomjs ./server.js --port 8002 --ready_event onRender
    

    The server exposes a single root endpoint at /. It returns generated html, based on the following parameters:

    • href: The url to be rendered. This is required, and must be fully qualified.
    • max_time: The maximum number of milliseconds until render. Any windows not already rendered by the ready_event will be rendered once this elapses. This is optional, and 30000 by default (30 seconds).
    • max_bytes: The maximum number of incoming bytes. Any windows that load more than this value will return an error without rendering. This is optional, and 1048576 by default (1 MiB).
    • load_images: This can be specified to any value to load document images. This is optional, and omitted by default.
    • ready_event: This is the name of the window event that triggers render. This is optional, and load by default. To specify when rendering occurs, such as when the DOM is not ready to be rendered until after window.onload, trigger a DOM event manually, such as follows (using jQuery in this case):
    jQuery.getJSON("http://api.myapp.com", function(data) {
      myCustomRenderingCallback(data)
     
      var readyEvent = document.createEvent("Event")
      readyEvent.initEvent("renderReady", true, true)
      window.dispatchEvent(readyEvent)
    })

    Examples

    The following examples assume a single-page app running in production at http:/myapp.com and rndr.me running as follows:

    phantomjs ./server.js --port 8080

    Let's render the app with default settings:

    curl localhost:8080 -G \
      --data-urlencode 'href=http://myapp.com/#!home'

    Now let's cap the maximum rendering time at 10 seconds:

    curl localhost:8080 -G \
      --data-urlencode 'href=http://myapp.com/#!home'
      -d max_time=10000

    We can also cap the maximum incoming bytes at 100KiB:

    curl localhost:8080 -G \
      --data-urlencode 'href=http://myapp.com/#!home'
      -d max_time=10000
      -d max_bytes=102400

    Now let's allow images to load, raising the maximum incoming bytes to 500KiB:

    curl localhost:8080 -G \
      --data-urlencode 'href=http://myapp.com/#!home'
      -d max_time=10000
      -d max_bytes=512000
      -d load_images

    Now let's use the custom rendering event render_ready, triggered on the window of the DOM, using the default fallback maximum time:

    curl localhost:8080 -G \
      --data-urlencode 'href=http://myapp.com/#!home'
      -d max_bytes=512000
      -d load_images
      -d ready_event=render_ready

    LICENSE

    (The MIT License)

    Copyright (c) 2013 Jed Schmidt <where@jed.is>

    Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

    The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

    Keywords

    install

    npm i rndr-me

    Downloadsweekly downloads

    2

    version

    1.0.0

    license

    MIT

    repository

    githubgithub

    last publish

    collaborators

    • avatar