Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ryanhefner/react-prismic

📰 Easily compose Prismic requests and data into your React applications.
https://github.com/ryanhefner/react-prismic

api fetch prismic prismic-javascript query react react-component react-component-library react-hoc

Last synced: 2 days ago
JSON representation

📰 Easily compose Prismic requests and data into your React applications.

Host: GitHub
URL: https://github.com/ryanhefner/react-prismic
Owner: ryanhefner
License: mit
Created: 2019-08-09T14:59:49.000Z (about 5 years ago)
Default Branch: master
Last Pushed: 2023-01-06T02:06:26.000Z (over 1 year ago)
Last Synced: 2024-09-02T11:18:10.631Z (about 1 month ago)
Topics: api, fetch, prismic, prismic-javascript, query, react, react-component, react-component-library, react-hoc
Language: JavaScript
Homepage: https://www.pkgstats.com/pkg:@ryanhefner/react-prismic
Size: 1.95 MB
Stars: 3
Watchers: 2
Forks: 0
Open Issues: 13
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE

Awesome Lists containing this project

README

        # 📰 react-prismic

[![npm](https://img.shields.io/npm/v/@ryanhefner/react-prismic?style=flat-square)](https://www.npmjs.com/package/@ryanhefner/react-prismic)

[![NPM](https://img.shields.io/npm/l/@ryanhefner/react-prismic?style=flat-square)](https://www.npmjs.com/package/@ryanhefner/react-prismic)

[![npm](https://img.shields.io/npm/dt/@ryanhefner/react-prismic?style=flat-square)](https://www.npmjs.com/package/@ryanhefner/react-prismic)

Easily compose [Prismic](https://prismic.io) requests and data into your React applications.

## Install

Via [npm](https://npmjs.com/package/@ryanhefner/react-prismic)

```sh

npm install --save @ryanhefner/react-prismic

```

Via [Yarn](https://yarn.pm/@ryanhefner/react-prismic)

```sh

yarn add @ryanhefner/react-prismic

```

## How to use

The goal of `react-prismic` is to take the thinking out of initializing a client

and making requests, and focused on making it easy to quickly setup and access

the data that you need from [Prismic](https://prismic.io) in your React apps.

### `PrismicProvider`

The `PrismicProvider` allows you to define a scope/client to used for your next

`PrismicQuery`s. In most setups, you’ll probably only need one instance of this,

composed around your main app. But, if you happen to have another section or component

or your app that needs to interface with a different Prismic repo, you can compose

these wherever you like and all nested `PrismicQuery`s will use the client for

each.

#### Props

* `repo: string` - The name of the Prismic repo you plan on querying.

> This is name that is before `.prismic.io` when you are looking at your repo in Prismic.

> `repo` should be good for 94.6% of instances when using this class. If you want

> to get fancy, the following `props` are also available for you.

* `api: PrismicApi` - If you’re already initialzing an instance of the Prismic API outside of the `PrismicProvider`, you can pass that in to keep using that same one.

> If you have a reason to override the Prismic API witth your own logic, like

> hitting your own custom endpoint, it should be assumed that your instance of

> the Prismic API matches the interface of the original.

* `client: PrismicClient` - Client that will be used to make requests against Prismic.

* `cache: Cache | iterable | string` - Cache instance to initialize the `client` cache with.

* `renderPromises: RenderPromises` - Passed in via [`next-prismic`](https://github.com/ryanhefner/next-prismic) for requesting and rendering requests during server-side rendering.

#### Example

```js

import React from 'react';

import { PrismicProvider } from 'react-prismic';

import Component from './Component';

const App = () => (

  

    

  

);

```

### `PrismicQuery`

This is where the magic happens ✨ Easily compose Prismic queries into your React applications.

Instead of getting crafty with some unmappable props -> method fiasco, I’ve just

exposed all the available methods from the [`Prismic - ResolvedApi`](https://prismicio.github.io/prismic-javascript/classes/resolvedapi.html)

as props to make it easy to choose the method that best suits your needs without

another API to learn.

The only caveat to this is, instead of just passing in an array of arguments to

the methods, I’ve mapped an object to the function args. It feels more React-y

when using it, but I’m also open to a discussion on a better way to handle these

since the prop list is rather verbose right now.

> For more details about the Prismic API, I highly recommend that you reference

> their [`prismic-javascript` documentation](https://prismicio.github.io/prismic-javascript/index.html).

#### Props

* `currentExperience: boolean`

* `everything: boolean`

* `getBookmark: { bookamark, options?, callback }`

* `getByID: { id, options?, callback? }`

* `getByIDs: { ids, options?, callback? }`

* `getByUID: { type, uid, options?, callback? }`

* `getSingle: { type, options?, callback? }`

* `master: boolean`

* `previewSession: { token, linkResolver, defaultUrl, callback? }`

* `query: { query, options?, callback? }`

* `queryFirst: { query, options?, callback? }`

* `prismicRef: { label }` - This is the one method that doesn’t map directly to the existing API, since it conflicts with React’s native `ref` prop.

* `skip: boolean` - Skip the request during server-side rendering.

* `onError: ({ data, error, loading, fetch }) => {}` - Called when an error is encountered during the request.

* `onLoad: ({ data, error, loading, fetched }) => {}` - Called when the request has finished loading.

* `onRequest: ({ data, error, loading, fetched }) => {}` - Called when the request has been initiated.

#### Example

```js

import React from 'react';

import { PrismicQuery } from 'react-prismic';

import { RichText } from 'prismic-reactjs';

const Component = () => (

  

    

      

        {({ data, error, fetched }) => {

          if (!fetched) {

            return null;

          }

          if (error) {

            console.error(error);

            return null;

          }

          const {

            name,

            logo,

            logoLink,

            headerLinks,

          } = data.data;

          return (

            

              


                

                  {logo && }

                  {name}

                

              

              

                {headerLinks && headerLinks.value.map(headerLink => (

                  

                    {headerLink.link_title.value.text}

                  

                ))}

              

            

          );

        }}

      

    

    

      

        {({ data, error, fetched}) => {

          ...

        }}

      

    

    

      

        {({ data, error, fetched }) => {

          ...

        }}

      

    

  

);

export default Component;

```

### `withPrismic`

Have another type of component in mind to use within your `PrismicProvider`?

By using `withPrismic` you can expose the `prismic` context to your component

and utilize whatever is available. (Pssst...this is what the `PrismicQuery`

component is using.)

#### Context

* `client: PrismicClient` - Use this to make requests, access the cache, or whatever else you might want to do.

* `renderPromises: RenderPromises` - This is typically only set during server-side rendering (used by `next-prismic`), but available just letting you know in case you might need it.

#### Example

```js

import React from 'react';

import { withPrismic } from 'react-prismic';

const Component = ({ prismic }) => {

  const {

    client,

  } = prismic;

  [do something with client]

};

export default withPrismic(Component);

```

### `PrismicClient`

Again, this is one of those classes that you’ll rarely have to interface with

since the `PrismicProvider` takes care of instantiating an instance for you. But,

in an effort of making truly open, open source software, here is a little breakdown

of the `PrismicClient`

#### Options

* `api: PrismicClient` - Available for the wild ones, the dreamers, the mavericks. Pass in your own Prismic API interface in the event you need to do some low-level shenanigans.

* `cache: Cache` - Internally this package uses [`creature-cache`](https://github.com/ryanhefner/creature-cache), but there’s nothing preventing you from using something else, as long as you implement your’s with the same interface.

* `repo: string` - String of the Prismic repo you are planning to access.

> This is name that is before `.prismic.io` when you are looking at your repo in Prismic. (ex. `your-repo.prismic.io`, the `repo` would be `your-repo`)

#### Example

```js

import { PrismicClient } from 'react-prismic';

const prismicClient = new PrismicClient({

  repo: '[name of prismic repo, ex. `your-repo` of your-repo.prismic.io]'

});

```

## Using Next.js?

If you like what you see above, you might like [@ryanhefner/next-prismic](https://github.com/ryanhefner/next-prismic),

which lets you easily add `react-prismic` to your Next.js app, making it easy

to ensure that all your `PrismicQuery` instances render awesomely server-side.

## License

[MIT](LICENSE) © [Ryan Hefner](https://www.ryanhefner.com)