Skip to content


Subversion checkout URL

You can clone with
Download ZIP
ReadiumJS viewer: default web app for Readium.js library
HTML JavaScript Other
Failed to load latest commit information.
chrome-app Added minimum chrome version
css ensure no unwanted scroll bar in div containers, see
epub_content Move the reading system book to the back of the list so it fixes the …
fonts First alpha of chrome extension for Feb release
grunt Addresses #289 (comment)
i18n Merge branch 'lmvco-patch-2' of…
images readium logos for touch-icon and favicon
lib build and submodule
logos First alpha of chrome extension for Feb release
readium-js @ 9e09854 Updating readium-js submodule
templates Updated to bootstrap 3.3.2 and added bootstrap accessibility plugin
tests Attempt to fix the build
.gitignore Updated build to handle deployment. Updated submodule.
.gitmodules Update .gitmodules
.travis.yml Removed encryption to see if it is the problem with the build
Gruntfile.js Merging test refactoring Update
deployCrx.js #92, fixing typo
divshot.json Adding cache control to the divshot config
embed.html Changes for embedded viewer and added icon for annotations button
extend_require_config.js addresses the issue about the missing build/version.json file in non-…
index.html Updated to bootstrap 3.3.2 and added bootstrap accessibility plugin
license.txt Changed the BSD-style license from BSD_license.txt to simply license.txt
package.json Bumped version to x.18.1
require_config.js jQuery update to latest, renamed so that future updates do not requir…
simpleviewer.html minor: just triggering a new build on Travis (failed submodule refere…

ReadiumJS Viewer

Welcome to the ReadiumJS viewer project. This project encapsulates several applications.

  • A basic EPUB viewer
  • A Chrome packaged app for managing an EPUB library and reading EPUBs.
  • A generic EPUB library management and viewer application that requires you to implement your own backend

The viewer is the default viewer for Readium.js, a JS library for rendering EPUB files on any modern browser, via any web server. If you'd like to learn more, check out the ReadiumJS website](, and/or source on Github. ReadiumJS is in early development and it is not yet recommended that you use it for production deployment of EPUB files.

Getting started

Initialize your repository

ReadiumJS uses git submodules to embed other repositories and it uses Node.js and associated tools and libraries. Do the following steps to be up and running:

  • Install Node.js (details depend on your operating system)
  • Install the Grunt build tool using the command line: npm install -g grunt-cli (requires at least version 0.4.4)
  • From the command line run git clone
  • From the command line run cd readium-js-viewer
  • From the command line run git submodule update --init --recursive
  • install Node.JS
  • From the command line run npm install -g grunt-cli
  • From the command line run npm install (in the readium-js-viewer directory)
  • From the command line run cd readium-js
  • From the command line run npm install (a second time in the readium-js directory)
  • From the command line run cd ..
  • You should now be able to run the grunt commands specified below.

Basic EPUB Viewer

Visit online demo

There easiest way to see the Readium Cloud Reader in action is to navigate to the CloudReader instance here. The content hosted there isn't that interesting since it is aimd primarily at providing a frequently updated instance of the CloudReader that can be crowd-tested. We are working on a more interesting instance and will post the link here soon.

Clone into your own web server

To test the ReadiumJS viewer on any static web server:

  • Perform the above steps and clone into a content directory in your web server (e.g. into a "www/readium-js-viewer" folder)
  • For zipped EPUB files support, configure your web server for HTTP Byte Serving so that Readium.js library can fetch only the necessary portions of a zipped EPUB file that contain content for the displayed page
  • Visit yourdomain/readium-js-viewer/simpleviewer.html?epub=epub_content/moby_dick and enjoy!
  • There is no step three! (but it is not recommended to deploy the build-related files onto a publicly-accessible server)

Clone and run an embedded Node.JS web server

You can also use the Grunt build configuration contained in cloned sources to run an embedded Node.JS + Express web server that serves the demo application:

One of advantages of the embedded Node.JS + Express web server is that it supports HTTP Byte Serving out of the box, without additional configuration, required for efficient handling of zipped EPUB files.

Add additional EPUBs

The viewer uses the epub url query parameter to find the ebook to display. The project comes with several epubs already (look under the epub_content directory). To add a new EPUB simply unzip an epub to be anywhere on the same server as the viewer. Example steps:

  • unzip any (*) valid (**) .epub file (EPUB 2 or EPUB 3 version) in the "epub_content" directory
  • navigate to http://localhost:8080/simpleviewer.html?epub=epub_content/new_book_directory

(*) NOTE1: This is somewhat aspirational; as Readium.js is still in early development not all EPUB 3 features are yet supported in - see issues trackers for the consituent sub-projects for more info

(**) NOTE2: "valid" means EPUBCHeck 3.0 reports zero errors. At this time Readium.js does not have robust error handling

Use the latest Readium.js library version

The Grunt build configuration also contains an optional task that builds the latest versions of Readium.js library files and places them in the lib/ directory.

Assuming that you have Grunt and project's dependencies already installed (see above), in order to run this task, execute the following command:

grunt update-readium

Embeddable EPUB Viewer

You can host an embeddable epub viewer using the same instructions as the Basic EPUB viewer. For example, if you wanted to add epub content to a blog or similar.

Follow the same instructions as setting up the Basic EPUB viewer then embed the epub reader using an iframe like so

<iframe width="600" height="400" src="http://localhost:8080/simpleviewer.html?epub=epub_content/moby_dick&amp;embedded=true" style="border:1px #ddd solid;" allowfullscreen mozallowfullscreen webkitallowfullscreen></iframe>

Note the embedded=true query parameter. This adds a special UI and handling for a smaller screen. See the embed.html file in the root of the source tree for a complete example that works with the Basic EPUB viewer setup.

Chrome Packaged App

To run the chrome packaged app, you will need to initialize your repository and then:

  • Build the application with grunt chromeApp
  • Load the app as an unpacked extension from (project-root)/build/chrome-app. Directions here
  • Open the App in Chrome under chrome://apps

Custom EPUB management and viewer application

The code that runs the chrome packaged app can also be run on a web server. However, it requires a backend to store and retrieve EPUB files. You would have to implement this yourself. You can see this in action by following the directions to run a node web server and then navigating to http://localhost:8080/index.html. The backend the example uses is just static files so it doesn't support updating.

Alternatively you can build a package using either of the following two commands:

grunt cloudReader
grunt cloudReaderWithEpub; # Comes with ePubs bundled

Running the Tests

The viewer project contains some basic regression tests. These are run using chromedriver, Selenium WebdriverJS, and nodeunit. The tests target the chrome packaged app. Assuming you have already followed the steps above to run the packaged app, these are the additional steps if you want to run the tests

  • Install chromedriver for your platform and ensure it's on your system path somewhere.
  • Install the Google Chrome browser or have it already installed in the default install location for your platform.
  • run grunt test

Licensing info

Licensing information can be found in the file license.txt in the root of the repo, as well as in the source code itself.

Something went wrong with that request. Please try again.