Getting Started

Get started with qortex in minutes. Learn the basics and build your first data fetching application.

Quick Start

Install qortex

Step 1

Choose the package that fits your framework

# For React applications
npm install qortex-react

# For other frameworks (Vue, Svelte, vanilla JS)
npm install qortex-core

# Using pnpm or yarn
pnpm add qortex-react  # or qortex-core
yarn add qortex-react  # or qortex-core

Set up your first fetcher

Step 2

Register a fetcher function to define how data is fetched

import { registerFetcher, setDefaultConfig } from "qortex-react";

// Register a fetcher for todos
registerFetcher(["todos"], {
  fetcher: async () => {
    const response = await fetch("/api/todos");
    return response.json();
  },
  placeholderData: [] // Show empty array while loading
});

Use in your React component

Step 3

Use the useQuery hook to fetch and display data

import { useQuery } from "qortex-react";

function TodosList() {
  const { data, isLoading, error, refetch } = useQuery(["todos"]);

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <button onClick={() => refetch()}>Refresh</button>
      <ul>
        {data?.map(todo => (
          <li key={todo.id}>{todo.title}</li>
        ))}
      </ul>
    </div>
  );
}

Key Features

Automatic Caching

Data is automatically cached and shared across components

Background Updates

Data is refreshed in the background when it becomes stale

Error Handling

Built-in error handling with retry capabilities

TypeScript Support

Full TypeScript support with type inference

Complete Example

Here's a complete example showing how to set up qortex in a React application:

// App.tsx
import React from 'react';
import { setDefaultConfig } from 'qortex-core';
import { TodosList } from './TodosList';

// Set global defaults
setDefaultConfig({
  staleTime: 5 * 60 * 1000, // 5 minutes
  refetchOnSubscribe: "stale",
  throttleTime: 100,
  usePreviousDataOnError: false
});

// Register fetchers
registerFetcher(["todos"], {
  fetcher: async () => {
    const response = await fetch("/api/todos");
    if (!response.ok) throw new Error('Failed to fetch todos');
    return response.json();
  },
  placeholderData: []
});

registerFetcher(["user", "id"], {
  fetcher: async (key) => {
    const [, , userId] = key;
    const response = await fetch(`/api/users/${userId}`);
    if (!response.ok) throw new Error('Failed to fetch user');
    return response.json();
  }
});

function App() {
  return (
    <div className="app">
      <h1>My Todo App</h1>
      <TodosList />
    </div>
  );
}

export default App;

// TodosList.tsx
import React from 'react';
import { useQuery } from 'qortex-react';

interface Todo {
  id: string;
  title: string;
  completed: boolean;
}

export function TodosList() {
  const { data: todos, isLoading, error, refetch } = useQuery<Todo[]>(["todos"]);

  if (isLoading) return <div>Loading todos...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <div className="flex items-center justify-between mb-4">
        <h2>Todos</h2>
        <button 
          onClick={() => refetch()}
          className="btn-primary"
        >
          Refresh
        </button>
      </div>
      <ul className="space-y-2">
        {todos?.map(todo => (
          <li key={todo.id} className="flex items-center space-x-2">
            <input 
              type="checkbox" 
              checked={todo.completed}
              readOnly
            />
            <span className={todo.completed ? 'line-through' : ''}>
              {todo.title}
            </span>
          </li>
        ))}
      </ul>
    </div>
  );
}

What's Next?

Now that you have the basics down, explore more advanced features and patterns.

Basic Usage PatternsAPI ReferenceConfiguration Guide