@incubrain/client

A type-safe GraphQL client for Hasura, optimized for Node.js and Nuxt environments with full TypeScript support.

Features

🚀 ESM-first architecture
🎯 Full TypeScript support with generated types
📦 Auto-generated mutations and queries
🔄 Built-in GraphQL code generation
🛡️ Type-safe API calls
⚡ Optimized for Hasura
🌐 Universal runtime support (Node.js and Nuxt)
🔒 Built-in authentication handling

Installation

# Using npm
npm install @incubrain/client

# Using pnpm
pnpm add @incubrain/client

# Using yarn
yarn add @incubrain/client

Quick Start

import { createClient } from "@incubrain/client";

// Initialize the client
const client = createClient({
  endpoint: "YOUR_HASURA_ENDPOINT",
  headers: {
    "x-hasura-admin-secret": "YOUR_ADMIN_SECRET",
  },
});

// Use generated mutations
const { insert_users_one } = await client.mutation({
  insert_users_one: {
    object: {
      name: "John Doe",
      email: "john@example.com",
    },
  },
});

// Use generated queries
const { users } = await client.query({
  users: {
    where: {
      email: { _eq: "john@example.com" },
    },
  },
});

Configuration

Environment Variables

The client supports the following environment variables:

HASURA_ENDPOINT=https://your-hasura-endpoint/v1/graphql
HASURA_ADMIN_SECRET=your-admin-secret

Client Options

interface ClientOptions {
  endpoint?: string;        // GraphQL endpoint URL
  headers?: HeadersInit;    // Custom headers
  fetch?: typeof fetch;     // Custom fetch implementation
}

Development

Generate Mutations

pnpm generate:mutations

This will introspect your Hasura schema and generate all available mutations with proper TypeScript types.

Generate Client

pnpm generate

This will generate the type-safe client with all available operations.

Build

pnpm build

Builds the package for production.

Usage in Nuxt

Setup

// plugins/graphql.ts
import { createClient } from "@incubrain/client";

export default defineNuxtPlugin(() => {
  const config = useRuntimeConfig();
  
  const client = createClient({
    endpoint: config.public.hasuraEndpoint,
    headers: {
      "x-hasura-admin-secret": config.hasuraAdminSecret,
    },
  });

  return {
    provide: {
      graphql: client,
    },
  };
});

Usage in Components

<script setup>
const { $graphql } = useNuxtApp();

const { users } = await $graphql.query({
  users: {
    limit: 10,
  },
});
</script>

Type Safety

The client provides full type safety for all operations:

// All these are type-checked
const { users } = await client.query({
  users: {
    where: {
      id: { _eq: 123 },     // ✅ Valid
      invalid: true,        // ❌ Type error
    },
    order_by: {
      created_at: "desc",   // ✅ Valid
      invalid: "asc",       // ❌ Type error
    },
  },
});

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

MIT