react-tinacms-contentful

A library for using Contentful with TinaCMS and React.js

• react-tinacms-contentful
  • Usage
    • Installation
    • Setup
    • Media
  • APIs
    • Provider
    • Hooks

Usage

Installation

To install the package, run:

npm install react-tinacms-contentful tinacms-contentful contentful contentful-management

Setup

To setup TinaCMS with Contentful, you must create an instance of the TinaCMS ContentfulClient for each space you want to edit content from.

For a single space:

import React, { useMemo } from 'React'
import { TinaProvider } from 'tinacms'
import { ContentfulClient } from 'tinacms-contentful'

export default function MyApp() {
  const cms = useMemo(() => {
    const contentful = new ContentfulClient({
      spaceId: /* Contentful Space ID */,
      defaultEnvironmentId: /* Contentful environment ID to use by default. Default: master */,
      accessTokens: {
        delivery: /* Contentful delivery access token for the space */,
        preview: /* Contentful preview access token for the space */,
      }
      clientId: /* OAuth App Client ID */,
      redirectUrl: /* OAuth App Callback URL */,
      rateLimit: /* API Rate Limit for your Contentful Plan (Requests per second). Default: 4 */,
      insecure: /* If true, uses same-site HTTPS cookies to create a session. Default: false */
    })

    return new TinaCMS({
      apis: {
        contentful
      }
    })
  });

  return (
    <TinaProvider cms={cms}>
      <TinaContentfulProvider>
        <div>Hello world</div>
      </TinaContentfulProvider>
    </TinaProvider>
  )
}

Or if the CMS has already been created:

import { useCMS } from 'tinacms'

export default function MyComponent() {
  const cms = useCMS();

  useEffect(() => {
    const contentful = new ContentfulClient({
      spaceId: /* Contentful Space ID */,
      defaultEnvironmentId: /* Contentful environment ID to use by default. Default: master */,
      accessTokens: {
        delivery: /* Contentful delivery access token for the space */,
        preview: /* Contentful preview access token for the space */,
      }
      clientId: /* OAuth App Client ID */,
      redirectUrl: /* OAuth App Callback URL */,
      rateLimit: /* API Rate Limit for your Contentful Plan (Requests per second). Default: 4 */,
      insecure: /* If true, uses same-site HTTPS cookies to create a session. Default: false */
    })

    cms.registerApi('contentful', contentful)
  }, [])

  return (
    <div>Hello world!</div>
  )
}

For multiple spaces:

import React, { useMemo } from 'React'
import { TinaProvider } from 'tinacms'
import { createContentfulClientForSpaces } from 'tinacms-contentful';

export default function MyApp() {
  const cms = useMemo(() => {
    const spaces = [
      {
        spaceId: /* Contentful Space ID */,
        defaultEnvironmentId: /* Contentful environment ID to use by default. Default: master */,
        accessTokens: {
          delivery: /* Contentful delivery access token for the space */,
          preview: /* Contentful preview access token for the space */,
        }
      },
      {
        spaceId: /* Contentful Space ID */,
        defaultEnvironmentId: /* Contentful environment ID to use by default. Default: master */,
        accessTokens: {
          delivery: /* Contentful delivery access token for the space */,
          preview: /* Contentful preview access token for the space */,
        }
      }
    ]

    const contentful = createClientForSpaces(spaces, {
      clientId: /* OAuth App Client ID */,
      redirectUrl: /* OAuth App Callback URL */,
      rateLimit: /* API Rate Limit for your Contentful Plan (Requests per second). Default: 4 */,
      insecure: /* If true, uses same-site HTTPS cookies to create a session. Default: false */
    })

    return new TinaCMS({
      apis: {
        contentful
      }
    })
  });

  return (
    <TinaProvider cms={cms}>
      <TinaContentfulProvider>
        <div>Hello world</div>
      </TinaContentfulProvider>
    </TinaProvider>
  )
}

Media

To add support for media, you must setup a media store for the space media should be uploaded to.

For a single space:

import React, { useMemo } from 'React'
import { TinaProvider } from 'tinacms'
import { ContentfulClient, ContentfulMediaStore } from 'tinacms-contentful'

