repository·main·Indexed 19 days ago
https://github.com/diizzayy/nuxt-graphql-clientA minimal GraphQL client and code generation tool optimized for Nuxt 3. It provides full TypeScript support, Hot Module Reload (HMR) for GraphQL documents, and leverages graphql-request and graphql-code-generator. Key features include zero configuration, automatically generated Gql functions, and composables such as useAsyncGql, useGql, and useGqlToken for managing requests, authorization, and error handling.
If your GraphQL API requires authentication to run introspection queries (used for generating types), you must provide a token to the client.
Recommended approach: Add the token to your .env file using the GQL_<CLIENT_NAME>_TOKEN format. This token will only live server-side and will not be passed to the browser.
When using Multiple Client Mode, you must tell the module which client an operation belongs to. You can do this using one of three methods, listed in order of precedence:
<clientname>.gql or <clientname>.graphql. For example, example.github.gql will be linked to the github client../queries/spacex/ will be linked to the spacex client.default client.Due to how Nuxt 3 handles SSR, the Nuxt instance context is lost after the first await statement. This means you cannot call multiple Gql Functions sequentially if they rely on the Nuxt context (like useState or useRoute) inside an async function.
Calling a second Gql Function after an await will fail because the context is gone.
export const useExample = async () => {
const { user } = await GqlUser() // Context lost here
const { relations } = await GqlRelations({ id: user.id }) // Fails
}Use the useGql composable to create a single instance. This allows you to perform multiple queries/mutations while maintaining the necessary context. Additionally, ensure any Nuxt composables (like useState) are called before the first await statement.
export const useExample = async () => {
const GqlInstance = useGql()
// Access Nuxt composables BEFORE the first await
const myState = useState('example')
const { user } = await GqlInstance('user')
const { relations } = await GqlInstance('relations', { id: user.id })
// myState is still accessible
}export const useExample = async () => {
const GqlInstance = useGql()
const myState = useState('example')
const { user } = await GqlInstance('user')
const { relations } = await GqlInstance('relations', { id: user.id })
}The module provides the following core capabilities:
graphql-request for the client and graphql-code-generator for code generation.The default client is the fallback for any GraphQL operation that does not explicitly specify a client via file naming or directory structure.
In Multiple Client Mode, the default client is determined by:
clients object.default in the Nuxt Configuration.If your GraphQL API is not publicly available or you prefer not to use introspection over the network, you can provide a path to a local schema file. The module will use this file to generate types for your GraphQL operations. Provide the path relative to your project root in the schema property within your client configuration.
export default defineNuxtConfig({
modules: ['nuxt-graphql-client'],
runtimeConfig: {
public: {
'graphql-client': {
clients: {
default: {
schema: '<relative_path_to_schema_file>',
}
}
}
}
}
})Operations (queries and mutations) must be written in .gql or .graphql files. Writing operations directly within SFC components is not supported.
nuxt-graphql-client automatically parses these files and generates corresponding functions and types. The generated function name is derived from the GraphQL operation name.
Example Operation:
Create a file at ./queries/starlink.gql:
query launches($limit: Int = 5) {
launches(limit: $limit) {
id
launch_year
mission_name
}
}This will generate a function named GqlLaunches() (based on the operation name launches) that is fully typed based on the GraphQL document. To trigger code generation, run your development server (e.g., yarn dev).
To interact with multiple GraphQL APIs, add a clients key to the graphql-client property within your Nuxt runtimeConfig.public. Each key in the clients object represents a unique client name.
If you configure more than one client, the module enters Multiple Client Mode. In this mode, you must explicitly associate GraphQL operations with a specific client using file naming or directory structures, otherwise, they will fall back to the default client.
import { defineNuxtConfig } from 'nuxt'
export default defineNuxtConfig({
modules: ['nuxt-graphql-client'],
runtimeConfig: {
public: {
'graphql-client': {
clients: {
default: 'https://spacex-production.up.railway.app/',
github: {
host: 'https://api.github.com/graphql',
token: 'your_access_token',
},
countries: {
host: 'https://countries.trevorblades.com/graphql',
token: {
name: 'X-Custom-Auth',
value: 'your_access_token'
}
}
}
}
}
}
})To add the nuxt-graphql-client module to your Nuxt project, use the Nuxt CLI command. This module provides a minimal GraphQL client combined with automatic TypeScript code generation.
npx nuxi@latest module add graphql-clientTo use nuxt-graphql-client in a Nuxt 3 application, follow these steps:
Install the module using the Nuxt CLI:
npx nuxi@latest module add graphql-clientEnable the module in your nuxt.config.ts:
import { defineNuxtConfig } from 'nuxt/config'
export default defineNuxtConfig({
modules: ['nuxt-graphql-client'],
})Configure the GraphQL API URL by providing a GQL_HOST. You can define this in nuxt.config.ts or via a .env file. Note that a GQL_HOST value in .env will overwrite the value defined in runtimeConfig.
Using nuxt.config.ts:
export default defineNuxtConfig({
modules: ['nuxt-graphql-client'],
runtimeConfig: {
public: {
GQL_HOST: 'https://your-api-url.com/'
}
}
})Using .env:
GQL_HOST="https://your-api-url.com/"npx nuxi@latest module add graphql-clientGql Functions are automatically generated and imported based on the GraphQL operations defined in your project. They allow you to execute queries and mutations as simple asynchronous functions.
Functions are named using the pattern Gql + [OperationName]. For example, a query named GetUsers becomes the function GqlGetUsers().
query { ... }) are skipped and will not generate a Gql Function..gql or .graphql files located anywhere in your project.query GetUsers {
users {
id
name
}
}
mutation LoginUser($email: String!, $password: String!) {
login(email: $email, password: $password) {
id
name
}
}// Generated functions are automatically imported
async function loadUsers() {
const result = await GqlGetUsers()
}
async function handleLogin(email: string, password: string) {
const result = await GqlLoginUser(email, password)
}