> ## Documentation Index
> Fetch the complete documentation index at: https://webviewer-docs.mupdf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

## Install

Grab the package on NPM with:

```bash theme={null}
npm install mupdf-webviewer
```

## Prepare your DOM

Ensure that your HTML page where you want to use **MuPDF WebViewer** has a dedicated DOM node available with the `id` you require, e.g.

```html theme={null}
<div id="viewer"></div>
```

## Initialization

Once ready you should initialize with [initMuPDFWebViewer()](/api-reference/introduction#initmupdfwebviewer).

**Example**

```javascript theme={null}
import { initMuPDFWebViewer } from 'mupdf-webviewer';

initMuPDFWebViewer(
  '#viewer',
  'https://webviewer.mupdf.com/assets/demo/mupdf-book.pdf',
)
  .then(webViewer => {
    /* API */
  })
  .catch(err => {
    /* Error handling */
  });
```

<Note>
  File paths to PDFs should be absolute paths.
</Note>

### Optionally set the library path

The main JavaScript viewer libraries will be served from CDN by default, however you can choose to self-host these files by setting the `libraryPath` option during initialization.

One of the benefits of self-hosting is that you can reference the files with *relative paths* from your own domain.

#### Copy the library assets

The library folder for **MuPDF WebViewer** is required to be copied to a library path of your choosing.

<CodeGroup>
  ```bash Bash theme={null}
  cp -r node_modules/mupdf-webviewer/lib/* {YOUR_LIBRARY_PATH}/
  ```

  ```powershell PowerShell theme={null}
  Copy-Item -Path "node_modules/mupdf-webviewer/lib/*" -Destination "{YOUR_LIBRARY_PATH}/"
  ```
</CodeGroup>

#### Set the library path during initialization

Then set the `libraryPath` option during initialization to point to your chosen path.

**Example**

```javascript theme={null}
import { initMuPDFWebViewer } from 'mupdf-webviewer';

initMuPDFWebViewer(
  '#viewer',
  'sample.pdf',
  { libraryPath: 'lib' },
)
  .then(webViewer => {
    /* API */
  })
  .catch(err => {
    /* Error handling */
  });
```

In the case above our library path is simply "lib".

<Note>
  File paths to PDFs can be *relative* or *absolute* paths if you are self-hosting the library files.
</Note>

## Running

You should be able to run on your local machine's browser.

The following local domains work out of the box:

* `localhost`
* `127.0.0.1`
* `*.test`

## Trial License

For local development a license key is *not required*, however for deployment to production, a license key *is required* to use **MuPDF WebViewer**. Visit [MuPDF WebViewer](https://webviewer.mupdf.com/pricing) to obtain your trial license.

Use the `licenseKey` option during initialization to set your license key.

**Example**

```javascript theme={null}
import { initMuPDFWebViewer } from 'mupdf-webviewer';

initMuPDFWebViewer(
  '#viewer',
  'https://webviewer.mupdf.com/assets/demo/mupdf-book.pdf',
  { licenseKey: 'YOUR_LICENSE_KEY' },
)
  .then(webViewer => {
    /* API */
  })
  .catch(err => {
    /* Error handling */
  });
```

<Note>
  When deploying to the web don't forget that a license key is required & specific to the domain you registered the key against.
</Note>

## Opening Files

You can open local and remote files with MuPDF Webviewer. You can also open files as blob URLs if required.

### Local files

Depending on your integration you can open local files with absolute or relative paths, as follows:

#### Absolute paths

Supply the absolute path to your file as follows:

**Example**

```javascript theme={null}
webViewer.document.open({ url: `/doc/my-file.pdf` });
```

#### Relative paths

Supply the relative path to your file as follows:

**Example**

```javascript theme={null}
webViewer.document.open({ url:"../../doc/my-file.pdf" });
```

### Remote files

Supply the URL to your file as follows:

**Example**

```javascript theme={null}
webViewer.document.open({ url: "https://example.com/my-file.pdf" });
```

<Warning>
  Remote PDF files shuold ensure to have the correct CORS permissions set. See the [warning in the API docs for `document.open` and remote files](/api-reference/document/index#open-warning).
</Warning>

### Loading Files as Blob URLS

If you want to use [blob URLs](https://developer.mozilla.org/en-US/docs/Web/API/Blob), then MuPDF WebViewer can use that for the file data. The example below converts a PDF into a blob URL then opens it:

**Example**

```javascript theme={null}
async function openWithBlobURL(url) {
  const response = await fetch(url);
  const blob = await response.blob();
  const blobUrl = URL.createObjectURL(blob);
  webViewer.document.open({ url: blobUrl });
}

openWithBlobURL('/file.pdf')
```

See the [Sample Projects](/sample-projects) for more.