export default function MyApp() {
  const cms = useMemo(() => {
    const contentful = new ContentfulClient({
      spaceId: /* Contentful Space ID */,
      defaultEnvironmentId: /* Contentful environment ID to use by default. Default: master */,
      accessTokens: {
        delivery: /* Contentful delivery access token for the space */,
        preview: /* Contentful preview access token for the space */,
      }
      clientId: /* OAuth App Client ID */,
      redirectUrl: /* OAuth App Callback URL */,
      rateLimit: /* API Rate Limit for your Contentful Plan (Requests per second). Default: 4 */,
      insecure: /* If true, uses same-site HTTPS cookies to create a session. Default: false */
    })
    const contentfulMediaStore = new ContentfulMediaStore(contentful)

    return new TinaCMS({
      apis: {
        contentful
      },
      media: contentfulMediaStore
    })
  });

  return (
    <TinaProvider cms={cms}>
      <TinaContentfulProvider>
        <div>Hello world</div>
      </TinaContentfulProvider>
    </TinaProvider>
  )
}

For multiple spaces:

The media store is only capable of acting on a single space at a time. To change spaces dynamically, run:

import React, { useMemo } from 'React'
import { TinaProvider } from 'tinacms'
import { ContentfulClient, ContentfulMediaStore } from 'tinacms-contentful'

+export default function MyApp(currentSpaceId) {
      const spaces = [
      {
        spaceId: /* Contentful Space ID */,
        defaultEnvironmentId: /* Contentful environment ID to use by default. Default: master */,
        accessTokens: {
          delivery: /* Contentful delivery access token for the space */,
          preview: /* Contentful preview access token for the space */,
        }
      },
      {
        spaceId: /* Contentful Space ID */,
        defaultEnvironmentId: /* Contentful environment ID to use by default. Default: master */,
        accessTokens: {
          delivery: /* Contentful delivery access token for the space */,
          preview: /* Contentful preview access token for the space */,
        }
      }
    ]

    const contentful = createClientForSpaces(spaces, {
      clientId: /* OAuth App Client ID */,
      redirectUrl: /* OAuth App Callback URL */,
      rateLimit: /* API Rate Limit for your Contentful Plan (Requests per second). Default: 4 */,
      insecure: /* If true, uses same-site HTTPS cookies to create a session. Default: false */
    })

+    const contentfulMediaStore = new ContentfulMediaStore(contentful[currentSpaceId])

    return new TinaCMS({
      apis: {
        contentful
      },
      media: contentfulMediaStore
    })
  });

  return (
    <TinaProvider cms={cms}>
      <TinaContentfulProvider>
        <div>Hello world</div>
      <TinaContentfulProvider>
    </TinaProvider>
  )
}

APIs

The library has the following core APIs:

• ContentfulClient: an API client for communicating with Contentful that integrates directly with the CMS.
• ContentfulMediaStore: a media store that uses a ContentfulClient to manage media for a single space.
• Provider: a React provider for official plugins and authorization.
• Hooks: a series of React Hooks for interacting with Contentful in your React app and CMS Plugins.

There are other public APIs as well. To learn more, read the full React API documentation or read the full JavaScript API documentation.

Provider

When using Contentful with TinaCMS and React, you must wrap the CMS-enabled portions of your app with the TinaContentfulProvider:

  return (
    <TinaProvider cms={cms}>
      <TinaContentfulProvider>
        <div>Hello world</div>
      <TinaContentfulProvider>
    </TinaProvider>
  )

Hooks

• useContentful: retreives the ContentfulClient off of the CMS, and allows specifying a space ID when using multiple spaces.
• useContentfulDelivery: retreives a delivery client from the ContentfulClient and allows specifying a space ID when using multiple spaces.
• useContentfulPreview: retreives a preview client from the ContentfulClient and allows specifying a space ID when using multiple spaces.
• useContentfulManagement: retreives a management client from the ContentfulClient and allows specifying a space ID when using multiple spaces.
• useContentfulEntry: fetches an entry from contentful and returns the entry, loading constant, and error constant, and allows specifying a space ID when using multiple spaces.
• useContentfulEntries: fetches multiple entries from contentful and returns the entry, loading constant, and error constant, and allows specifying a space ID when using multiple spaces.
• useContentfulEntryForm: creates a TinaCMS form for a given entry, which can be registered with the CMS or used to provide editing UIs to end users.
• useContentfulEntriesForm: creates a TinaCMS form for multiple entries, which can be registered with the CMS or used to provide editing UIs to end users.
• useContentfulAuthRedirect: sets up a route to be used as the callback URL for an OAuth application.