graphql

Intuition GraphQL Package

This package provides the GraphQL client, generated types, and query/mutation definitions for interacting with the Intuition API. It serves as the core data fetching layer used by other packages in the monorepo.

Getting Started

Once you've cloned the intuition-ts monorepo you can run the GraphQL package from the monorepo root. Install all packages from the monorepo root by running pnpm install.

Features

• Type-safe GraphQL operations using code generation
• React Query hooks for data fetching
• Reusable GraphQL fragments
• Built-in authentication handling
• Automatic error handling

Development

GraphQL Code Generation

This package uses GraphQL Code Generator to create TypeScript types and React Query hooks from GraphQL operations. To run the code generator:

pnpm run codegen

You can also run this from the monorepo root:

pnpm graphql:codegen

Schema Management

The package uses a local schema.graphql file as the source of truth for generating TypeScript types. This ensures consistent behavior across all environments and makes the package more portable for external use.

Testing

Run unit tests with:

pnpm run test

You can also run this from the monorepo root:

pnpm graphql:test

Testing with Local Registry

Setup

1. Copy .npmrc.example from the root to .npmrc to configure the local registry.

2. Start the local registry:

pnpm nx local-registry

Version Management

Before publishing, you may need to update the package version. Use one of these commands:

pnpm version:patch  # For bug fixes (0.0.x)
pnpm version:minor  # For new features (0.x.0)
pnpm version:major  # For breaking changes (x.0.0)
pnpm version:beta   # For beta releases

Testing in Monorepo Apps (Recommended)

1. Make changes to the package and build:

cd packages/graphql
# This will run codegen first (prebuild) and then build
pnpm build

2. Test the build before publishing (optional):

pnpm publish-dry

3. Publish to local registry using one of these commands:

# For local testing only
npm publish --registry http://localhost:4873

# For publishing to npm registry with tags (when ready)
pnpm publish-latest  # Publishes with 'latest' tag
pnpm publish-next   # Publishes with 'next' tag

4. In your test app, update the package version in package.json:

{
  "dependencies": {
    "@0xintuition/graphql": "^x.x.x" // Use the version from package.json
  }
}

5. Install the updated package:

pnpm install

Notes

• The local registry persists packages in tmp/local-registry/storage
• Clear storage by stopping and restarting the registry
• First-time publishing requires creating a user (any username/password works)
• The registry runs on port 4873 by default
• The build process automatically runs codegen before building

Usage

Client Setup

The package exports a GraphQL client that can be used to make authenticated requests:

import { createServerClient } from '@0xintuition/graphql'

const client = createServerClient({
  token: 'your-auth-token', // Optional
})

Using Generated Hooks

The generated React Query hooks can be imported directly:

import { useGetStats } from '@0xintuition/graphql'

function StatsComponent() {
  const { data, isLoading } = useGetStats()
  // ...
}

Project Structure

graphql
├── src
│   ├── client.ts        # GraphQL client configuration
│   ├── fragments/       # Reusable GraphQL fragments
│   ├── queries/         # GraphQL queries
│   ├── mutations/       # GraphQL mutations
│   └── generated/       # Generated TypeScript types and hooks
├── tests/              # Unit tests
└── codegen.ts         # Code generation configuration

Configuration

The package can be configured through the following files:

• codegen.ts - GraphQL code generation settings
• tsconfig.json - TypeScript configuration
• vitest.config.ts - Test configuration
• schema.graphql - GraphQL schema (source of truth)

Contributing

Please read the core CONTRIBUTING.md before proceeding.