@nypl/web-reader 4.1.0 → 4.3.0

package/README.md

@@ -1,15 +1,20 @@
 # NYPL Web Reader
 
-This project is a web reader built by NYPL for reading eBooks. It is built using the [Readium Architecture](https://github.com/readium/architecture), and specifically built for Webpubs. Webpub is a spec [defined by the Readium Foundation](https://github.com/readium/webpub-manifest) to provide a common abstraction between many types of web publications. Initially, this project will focus on HTML-based Webpubs and Webpubs that define PDF collections. An HTML-based Webpub can be generated from many types of eBooks, but most commonly ePubs.
+This project is a web reader built by NYPL for reading eBooks. It was designed using the [Readium Architecture](https://github.com/readium/architecture), and specifically built for Webpubs. Webpub is a spec [defined by the Readium Foundation](https://github.com/readium/webpub-manifest) to provide a common abstraction between many types of web publications. This project currently focuses on HTML-based Webpubs and Webpubs that define PDF collections. An HTML-based Webpub can be generated from many types of eBooks, but most commonly ePubs.
 
-The project is built with [esbuild](https://esbuild.github.io/). It uses Typescript, React, Jest and Cypress, and features both a Storybook development environment and an example application under `/example`. The example is deployed here: https://nypl-web-reader.vercel.app.
+## Demo - Example App
 
-A big thanks to [R2D2BC](https://github.com/d-i-t-a/R2D2BC) for providing the underlying HTML navigator capabilities.
+This project features an example application under `/example`, which is deployed here: https://nypl-web-reader.vercel.app.
 
-## Demo
+## Built With
 
-- [Example reader app](https://nypl-web-reader.vercel.app)
-- [Storybook deployment](https://web-reader-storybook.vercel.app)
+- [esbuild](https://esbuild.github.io/) - JavaScript bundler for the web-reader package
+- [react-pdf](https://react-pdf.org/) - For creating PDF files on the browser and server
+- [chakra-ui](https://chakra-ui.com/) - For styling the default UI components
+- [TypeScript](https://www.npmjs.com/package/typescript) - JavaScript with syntax for types
+- [React](https://www.npmjs.com/package/react) - For creating user interface components
+- [Jest](https://jestjs.io/) & [React Testing Library](https://testing-library.com/) - For writing unit tests
+- The Example App is packaged with [Parcel](https://parceljs.org/) & deployed with [Vercel](https://vercel.com/). Integration tests are run with [Cypress](https://www.cypress.io/).
 
 ## Features
 
@@ -23,17 +28,17 @@ A big thanks to [R2D2BC](https://github.com/d-i-t-a/R2D2BC) for providing the un
   - [x] Fullscreen
   - [x] Paginated / Scrolling mode toggle
   - [x] Zoom (PDF only)
-- [x] Offline support (prefetch and cache desired content via Service Worker, along with host app shell.
-- [ ] Saving bookmarks / highlights
 - [x] WAI-ARIA compliant accessibility
 - [x] Integration tested
+- [ ] Offline support (prefetch and cache desired content via Service Worker, along with host app shell)
+- [ ] Saving bookmarks / highlights
 
-## Example
+## Examples
 
 Basic usage within a React app, using the default UI:
 
 ```typescript
-import WebReader from 'nypl/web-reader';
+import WebReader from '@nypl/web-reader';
 
 const ReaderPage = ({ manifestUrl }) => {
   return (
@@ -45,96 +50,32 @@ const ReaderPage = ({ manifestUrl }) => {
 };
 ```
 
-Passing a content decryptor to the reader for use by the Client. This would be how we render AxisNow content for example:
-
-```typescript
-import WebReader from "nypl/web-reader"
-import AxisNowDecryptor from "nypl/axisnow-access-control-web"
-
-const ReaderPage = ({manifestUrl}) => {
-  const decryptor = new AxisNowDecryptor(...);
-  return (
-	  <WebReader
-      getContent={decryptor.getContent}
-      manifestUrl={manifestUrl}
-    />
-  )
-}
-```
-
-To support customization, you can piece together your own UI and call the `useWebReader` hook to get access to the reader API.
+- [More React examples](/example/index.tsx) - Includes examples that render EPUB2 & EPUB3 based webpubs, remote hosted webpubs, and PDFs
+- [Encrypted example](/example/axisnow-encrypted.tsx) - How to pass an content decryptor to the web-reader to render encrypted content
+- [usePDFReader hook example](/example/use-pdf-reader.tsx) - Useful for instances when you know you're only going to be using the web-reader to open PDFs
+- [useHTMLReader hook example](/example/use-html-reader.tsx) - Useful for cases when you know you're only going to be using the web-reader to read EPUBs
+- [Real-world example: Open eBooks Web](https://github.com/NYPL/ereading-clients/blob/staging/apps/oew/src/components/theme-ui/WebReader.tsx) - NYPL application for children to read books on the web. This demonstrates how encrypted AxisNow content is passed to the web-reader.
+- [Real-world example: Digital Research Books (DRB)](https://github.com/NYPL/sfr-bookfinder-front-end/blob/development/src/components/ReaderLayout/ReaderLayout.tsx) - NYPL application that collects digital versions of research books into one convenient place to search.
 
-```typescript
-import { useWebReader, ReaderNav, ReaderFooter } from 'nypl/web-reader';
+## Required Fonts
 
-const CustomizedReaderPage = ({ webpubManifestUrl }) => {
-  // takes a manifest, instantiates a Navigator, and
-  // returns the Navigator, interaction handlers, and
-  // the current state of the reader as an object
-  const reader = useWebReader({
-    webpubManifestUrl,
-  });
+In order for the Settings panel to be displayed as intended, the fonts Roboto, Georgia, and OpenDyslexic must be available to your application. Georgia is web safe, meaning it is installed by default on most devices, but the others are not. One way to include them is to copy them from the `fonts` folder in `@nypl/web-reader/example/static` into your `/public` directory. Alternatively, for Roboto, you can embed the Google Font into the <head> of your html (directions [here](https://fonts.google.com/specimen/Roboto)).
 
-  return (
-    <div>
-      {/* eg. keep default header, but change its background */}
-      <ReaderNav {...reader} className="bg-blue" />
+## Required CSS Injectables for the HTML Reader (EPUBs)
 
-      {/* we can add custom prev/next page buttons */}
-      <button onClick={reader.handleNextPage}>Next</button>
-      <button onClick={reader.handlePrevPage}>Prev</button>
+**Note:** This section does not apply to PDFs
 
-      {/* you will receive content from the reader to render wherever you want */}
-      {reader.content}
+The HTML Reader can inject `<style>` tags (and other tags) into the reader iframe itself, called an "injectable". This is used to add styles to the html content of the publication.
 
-      {/* use the default footer */}
-      <ReaderFooter {...reader} />
-    </div>
-  );
-};
-```
+In order for the web-reader to render EPUBs correctly and display the OpenDyslexic font, there are some files that you must import into your application and inject into the `<WebReader />`. Those files are as follows:
 
-If you know you are only going to be using one type of reader, you can also call the hook just for that reader:
+1. The `opendyslexic` font
+2. The three default Readium stylesheets
 
-```typescript
-import { usePdfReader } from 'nypl/web-reader';
+We export the Readium CSS stylesheets compiled under `@nypl/web-reader/dist/injectable-html-styles/*.css`. These css files can then be imported via webpack as a url to a static file that is copied to the dist folder. You can then use this url in your injectable config.
 
-const MyPdfReader = ({ webpubManifestUrl, manifest }) => {
-  const reader = usePdfReader({ manifest, webpubManifestUrl });
-
-  return <div>{reader.content}</div>;
-};
-```
-
-Finally, to use in a vanilla Javascript app:
-
-```html
-<div id="web-reader" />
-<script>
-  const readerDiv = document.getElementById('web-reader');
-  renderReader(readerDiv, {
-    manifestUrl: xxx,
-  });
-</script>
-```
-
-## Styling
-
-Most styling is included in the basic UI, but we also ship a few css files that must be included:
-
-1. Both the HTML and the PDF side have css that is necessary to be included for the dependencies we use to render correctly. This is built automatically into `@nypl/web-reader/dist/esm/index.css` and `@nypl/web-reader/dist/cjs/index.css`. Depending which package you are using, you should include one of those files in your bundle.
-1. The HTML Reader can inject `<style>` tags (and other tags) into the reader iframe itself, called an "injectable". This is used to add styles to the html content of the publication. More on this is below.
-
-In order for the Settings panel to be displayed as intended, the fonts Roboto, Georgia, Helvetica, and OpenDyslexic must be available to your application. Georgia is web safe, meaning it is installed by default on most devices, but the others are not. One way to include them is to copy the `fonts` folder and its contents from `@nypl/web-reader/example/static` into your `/public` directory.
-
-## Injectables
-
-The HTML Reader has the ability to inject custom elements into the reader iframe. This is most useful for passing stylesheets and fonts, but other elements can be injected too. It is recommended to pass the `opendyslexic` font and the default Readium stylesheets as injectables to the iframe.
-
-In the below example, we show two different ways to do this.
-
-1. We export the Readium CSS stylesheets compiled under `@nypl/web-reader/dist/injectable-html-styles/*.css`. These css files can then be imported via webpack as a url to a static file that is copied to the dist folder. You can then use this url in your injectable config.
-2. The `fontInjectable` uses a plain url to a css file that we host normally on our site. In this case you would be responsible for copying the css file into your source code and making sure it is hosted at some location.
+**Example:**
+You will need to install `file-loader`, `extract-loader`, and `css-loader` and import the files you need like this:
 
 ```ts
 import readiumBefore from '!file-loader!extract-loader!css-loader!@nypl/web-reader/dist/injectable-html-styles/ReadiumCSS-before.css';
@@ -155,6 +96,8 @@ const cssInjectables: Injectable[] = [
     url: readiumAfter,
   },
 ];
+
+// The `fontInjectable` uses a plain url to a css file that we host normally on our site. In this case you would be responsible for copying the css file into your source code and making sure it is hosted at some location.
 const fontInjectable: Injectable = {
   type: 'style',
   url: `${origin}/fonts/opendyslexic/opendyslexic.css`,
@@ -166,39 +109,106 @@ const htmlInjectables = [...cssInjectables, fontInjectable];
 const Reader = () => {
   return (
     <WebReader
-      injectables={htmlInjectables}
+      injectablesReflowable={htmlInjectables}
       webpubManifestUrl="example/manifest.json"
     />
   );
 };
 ```
 
-**Note:** Injectables do not apply to pdf reading.
+A real-world [example](https://github.com/NYPL/sfr-bookfinder-front-end/blob/development/src/components/ReaderLayout/ReaderLayout.tsx) can be seen in the Digital Research Books project.
+
+Alternatively, you can host those three Readium CSS files within your project and import them wherever you render the <WebReader />. This is what we are doing in [Open eBooks](https://github.com/NYPL/ereading-clients/tree/staging/apps/oew/public/css/readium), which enables us to support offline reading mode.
+
+### injectablesFixed vs. injectablesReflowable
+
+There are two different injectables props you can pass to the web reader.
+
+- `injectablesReflowable` is used by HTML-based text books, or any content that makes sense to be resized based on the screen size. For most cases, this is where you should add the Readium CSS files mentioned above.
+- `injectablesFixed` is being used in Open eBooks as a way to style picture books. It could also be used to style other formats like audio and video files.
+
+Your app can provide both props or only one. The reader will decide which one to load into the iframe based on the book format defined in the webpub manifest.
+
+## Other Injectables
+
+You can import and inject other files into the `<WebReader />` to customize behavior. For example, in Open eBooks, we import some [custom JavaScript](https://github.com/NYPL/ereading-clients/blob/staging/apps/oew/src/components/theme-ui/WebReader.tsx#L65) to disable right clicking & copying copywritten content.
+
+## Custom Styling
+
+Basic default styling is included in the basic UI. We are using [Chakra](https://chakra-ui.com/) to style the default UI components. You can wrap our UI components in your own `<ThemeProvider>` to pass your own custom theme.
 
 ## Errors
 
-We make every effort to throw useful errors. Your app should probably wrap the web reader component in a React `<ErrorBoundary>` to either display the thrown errors or a custom error state for your users in the case one is thrown. See the example app for an example using an Error Boundary.
+We make every effort to throw useful errors. Your app should probably wrap the web reader component in a React `<ErrorBoundary>` to either display the thrown errors or a custom error state for your users in the case one is thrown.
+
+## Modifying PDF Manifests
+
+In some cases it may be desirable to modify the Webpub Manifest before passing it to the web reader. One example of this is with single-resource PDFs. These manifests sometimes arrive without a table of contents. The information for the TOC is embedded in the single PDF file itself. In this situation, we have set up a utility to extract the PDF TOC and add it to the manifest. There is an example of this working at [`/pdf/single-resource-short`](https://nypl-web-reader.vercel.app/pdf/single-resource-short).
+
+In order to make this work in your app, you will want to:
+
+1. Fetch your manifest
+1. Use `addTocToManifest` to add the table of contents
+1. Generate a synthetic URL for the in-memory JSON object
+1. Pass this generated URL to the web reader.
+
+<details>
+<summary>See the example code</summary>
+
+```ts
+const fetchAndModifyManifest: Fetcher<string, string> = async (url) => {
+  const response = await fetch(url);
+  const manifest = await response.json();
+  const modifiedManifest = await addTocToManifest(
+    manifest,
+    getProxiedResource(pdfProxyUrl),
+    pdfWorkerSrc
+  );
+  const syntheticUrl = URL.createObjectURL(
+    new Blob([JSON.stringify(modifiedManifest)])
+  );
+  return syntheticUrl;
+};
 
-# Development
+const SingleResourcePdf = () => {
+  const { data: modifiedManifestUrl, isLoading } = useSWR<string>(
+    '/samples/pdf/single-resource-short.json',
+    fetchAndModifyManifest
+  );
+
+  if (isLoading || !modifiedManifestUrl) return <div>Loading...</div>;
+
+  return (
+    <WebReader
+      webpubManifestUrl={modifiedManifestUrl}
+      proxyUrl={pdfProxyUrl}
+      pdfWorkerSrc={`${origin}/pdf-worker/pdf.worker.min.js`}
+    />
+  );
+};
+```
+
+</details>
 
 ## Architecture
 
-### Overview
+One of the primary architectural goals of the web reader is to abstract away the particularities of the many individual publication formats by using a common manifest to describe all publication types. This is the [Readium Webpub Manifest](https://readium.org/webpub-manifest/profiles/epub.html). This allows the web-reader to consume Webpub Manifests, not manipulate or generate them.
+
+- ePubs are generally run through a Streamer, which fetches the full compressed ePub, generates a manifest for it, and then serves the individual pieces separately. Processing EPUBs into Webpub Manifests can be done with a Readium Streamer or some other way. [epub-to-webpub](https://github.com/NYPL/ePub-to-webpub) is used in the [Open eBooks](https://github.com/NYPL/ereading-clients/tree/staging/apps/oew) project and generates Webpub Manifests from EPUBs and the web-reader consumes them. Digital Research Books generates Webpub manifests for EPUBs using a [Python script](https://github.com/NYPL/drb-etl-pipeline/blob/main/managers/webpubManifest.py).
+- On the PDF side, we don't have a shared utility for generating manifests, but the Digital Research Books project does use a [Python script](https://github.com/NYPL/drb-etl-pipeline/blob/main/managers/webpubManifest.py) to pre-generate PDF manifests from web-scraped content before sending them to the web-reader. These manifests are then stored in an S3 bucket.
 
-We always start with a Webpub Manifest, which gives us metadata and the structure of the publication with links to the content. Depending on the `metadata.conformsTo` field, we know which type of reader to use to render the publication. Each media type (HTML for EPUBS, PDF for PDF publications, etc) has its own `use_X_Reader` hook (`usePdfReader`, `useHtmlReader`, etc).
+A Webpub Manifest gives us metadata and the structure of the publication with links to the content. Depending on the `metadata.conformsTo` field, we know which type of reader to use to render the publication. Each media type (HTML for EPUBS, PDF for PDF publications, etc) has its own `use_X_Reader` hook (`usePdfReader`, `useHtmlReader`, etc).
+
+C4 Models have been created to demonstrate how the WebReader and other web reading utilities interact with the DRB & Open eBooks apps. View them here: https://structurizr.com/share/72104
 
 **Notes:**
 
 - There is one `use_X_Reader` per _media-type_ (PDF, HTML, Image, etc), not per _format_. As in, ePub and Mobi books are different formats that use the same media type (HTML). Audiobooks and PDF collections use different media types. We currently only have plans for HTML and PDF, but other hooks are welcome and should fit right in.
-- We always start from a Webpub Manifest. This means other formats (like ePub) need to be processed before they get to us. This can be done with a Readium Streamer, or some other way.
-  - For example, DRB is pre-generating PDF manifests from web-scraped content.
-  - There is [nypl/epub-to-webpub](https://github.com/NYPL/ePub-to-webpub) to generate Webpub Manifests from EPUBS.
-  - ePubs are generally run through a Streamer, which is a piece that fetches the full compressed ePub, generates a manifest for it, and then serves the individual pieces separately.
-  - AxisNow encrypted ePubs are served uncompressed. We will generate the manifest for them on the client before instantiating the reader.
+- AxisNow encrypted ePubs are served uncompressed. We will generate the manifest for them on the client before instantiating the reader.
 
-### Pieces of the architecture:
+### Pieces of the Architecture
 
-1. **use_X_Reader hook**
+1. **use_X_Reader Hook**
 
 - Takes in the Webpub Manifest and returns:
   - `State` of the reader, such as current settings and location.
@@ -207,7 +217,7 @@ We always start with a Webpub Manifest, which gives us metadata and the structur
 - Internally, it will instantiate whatever package is being used to control that media type, and render the contents into the `Content` element it returns.
 - Each hook for each media type separately manages its own state using a redux-style `useReducer` hook. There is a basic set of common state that is shared and returned from the `use_X_Reader` hook, but custom internal state can also be added, such as the `D2Reader` instance in the `useHtmlReader` hook.
 
-2. **useWebReader hook**
+2. **useWebReader Hook**
 
 - This is a generic hook that works for both PDF manifests and HTML-type manifests. It will internally call the proper `use_X_Reader` hook for you, and pass through the return value.
 
@@ -221,7 +231,7 @@ We always start with a Webpub Manifest, which gives us metadata and the structur
 This is the folder structure:
 
 ```txt
-/cypress            # cypress tests will go in here
+/cypress            # cypress integration tests
 /example            # example app packaged by Parcel
   index.html
   index.tsx         # entrypoint for the demo app
@@ -235,9 +245,7 @@ This is the folder structure:
   types.ts          # commonly used types
   useWebReader.tsx  # the React hook providing the main API into the reader
 /test
-  blah.test.tsx     # tests will go in here
-/stories            # stories will go in here
-/.storybook         # storybook config
+  blah.test.tsx     # unit tests go here
 ```
 
 ### Decryption
@@ -249,41 +257,37 @@ The web reader does support DRM via two possible routes:
 
 The `AxisNow Encrypted EPUB` example shows how this is done using the private NYPL AxisNow decryptor. The AxisNow scheme is a specific DRM technique not publicly available and the repo and code for the decryptor cannot be shared. Thus this example will not work for the public, but you can read the example code to see how we use the private `Decryptor` package to:
 
-- Create a Web Worker using Comlink](https://github.com/GoogleChromeLabs/comlink) that will performe the fetching and decryption. This should help keep the main thread free while those heavy tasks are performed.
+- Create a Web Worker using [Comlink](https://github.com/GoogleChromeLabs/comlink) that will perform the fetching and decryption. This should help keep the main thread free while those heavy tasks are performed.
 - Fetch content from the network
 - Decrypt the HTML content
 - Search for embedded CSS and image assets
 - Fetch those assets and decrypt them
-- Re-embed the decrypted CSS and image assets as Object URLs into the decrypted HTML document.
-- Return the HTML string with fully decrypted reources for the web-reader to render in the iframe.
-
-## Commands
+- Re-embed the decrypted CSS and image assets as Object URLs into the decrypted HTML document
+- Return the HTML string with fully decrypted reources for the web-reader to render in the iframe
 
-Before getting started, be sure to run `npm install`.
+## Getting Started
 
-The recommended workflow is to either run the storybook app, or the example app:
+These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See [Publishing to NPM](#publishing-to-npm) for notes on how to publish a new version to NPM.
 
-### Storybook
+### Prerequisites
 
-Run in `/web-reader`:
+1. Before getting started, be sure to run `npm install`.
 
-```bash
-npm run start
-```
+If you are internal to NYPL you can be added to the private `@nypl-simplified-packages/axisnow-access-control-web` package, which is required in order to open the AxisNow Encrypted EPUB example. If you decide to install this package, you'll also need to generate a Personal Access Token in GitHub with `read` permissions and run `GH_PACKAGE_AUTH_TOKEN=<your-token-here> npm install`.
 
-Then in another terminal:
+2. In order to open any of the PDF examples in the Example App, you'll need to allow urls in a `WebpubManifest` to be proxied. This is done by passing a `proxyUrl` to the `<WebReader>` component. In order to do that, you must have a proxy running somewhere.
 
-```bash
-npm run storybook
-```
+We have set up a small express-based CORS proxy that can be run for local development.
 
-This loads the stories from `./stories`.
+- Run the proxy with `npm run cors-proxy`.
+- Pass the proxy url to the example app by setting the following env var in a `.env` file at the root of the project: `CORS_PROXY_URL="http://localhost:3001/?requestUrl="`.
+- In a separate terminal session, start the example app: `npm run example`.
 
-> NOTE: Stories should reference the components as if using the library. This means importing from the root project directory. This has been aliased in the tsconfig and the storybook webpack config as a helper.
+3. In order to open the AxisNow Encrypted EPUB example (`/html/axisnow-encrypted`), you will need to have `process.env.VAULT_UUID` and `process.env.ISBN` set in your `.env` file. Read [example/README.txt](/example/README.txt) for more info.
 
-### Example
+### Running the Example App
 
-To run the example app:
+To run the example app for local development:
 
 ```bash
 npm run example
@@ -291,31 +295,47 @@ npm run example
 
 The example will rebundle on change, but you have to refresh your browser to see changes (no hot reloading currently).
 
-#### Service Worker on localhost
+## Development Notes
 
-To develop with the service worker in the example app, you will need to run the app using HTTPS locally, and you will need to enable the service worker. We have disabled it by default because otherwise your development changes will never be reflected in the browser (since old JS will be served from the cache). You can run the app with https and the service worker enabled via the script:
+### Performance Optimizations
 
-```
-npm run example:sw
+Please see the main `tsdx` [optimizations docs](https://github.com/palmerhq/tsdx#optimizations). In particular, know that you can take advantage of development-only optimizations:
+
+```js
+// ./types/index.d.ts
+declare var __DEV__: boolean;
+
+// inside your code...
+if (__DEV__) {
+  console.log('foo');
+}
 ```
 
-If this HTTPS setup doesn't work for you, you may need to follow [this guide](https://web.dev/how-to-use-local-https/) to generate your own certificates or trust ours.
+You can also choose to install and use [invariant](https://github.com/palmerhq/tsdx#invariant) and [warning](https://github.com/palmerhq/tsdx#warning) functions.
 
-**NOTE:** Developing with the SW can be tricky. You will need to clear the CacheStorage of your browser whenever you make changes to your JS in dev mode. Hard refreshing your browser is not enough. I also suggest enabling `update on reload` in Chrome dev tools under `Application>Service Worker`.
+### Module Formats
 
-### CORS Proxy
+CJS and ESModules module formats are supported.
 
-We sometimes run in to CORS errors, and have a system to allow urls in a `WebpubManifest` to be proxied. This is done by passing a `proxyUrl` to the `<WebReader>` component. In order to do that, you must have a proxy running somewhere.
+The appropriate paths are configured in `package.json` and `dist/index.js` accordingly. Please [report](https://github.com/NYPL-Simplified/web-reader/issues) if any issues are found.
 
-#### CORS Proxy in the Example App
+## Running the Tests
 
-I have set up a small express-based CORS proxy that can be run for local development.
+### Unit Tests with Jest
 
-- Run the proxy with `npm run cors-proxy`.
-- Pass the proxy url to the example app by setting the following env var in a `.env` file at the root of the project: `CORS_PROXY_URL="http://localhost:3001/?requestUrl="`.
-- In a separate terminal session, start the example app: `npm run example`.
+To run Jest in watch mode:
+
+```bash
+npm run test
+```
+
+To run all the tests as they run in CI:
+
+```bash
+npm run test:ci
+```
 
-### Cypress
+### Integration Tests with Cypress
 
 The tests we have are located in the `cypress/integration` folder.
 
@@ -333,60 +353,30 @@ To run tests on your terminal without a browser:
 npm run cypress:cli
 ```
 
-### Other Scripts
-
-- `npm run test` - to run Jest in watch mode.
-- `npm run size` - to calculate the real cost of the library for consumers (using [size-limit](https://github.com/ai/size-limit)).
-- `npm run analyze` - to analyze the library bundle for places we can shrink down.
-
-## Code Quality
+## Code Quality & Bundle Size Checks
 
-Code quality enforcement is set up with `prettier`, `husky`, and `lint-staged`. Run `npm run lint` to lint the code, or have you editor do it.
-
-## Styling / CSS
-
-We are using [Chakra](https://chakra-ui.com/) to style our default UI components. You can wrap our UI components in your own `<ThemeProvider>` to pass your own custom theme.
+- `npm run lint` to lint the code yourself. Code quality enforcement is set up in pre-commit hooks with `prettier`, `husky`, and `lint-staged`.
+- `npm run size` - to calculate the real cost of the library for consumers (using [size-limit](https://github.com/ai/size-limit))
+- `npm run analyze` - to analyze the library bundle for places we can shrink down
 
 ## Continuous Integration
 
-### GitHub Actions
-
-There are two Github Workflows:
-
-- `main` which installs deps w/ cache, lints, tests, and builds on all pushes against a Node and OS matrix
-- `size` which comments cost comparison of your library on every pull request using [size-limit](https://github.com/ai/size-limit)
-
-## Optimizations
-
-Please see the main `tsdx` [optimizations docs](https://github.com/palmerhq/tsdx#optimizations). In particular, know that you can take advantage of development-only optimizations:
-
-```js
-// ./types/index.d.ts
-declare var __DEV__: boolean;
-
-// inside your code...
-if (__DEV__) {
-  console.log('foo');
-}
-```
+There are three Github Actions Workflows:
 
-You can also choose to install and use [invariant](https://github.com/palmerhq/tsdx#invariant) and [warning](https://github.com/palmerhq/tsdx#warning) functions.
+- `main` - installs deps w/ cache, lints, tests, and builds on all pushes against a Node and OS matrix
+- `size` - comments cost comparison of your library on every pull request using [size-limit](https://github.com/ai/size-limit)
+- `cypress` - runs the Cypress integration tests on Vercel deployments, which means it runs whenever a pull request is opened or updated
 
-## Module Formats
+## Versioning
 
-CJS and ESModules module formats are supported.
+We use [SemVer](https://semver.org/) for versioning. For the versions available, see the [releases](https://github.com/NYPL-Simplified/web-reader/releases) on this repository.
 
-The appropriate paths are configured in `package.json` and `dist/index.js` accordingly. Please report if any issues are found.
-
-## Deploying the Example Playground
+## Publishing to NPM
 
-The Playground is just a simple [Parcel](https://parceljs.org) app, you can deploy it anywhere you would normally deploy that. We have deployed it to Vercel. Here is how you build a standalone version:
+To publish the package to [NPM](https://www.npmjs.com/package/@nypl/web-reader), you must first be added to the `nypl` organization within NPM.
 
-```bash
-cd example # if not already in the example folder
-npm run build # builds to dist
-```
+Run `npm run release` from the main branch. Follow the prompts to add a new version, publish a release to github, and push to npm.
 
-## Publishing to NPM
+## License
 
-Run `npm run release` from the main branch. Follow the prompts to add a new version, publish a release to github, and push to npm.
+This project is licensed under the MIT License - see the [LICENSE](/LICENSE) file for details.