nuxt-arpix-graphql-connect

A generic, robust GraphQL client module for Nuxt 3 and 4, powered by graphql-request and graphql-ws. Designed to work seamlessly with Hasura and other GraphQL APIs, supporting both authenticated (JWT) and public operations.

✨ Features

• 🚀 Generic GraphQL Client - Works with any GraphQL endpoint (Hasura, Apollo, etc.).
• � Token Management - Automatic JWT handling for authenticated requests.
• 📡 Real-time Subscriptions - Built-in WebSocket support using graphql-ws.
• 🔄 Auto-Refresh - Optional integration for token refresh endpoints.
• ⚡ Reactive Composables - Use useQuery and useSubscription for easy state management in Vue components.
• �️ TypeScript Support - Fully typed for better developer experience.

📦 Installation

The easiest way to install the module is using the Nuxt CLI:

npx nuxi module add nuxt-arpix-graphql-connect

Alternatively, you can install it manually:

# Using npm
npm install nuxt-arpix-graphql-connect

# Using yarn
yarn add nuxt-arpix-graphql-connect

# Using pnpm
pnpm add nuxt-arpix-graphql-connect

🚀 Quick Setup

Add configuration to your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['nuxt-arpix-graphql-connect'],

  graphql: {
    // Required: Your GraphQL HTTP endpoint
    httpUrl: process.env.GRAPHQL_HTTP_URL || 'http://localhost:8080/v1/graphql',
    
    // Optional: WebSocket endpoint for subscriptions
    wsUrl: process.env.GRAPHQL_WS_URL || 'ws://localhost:8080/v1/graphql',
    
    // Optional: Endpoint to refresh expired tokens
    refreshTokenEndpoint: '/api/auth/refresh',
    
    // Optional: Default headers to send with every request
    defaultHeaders: {
      // 'x-hasura-admin-secret': process.env.HASURA_ADMIN_SECRET // WARNING: For dev only!
    }
  }
})

📖 Usage

Using the Composable

<script setup lang="ts">
const { query, mutate, subscribe } = useGraphQLClient()

// 1. Simple Query
const fetchUsers = async () => {
  const data = await query(`
    query GetUsers {
      users {
        id
        name
      }
    }
  `)
  console.log(data)
}

// 2. Mutation
const createUser = async () => {
  await mutate(`
    mutation CreateUser($name: String!) {
      insert_users_one(object: {name: $name}) {
        id
      }
    }
  `, { name: 'John Doe' })
}

// 3. Subscription
onMounted(() => {
  const unsubscribe = subscribe(`
    subscription OnUserAdded {
      users {
        id
        name
      }
    }
  `, {
    next: (data) => console.log('New user:', data),
    error: (err) => console.error(err)
  })
})
</script>

Using Reactive Helpers

For simpler use cases, use the reactive helpers useQuery or useSubscription.

<script setup lang="ts">
const { useQuery } = useGraphQLClient()

// Data is reactive and updates automatically
const { data, loading, error, refetch } = useQuery(`
  query GetPosts {
    posts {
      id
      title
    }
  }
`)
</script>

Public (Unauthenticated) Queries

To make a request without sending authentication headers (e.g., for public data), use the skipAuth option:

const publicData = await query(
  `query PublicData { ... }`, 
  {}, // variables
  { 
    skipAuth: true,
    // Optional: Explicitly force 'public' role for Hasura
    headers: { 'x-hasura-role': 'public' }
  } 
)

🔐 Authentication & Token Management

The module automatically handles token refresh when configured with a refreshTokenEndpoint.

Token Storage

The module automatically stores tokens in:

• Cookies - auth_token (primary)
• localStorage - auth_token (fallback)

Manual Token Management

<script setup lang="ts">
const { clearToken } = useGraphQLClient()

// Clear token on logout
const logout = () => {
  clearToken()
  // Redirect to login page
}
</script>

⚙️ Configuration Options

| Option | Type | Required | Description | | ---------------------- | ------------------------ | -------- | -------------------------------------------------- | | httpUrl | string | ✅ Yes | GraphQL HTTP endpoint URL | | wsUrl | string | ❌ No | GraphQL WebSocket endpoint URL (for subscriptions) | | refreshTokenEndpoint | string | ❌ No | API endpoint to refresh tokens | | defaultHeaders | Record<string, string> | ❌ No | Default headers for all requests |

🎨 VSCode Snippets

The module includes helpful VSCode snippets in the snippets/ directory.

• graphql-query - Basic GraphQL query
• graphql-mutation - GraphQL mutation
• graphql-subscription - GraphQL subscription
• graphql-use-query - Reactive query helper
• graphql-use-subscription - Reactive subscription helper
• use-graphql-client - Import composable

🔄 Migration from v1.x

Version 2.0.0 is a complete rewrite with breaking changes:

❌ Removed in v2.0.0

• High-level operations (get, insert, update, delete, batch)
• $dbConnect plugin
• useDBConnector server composable
• Hasura-specific query builders

✅ New in v2.0.0

• Simple useGraphQLClient() composable
• Generic GraphQL support (any endpoint)
• Automatic token management
• Public access support
• Reactive helpers (useQuery, useSubscription)
• graphql configuration key (replaces dbConnect)

🤝 Contributing

Contributions are welcome! Please see the GitHub repository for more information.

📝 License

MIT