kevinydhan/gatsby-with-query

[WIP] A higher-order component used to decouple Gatsby's static queries

gatsby-with-query

withQuery is a higher-order component that is used to decouple Gatsby's static queries.

Table of Contents

• Installation
• Usage

Installation

npm i gatsby-with-query

yarn add gatsby-with-query

Usage

Create the following:

• your GraphQL query using Gatsby's graphql()
• a React hook which invokes Gatsby's useStaticQuery() and returns either all or a subset of your component's props

// App.query.tsx
import { graphql, useStaticQuery } from 'gatsby'

const query = graphql`
  query GetSiteMetadata {
    site {
      siteMetadata {
        title
        description
      }
    }
  }
`

const useGetSiteMetadataQuery = () => {
  const queriedProps = useStaticQuery(query)
  return queriedProps.site.siteMetadata
}

export default useGetSiteMetadataQuery

Then, import the React hook and withQuery() into your component's file:

// App.tsx
import React, { FunctionComponent } from 'react'
import withQuery from 'gatsby-with-query'
import useGetSiteMetadataQuery from './App.query'

interface AppProps {
  title: string
  description: string
}

export const App: FunctionComponent<AppProps> = ({ title, description }) => (
  <main>
    <h1>{title}</h1>
    <p>{description}</p>
  </main>
)

export default withQuery<AppProps>(App, useGetSiteMetadataQuery)

Alternatively, you can have your React component, GraphQL query, and React query hook in the same file:

// App.tsx
import React, { FunctionComponent } from 'react'
import { graphql, useStaticQuery } from 'gatsby'
import withQuery from 'gatsby-with-query'

interface AppProps {
  title: string
  description: string
}

export const App: FunctionComponent<AppProps> = ({ title, description }) => (
  <main>
    <h1>{title}</h1>
    <p>{description}</p>
  </main>
)

const query = graphql`
  query GetSiteMetadata {
    site {
      siteMetadata {
        title
        description
      }
    }
  }
`

export default withQuery<AppProps>(App, () => {
  const queriedProps = useStaticQuery(query)
  return queriedProps.site.siteMetadata
})

gatsby-with-query's Issues

Find a way for withQuery() to infer the type definition for the component's props

Currently, withQuery() is a generic function. The developer has to explicitly define their prop's type definition:

export default withQuery<AppProps>(App, () => {
  // ...
})

It would be nice if withQuery() can automatically infer the type definition for the component's props:

interface AppProps {
  title: string
  description: string
}

const App: FunctionComponent<AppProps> = ({ title, description }) => (
  <main>
    <h1>{title}</h1>
    <p>{description}</p>
  </main>
)

export default withQuery(App, (receivedProps) => {
  // receivedProps is either a subset of AppProps or AppProps
})

I can possibly utilize Parameters<T> to infer the component's props.

Provide support for Gatsby's StaticQuery

A possible feature would be to provide support for <StaticQuery>. However, the immediate issue is that it seems unnecessary to utilize <StaticQuery> as demonstrated below:

// App.tsx
import React, { FunctionComponent } from 'react'
import { graphql, StaticQuery } from 'gatsby'
import withQuery from 'gatsby-with-query'

interface AppProps {
  title: string
  description: string
}

export const App: FunctionComponent<AppProps> = ({ title, description }) => (
  <main>
    <h1>{title}</h1>
    <p>{description}</p>
  </main>
)

const query = graphql`
  query GetSiteMetadata {
    site {
      siteMetadata {
        title
        description
      }
    }
  }
`

// Possibly something like this? 
export default withQuery<AppProps>(() => (
  <StaticQuery query={query}>
    {(queriedProps) => <App {...queriedProps} />}
  </StaticQuery>
))

WithQueryHOC type definition expects all props from parent component

In the following type definition for WithQuery:

import { FunctionComponent } from 'react'

type WithQuery = <Props = Record<string, never>>(
  Component: FunctionComponent<Props>,
  useQueryHook: () => Props
) => FunctionComponent<ReturnType<typeof useQueryHook>>

useQueryHook()'s return type should be one of the following:

1. all of the component's props
2. a subset of the component's props

In addition, the parameter for the WithQueryHOC component should also be one of the two cases:

1. all of the component's props
2. a subset of the component's props

---

Considering these two requirements, a possible type definition would be to use Partial<T> for both useQueryHook()'s return value and the parameter for the WithQueryHOC component:

import { FunctionComponent } from 'react'

type WithQuery = <Props = Record<string, never>>(
  Component: FunctionComponent<Props>,
  useQueryHook: () => Partial<Props>
) => FunctionComponent<ReturnType<typeof useQueryHook>>

However, this poses the problem where calling React.createElement() with partial props will trigger a TypeScript warning.

Expose the type definition for the receivedProps parameter in useQueryHook

If a developer wanted to create a standalone React query hook, they will most likely have to explicitly type their hook to utilize IntelliSense for receivedProps:

// receivedProps will be type `any`
const useGetSiteMetadataQuery = (receivedProps) => {
  const queriedProps = useStaticQuery(query)
  return {
    ...queriedProps.site.siteMetadata,
    ...receivedProps,
  }
}

Approach 1: Providing a type definition for useQueryHook

import type { WithQueryHook } from 'gatsby-with-query'
import type { AppProps } from './App.d'

const useGetSiteMetadataQuery: WithQueryHook<AppProps> = (receivedProps): AppProps => {
  const queriedProps = useStaticQuery(query)
  return {
    ...queriedProps.site.siteMetadata,
    ...receivedProps,
  }
}

Approach 2: Providing a type definition for receivedProps

import type { WithQueryReceivedProps } from 'gatsby-with-query'
import type { AppProps } from './App.d'

const useGetSiteMetadataQuery = (receivedProps: WithQueryReceivedProps<AppProps>): AppProps => {
  const queriedProps = useStaticQuery(query)
  return {
    ...queriedProps.site.siteMetadata,
    ...receivedProps,
  }
}

Pass receivedProps into useQueryHook()

Currently, the WithQueryHOC component is overwriting duplicate props.<key>:

const withQuery: WithQuery = (Component, useQueryHook) => {
  const WithQueryHOC: ReturnType<WithQuery> = (receivedProps) => {
    const queriedProps = useQueryHook()
    return createElement(Component, {
      ...queriedProps,
      ...receivedProps, // Any duplicate keys are overwritten
    })
  }
  // ...
}

This may or may not be a behavior that developers want. Instead, receivedProps can be passed as an argument to useQueryHook() and the developer can manage their component's props in the useQueryHook() function:

// Component file

const App = () => {
  // ...
}

export default withQuery<AppProps>(App, (receivedProps) => {
  const queriedProps = useStaticQuery(query)
  
  // Do some logic with received and queried props
  
  return {
    ...queriedProps,
    ...receivedProps,
  }
})

---

Questions

• Will the type definitions need to adapt to whether the developer chooses to utilize receivedProps in their query hook?

Move React from dependencies to peerDependencies

I believe it would make more sense to make react a peer dependency. I need to figure out how to use peer dependencies.