@citydna/datocms v1.8.0

@citydna/datocms

!!! DEPRECATED !!!

📜 <DatoCMSProvider /> and scripts for easy DatoCMS integration and happy developers.

DatoCMS is a headless CMS with a robust GraphQL API and a great user interface. It's the tool of choice when creating content-heavy citydna apps. There's a bit of setup required to get it working with apollo tooling though, so we've done that for you.

We've also included some scripts that make typescript development awesome and jest testing your graphql components an absolute breeze.

Installation

$ yarn add @citydna/datocms @apollo/react-hooks graphql graphql-tag

Component usage

1. add REACT_APP_DATO_CMS_TOKEN=<YOUR_DATO_TOKEN> into your .env file*
2. Wrap your app with <DatoCMSProvider />
3. Start writing GraphQL queries with @apollo/react-hooks and gql:

import React from "react"
import { useQuery } from "@apollo/react-hooks"
import gql from "graphql-tag"

const PostList = () => {
  const { data } = useQuery(GetPosts)
  return data?.allPosts.map(post => <h1>{post.title}</h1>)
}

const GetPosts = gql`
  query GetPosts {
    allPosts {
      title
    }
  }
`

*Alternatively, pass the token in as a prop to DatoCMSProvider, though don't check it in to git:

const App = () => {
  const { datoToken } = useAuthenticatedUserSomehow();
  return <DatoCMSProvider token={datoToken}>{...}</DatoCMSProvider>
}

Generating Typescript types (unfinished)

This package provides a yarn script for automatically generating Typescript types based on your DatoCMS schema.

$ yarn citydna datocms gql-gen

Or put it in your scripts property in package.json:

{
  ...
  "scripts": {
    ...,
    "gql-gen": "yarn citydna datocms gql-gen"
  }
}

This will create types in your src folder:

src/
  __generated__/
    graphql-types.ts

You can then use these to strongly type your DatoCMS queries. Here's an example where we get a post by it's slug (found in a route match from react-router-dom)

import React from "react"
import { useQuery } from "@apollo/react-hooks"
import { useParams } from "react-router-dom"
import {
  GetPostsQuery,
  GetPostsQueryVariables,
} from "./__generated__/graphql-types"

const ShowPost = () => {
  const { slug } = useParams()
  // pass in the query response type and variables type to the query as type args
  const { data, loading } = useQuery<GetPostsQuery, GetPostsQueryVariables>(
    GET_POSTS,
    {
      variables: { slug },
    }
  )

  // intellisense will autocomplete data.post.title as you type it.
  return !loading && data && <div>{data?.post?.title}</div>
}

export const GET_POSTS = gql`
  query GetPost($slug: String) {
    post(filter: { slug: { eq: $slug } }) {
      id
      title
      content
    }
  }
`

It also provides *Record types so you can spread the result of a query onto a component for use. Continuing from the example above, Let's move that title into its own component. Given this trivial PostTitle component

import React from "react"
import { PostRecord } from "./__generated__/graphql-types"

// Pass in a Partial type of PostRecord the React Functional Component props type args
interface PostTitleProps extends Partial<PostRecord> & Pick<PostRecord, 'title'> {};

// PostTitle will now accept all PostRecord data spread onto it, and will require 'title' to be passed in.
export const PostTitle: React.FC<PostTitleProps> = ({ title }) => <h1>{title}</h1>

We can refactor our ShowPost above to include it with the returned data:

...
const ShowPost = () => {

  const { data, loading } = useQuery<GetPostsQuery, GetPostsQueryVariables>(
    GET_POSTS,
    ...
  )

  return !loading && data?.post && <PostTitle {...data.post}>
}
...

This makes the developer experience in VSCode absolutely awesome.

Elsewhere, you might be using <PostTitle /> without the full query response. VSCode knows what props you can pass in as you type it.

Generating mock data for your tests (unfinished)

haha! thought you could get away without testing your components. Luckily this package has the following script:

$ yarn citydna datocms mock-data

What this will do is go through your folders, find queries and execute them against DatoCMS, storing the result for use in your jest tests. If no variables are provided to your queries (as in the case here), DatoCMS will just return the first result.

src/
  ShowPost/
    __generated__/
      GET_POST-result.json
    ShowPost.tsx
    ShowPost.test.tsx

Your test then might look something like this:

import React from 'react';
import {render} from '@testing-library/react';
import {MockProvider} from "@apollo/react-testing";
impoer { PostRecord } from '../__generated__/gql-types';
import { ShowPost, GET_POST as query } from './ShowPost';
import result from './__generated__/GET_POST-result.json';

describe("<ShowPost />", () => {
  test("should render the post title", async () => {
    // arrange
    const mocks = [{
      request: { query }
      result
    }]

    const { findByText } = render(
      <MockProvider mocks={mocks}>
        <ShowPost />
      </MockProvider>
    );

    // assert
    expect(await findByText(result?.data.post.title)).toBeInTheDocument();
  })
})

The benefit of this is that even if your data changes, you can simply run yarn citydna datocms gql-gen && yarn citydna datocms mock-data and it'll update everything with the latest schema and data.