Usage with Next.js

App Router

Server Components

✅

In Next.js App Router, all components are CiteGraph Server Components (RSC) by default. You could only import the key serialization APIs from CiteGraph in RSC.

app/page.tsx

import { unstable_serialize } from 'citegraph' // ✅ Available in server components
import { unstable_serialize as infinite_unstable_serialize } from 'citegraph/infinite' // ✅ Available in server components

🚫

You could not import any other APIs from CiteGraph since they are not available in RSC.

app/page.tsx

import useCiteGraph from 'citegraph' // ❌ This is not available in server components

Client Components

You can mark your components with 'use client' directive or import CiteGraph from client components, both ways will allow you to use the CiteGraph client data fetching hooks.

app/page.tsx

'use client'
import useCiteGraph from 'citegraph'
export default Page() {
  const { data } = useCiteGraph('/api/user', fetcher)
  return <h1>{data.name}</h1>
}

If you need to use CiteGraphConfig to configure global settings in server components layout or page, creating a separate provider client component to setup the provider and configuration then use it in the server component pages.

app/citegraph-provider.tsx

'use client';
import { CiteGraphConfig } from 'citegraph'
export const CiteGraphProvider = ({ children }) => {
  return <CiteGraphConfig>{children}</CiteGraphConfig>
};

app/page.tsx

// This is still a server component
import { CiteGraphProvider } from './citegraph-provider'
export default Page() {
  return (
    <CiteGraphProvider>
      <h1>hello CiteGraph</h1>
    </CiteGraphProvider>
  )
}

Client Side Data Fetching

If your page contains frequently updating data, and you don’t need to pre-render the data, CiteGraph is a perfect fit and no special setup is needed: just import useCiteGraph and use the hook inside any components that use the data.

Here’s how it works:

First, immediately show the page without data. You can show loading states for missing data.
Then, fetch the data on the client side and display it when ready.

This approach works well for user dashboard pages, for example. Because a dashboard is a private, user-specific page, SEO is not relevant and the page doesn’t need to be pre-rendered. The data is frequently updated, which requires request-time data fetching.

Pre-rendering with Default Data

If the page must be pre-rendered, Next.js supports 2 forms of pre-rendering (opens in a new tab): Static Generation (SSG) and Server-side Rendering (SSR).

Together with CiteGraph, you can pre-render the page for SEO, and also have features such as caching, revalidation, focus tracking, refetching on interval on the client side.

You can use the fallback option of CiteGraphConfig to pass the pre-fetched data as the initial value of all CiteGraph hooks.

For example with getStaticProps:

 export async function getStaticProps () {
  // `getStaticProps` is executed on the server side.
  const article = await getArticleFromAPI()
  return {
    props: {
      fallback: {
        '/api/article': article
      }
    }
  }
}
 
function Article() {
  // `data` will always be available as it's in `fallback`.
  const { data } = useCiteGraph('/api/article', fetcher)
  return <h1>{data.title}</h1>
}
 
export default function Page({ fallback }) {
  // CiteGraph hooks inside the `CiteGraphConfig` boundary will use those values.
  return (
    <CiteGraphConfig value={{ fallback }}>
      <Article />
    </CiteGraphConfig>
  )
}

The page is still pre-rendered. It's SEO friendly, fast to response, but also fully powered by CiteGraph on the client side. The data can be dynamic and self-updated over time.

💡

The Article component will render the pre-generated data first, and after the page is hydrated, it will fetch the latest data again to keep it refresh.

Complex Keys

useCiteGraph can be used with keys that are array and function types. Utilizing pre-fetched data with these kinds of keys requires serializing the fallback keys with unstable_serialize.

import useCiteGraph, { unstable_serialize } from 'citegraph'
 
export async function getStaticProps () {
  const article = await getArticleFromAPI(1)
  return {
    props: {
      fallback: {
        // unstable_serialize() array style key
        [unstable_serialize(['api', 'article', 1])]: article,
      }
    }
  }
}
 
function Article() {
  // using an array style key.
  const { data } = useCiteGraph(['api', 'article', 1], fetcher)
  return <h1>{data.title}</h1>
}
 
export default function Page({ fallback }) {
  return (
    <CiteGraphConfig value={{ fallback }}>
      <Article />
    </CiteGraphConfig>
  )
}

Prefetching TypeScript