Skip to content

Latest commit

 

History

History
208 lines (148 loc) · 7.25 KB

README.md

File metadata and controls

208 lines (148 loc) · 7.25 KB
Raw

react-native-readium

NPM version Commitizen friendly PRs welcome! This project is released under the MIT license

Have A Bug/Feature You Care About?

We ❤️ open source. We work on the things that are important to us when we're able to work on them. Have an issue you care about?

Overview

A react-native wrapper for https://readium.org/. At a high level this package allows you to do things like:

  • Render an ebook view.
  • Register for location changes (as the user pages through the book).
  • Register for the Table of Contents (so that you can display things like chapters in your app)
  • Control settings of the Reader. Things like:
    • Dark Mode, Light Mode, Sepia Mode
    • Font Size
    • Page Margins
    • More (see the Settings documentation in the API section)
  • Etc. (read on for more details. 📖)

Table of Contents

Dark Mode Light Mode
Dark Mode Light Mode

Installation

Prerequisites

  1. iOS: Requires an iOS target >= 13.0 (see the iOS section for more details).
  2. Android: Requires compileSdkVersion >= 31 (see the Android section for more details).

Install Module

NPM

npm install react-native-readium

Yarn

yarn add react-native-readium

iOS

Due to the current state of the Readium swift libraries you need to manually update your Podfile (see more on that here).

# ./ios/Podfile
...
platform :ios, '13.0'

...

target 'ExampleApp' do
  config = use_native_modules!
  ...
  pod 'GCDWebServer', podspec: 'https://raw.githubusercontent.com/readium/GCDWebServer/3.7.5/GCDWebServer.podspec', modular_headers: true
  pod 'R2Navigator', podspec: 'https://raw.githubusercontent.com/readium/swift-toolkit/2.6.0/Support/CocoaPods/ReadiumNavigator.podspec'
  pod 'R2Shared', podspec: 'https://raw.githubusercontent.com/readium/swift-toolkit/2.6.0/Support/CocoaPods/ReadiumShared.podspec'
  pod 'R2Streamer', podspec: 'https://raw.githubusercontent.com/readium/swift-toolkit/2.6.0/Support/CocoaPods/ReadiumStreamer.podspec'
  pod 'ReadiumInternal', podspec: 'https://raw.githubusercontent.com/readium/swift-toolkit/2.6.0/Support/CocoaPods/ReadiumInternal.podspec'
  pod 'Minizip', modular_headers: true
  ...
end

Finally, install the pods:

pod install

Android

If you're not using compileSdkVersion >= 31 you'll need to update that:

// android/build.gradle
...
buildscript {
    ...
    ext {
        ...
        compileSdkVersion = 31
...

Usage

import React, { useState } from 'react';
import { ReadiumView } from 'react-native-readium';
import type { File } from 'react-native-readium';

const MyComponent: React.FC = () => {
  const [file] = useState<File>({
    url: SOME_LOCAL_FILE_URL,
  });

  return (
    <ReadiumView
      file={file}
    />
  );
}

Take a look at the Example App for a more complex usage example.

Supported Formats & DRM

Format Support

Format Support Notes
Epub 2 ✅
Epub 3 ✅
PDF ❌ On the roadmap, feel free to submit a PR or ask for direction.
CBZ ❌ On the roadmap, feel free to submit a PR or ask for direction.

Missing a format you need? Reach out and see if it can be added to the roadmap.

DRM Support

DRM is not supported at this time. However, there is a clear path to support it via LCP and the intention is to eventually implement it.

API

View Props

Name Type Optional Description
file File ❌ A file object containing the path to the eBook file on disk.
location Locator | Link ✅ A locator prop that allows you to externally control the location of the reader (e.g. Chapters or Bookmarks).

⚠️ If you want to set the location of an ebook on initial load, you should use the File.initialLocation property (look at the file prop). See more here
settings Partial<Settings> ✅ An object that allows you to control various aspects of the reader's UI (epub only)
style ViewStyle ✅ A traditional style object.
onLocationChange (locator: Locator) => void ✅ A callback that fires whenever the location is changed (e.g. the user transitions to a new page)
onTableOfContents (toc: Link[] | null) => void ✅ A callback that fires once the file is parsed and emits the table of contents embedded in the file. Returns null or an empty [] if no TOC exists. See the Link interface for more info.

⚠️ Web vs Native File URLs

Please note that on web the File.url should be a web accessible URL path to the manifest.json of the unpacked epub. In native contexts it needs to be a local filepath to the epub file itself on disk. If you're not sure how to serve epub books take a look at this example which is based on the dita-streamer-js project (which is built on all the readium r2-*-js libraries)

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

Release

The standard release command for this project is:

yarn version

This command will:

  1. Generate/update the Changelog
  2. Bump the package version
  3. Tag & pushing the commit

e.g.

yarn version --new-version 1.2.17
yarn version --patch // 1.2.17 -> 1.2.18

Sponsor The Library

If you'd like to sponsor a specific feature, fix, or the library in general, please reach out on an issue and we'll have a conversation!

License

MIT