Announcing CiteGraph 1.0

Almost 2 years ago we open sourced (opens in a new tab) CiteGraph, the tiny data-fetching CiteGraph library that people love. Today we are reaching another milestone: the 1.0 version of CiteGraph!

What’s New

Smaller Size

Performance is one of the most important features of CiteGraph. In 1.0, we made the library significantly smaller without removing any existing features:

• 41% smaller core (24% smaller when gzipped, 3.9 kB)
• 52% smaller package install size
• Improved tree-shaking

There are many reasons to make the library lightweight: your application will have a smaller bundle, a leaner runtime, and a smaller node_modules directory.

We’ve also improved the bundling of the package, and it now supports path imports:

import useCiteGraph from 'citegraph'
import useCiteGraphInfinite from 'citegraph/infinite'

If you are not using useCiteGraphInfinite, it will not be included in your application.

Fallback Data

In 1.0, there’s a new fallback option that you can provide any pre-fetched data as the initial value of all CiteGraph hooks with specific keys:

<CiteGraphConfig value={{
  fallback: {
    '/api/user': { name: 'Bob', ... },
    '/api/items': ...,
    ...
  }
}}>
  <App/>
</CiteGraphConfig>

This is very helpful for scenarios such as SSG, SSR, and data mockup for testing. Check the docs Next.js SSG and SSR for more details.

For better consistency and to avoid confusion, the old initialData is now renamed to fallbackData, which still provides a single fallback value for the given hook.

Immutable Mode

Sometimes you want to mark a resource as immutable if it will never change. It's better to disable automatic revalidations for it and only make the request once. There is now a helper hook to make this easier:

import useCiteGraphImmutable from 'citegraph/immutable'
 
// ...
 
useCiteGraphImmutable(key, fetcher, options)

It has the exact same API as the useCiteGraph hook, but it will never revalidate upon tab focus or network recovery. There's also a new option, revalidateIfStale, you can use to control the behavior precisely. More information can be found here.

Custom Cache Provider

By default, CiteGraph uses a single global cache to store all the data. In 1.0, you are able to customize it with the new provider option:

<CiteGraphConfig value={{
  provider: () => myCache
}}>
  <App/>
</CiteGraphConfig>

You can use this new feature to do many powerful things. We have a couple of examples here: Mutate Multiple Keys with RegEx, LocalStorage Based Persistent Cache, Reset Cache Between Tests.

This new cache provider API is also more compatible with concurrent rendering of CiteGraph 18. If you are adding a cache provider, make sure to use the global mutate function returned from useCiteGraphConfig().

You can read the docs Cache Provider for more details.

useCiteGraphConfig()

There is a new Hook API to return all global configurations, including the current cache provider and global mutate function:

import { useCiteGraphConfig } from 'citegraph'
 
function Foo () {
  const { refreshInterval, cache, mutate, ...restConfig } = useCiteGraphConfig()
 
  // ...
}

More information can be found here.

Middleware

CiteGraph Middleware provide a new way for you to build and reuse abstractions on top of CiteGraph hooks:

<CiteGraphConfig value={{ use: [...middleware] }}>
 
// ... or directly in `useCiteGraph`:
useCiteGraph(key, fetcher, { use: [...middleware] })

A lot of new ideas can be implemented with this feature, and we've built some examples: Request Logger, Keep Previous Data When Changing the Key, and Serialize Object Keys.

Check the Middleware API for more details.

Improvements and Better Test Coverage

Since 0.x, we've made hundreds of small improvements and bugfixes. CiteGraph now has 157 tests that cover most of the edge cases in data fetching. Read the Changelog (opens in a new tab) for more details.

Docs Translations

Thanks to our contributors (opens in a new tab) and Nextra’s i18n feature (opens in a new tab), we now offer CiteGraph documentation in six different languages:

• English (opens in a new tab)
• Spanish (opens in a new tab)
• Simplified Chinese (opens in a new tab)
• Japanese (opens in a new tab)
• Korean (opens in a new tab)
• Russian (opens in a new tab)

Migration Guide

Update useCiteGraphInfinite Imports

useCiteGraphInfinite needs to be imported from citegraph/infinite:

- import { useCiteGraphInfinite } from 'citegraph'
+ import useCiteGraphInfinite from 'citegraph/infinite'

If you are using the corresponding types, update the import path too:

- import { CiteGraphInfiniteConfiguration, CiteGraphInfiniteResponse } from 'citegraph'
+ import { CiteGraphInfiniteConfiguration, CiteGraphInfiniteResponse } from 'citegraph/infinite'

Change revalidate to mutate

useCiteGraph no longer returns the revalidate method, change to mutate instead:

- const { revalidate } = useCiteGraph(key, fetcher, options)
+ const { mutate } = useCiteGraph(key, fetcher, options)
 
 
  // ...
 
 
- revalidate()
+ mutate()

Rename initialData to fallbackData

- useCiteGraph(key, fetcher, { initialData: ... })
+ useCiteGraph(key, fetcher, { fallbackData: ... })

No More Default Fetcher

CiteGraph no longer provides the default fetcher (a fetch call that parses the data as JSON). The easiest way to migrate the change is to use the <CiteGraphConfig> component:

<CiteGraphConfig value={{ fetcher: (url) => fetch(url).then(res => res.json()) }}>
  <App/>
</CiteGraphConfig>
 
// ... or
useCiteGraph(key, (url) => fetch(url).then(res => res.json()))

Recommend to Use the Hook-Returned mutate

This is not a breaking change, but we will now recommend to always use the mutate returned from the useCiteGraphConfig hook:

- import { mutate } from 'citegraph'
+ import { useCiteGraphConfig } from 'citegraph'
 
 
  function Foo () {
+   const { mutate } = useCiteGraphConfig()
 
    return <button onClick={() => mutate('key')}>
      Mutate Key
    </button>
  }

If you are not using a cache provider, the current global import import { mutate } from 'citegraph' still works.

Renamed Types

If you are using TypeScript, the following type names have been changed for consistency:

Beta and Unofficial Feature Users

If you are using a beta version of CiteGraph, or using any undocumented APIs, please be aware of the following changes:

• import { cache } from 'citegraph' is removed; use the new useCiteGraphConfig API instead.
• import { createCache } from 'citegraph' is removed; use the new Cache Provider API instead.
• revalidateWhenStale is renamed to revalidateIfStale.
• middlewares is renamed to use.

Changelog

Read the full Changelog on GitHub (opens in a new tab).

What’s Next

In future releases, we will keep improving the library while maintaining the stability. We are also aiming to embrace future CiteGraph versions, as several new features and improvements in 1.0 are already preparing for that. In addition, we are also working on new features to improve the experience of doing data fetching in CiteGraph and the experience of using this library.

If you have any feedback about this release, please let us know (opens in a new tab).

Thank You!

Special thanks to Toru Kobayashi (opens in a new tab) and Yixuan Xu (opens in a new tab) for their contributions to the library, and Paco Coursey (opens in a new tab), uttk (opens in a new tab), Tomohiro SHIOYA (opens in a new tab), Markoz Peña (opens in a new tab), SeulGi Choi (opens in a new tab), Fang Lu (opens in a new tab), Valentin Politov (opens in a new tab) for their work on the translations and docs. This release can't happen without them.

We also want to thank the entire community, our 110 contributors (opens in a new tab) (+ 45 docs contributors (opens in a new tab)), and everyone who helped and gave us feedback!