CoreQL Logo

Quick Start

Purpose

CoreQL born as a wrapper around React Query to fix the main issue found while working with JSON:API. It's hard to format and maintain JSON:API URLs when you started adding query params.

Installation

CoreQL is available as an npm package in Able Registry for use with module bundlers.

First setup the Able Registry if you haven't already.

yarn config set registry https://registry.able.co

For npm or pnpm check instructions at https://registry.able.co.

Once you have done that install it as a normal package.

yarn add coreql react-query react
# npm i coreql react-query react

React Query and React are peer dependencies of CoreQL and should be provided by the project.

Basic Usage

import { useCollection } from 'coreql';


function Projects() {
  const { data: projects } = useCollection(
    'projects',
    {
      filter: { status: ['active', 'on-hold'] },
      included: ['owner'],
      sort: ['-ownerId', 'title', 'id'],
      fields: { projects: ['title'], users: ['fullName'] },
    },
    'denormalized',
  );


  return projects?.map(project => <Project {...project} key={project.id} />);
}

In this example, the React Hook useCollection accepts a resource, an options and a format. resource is the resource name in the API, typically in plural. The options are the query argument we will use against the resource. And the format is the way we want the hook to format the data received from the API.

useCollection returns an objet with the same shape as React Query, we set it to give us denormalized data, to get a formatted data we can later iterate on, without manually dealing with the JSON:API data structure.

Check more Examples for the best practices.

Help and Discussion

The coreql repository issue tracker is our official resource for all questions related to learning and using CoreQL.

Edit this page