@querry-kit/nuxt

Typed Vue 3 and Nuxt primitives for APIs implementing the Query Kit ResourceQuery contract: an Axios client, typed resource endpoints, headless remote tables, and autocompletes.

📖 Documentation: https://querry-kit.github.io/nuxt/

🌐 Querry Kit Ecosystem

The Querry Kit overview connects the three main repositories:

• @querry-kit/nest for the Query Kit-compatible NestJS API and controller patterns.
• @querry-kit/nuxt for typed API clients and headless Vue/Nuxt data primitives.
• @querry-kit/nuxt-ui for Nuxt UI integrations built on these primitives.

It also contains the complete Workboard API-and-web-app example, which shows the packages working together end to end.

📚 Table of Contents

• 🌐 Querry Kit Ecosystem
• 📦 Install
• 🚀 Release Workflow
• 🧩 Package exports
• 🔌 Create a client and endpoint
• 📊 Use remote state without a UI dependency
• 📖 Documentation
• 🛠 Development

📦 Install

pnpm add @querry-kit/nuxt axios @tanstack/table-core @vueuse/core @vueuse/router vue vue-router

The current package version is published on npm. npm is the primary distribution channel.

🚀 Release Workflow

Releases are driven by Changesets and GitHub Actions. The main branch contains source, documentation, examples, and workflow configuration; distribution files are built in CI.

Package-visible changes should include a changeset:

pnpm changeset

When changes land on main, the changesets workflow creates or updates a release PR. That PR contains the version bump and changelog updates produced by:

pnpm changeset version

The npm publish workflow uses npm Trusted Publishing through GitHub Actions OIDC. After a release PR is merged, it runs the package checks, builds the distribution, publishes @querry-kit/nuxt, creates the vX.Y.Z tag, and creates a GitHub Release.

The release workflow checks npm before publishing. The manually published 0.0.1 baseline therefore remains safe: it is tagged and released from GitHub without an attempted duplicate publish.

🧩 Package exports

Import	Purpose
@querry-kit/nuxt/api	createApiClient and useModuleApi
@querry-kit/nuxt/table	Headless, remotely paginated useTable
@querry-kit/nuxt/autocomplete	Selection-preserving useAutocomplete
@querry-kit/nuxt/types	Shared endpoint, table, and response contracts
@querry-kit/nuxt/utils	Query serialization and query-state helpers

The root export re-exports the public runtime APIs; use the explicit subpaths when an import communicates intent better.

🔌 Create a client and endpoint

import { createApiClient, useModuleApi } from '@querry-kit/nuxt/api';

type Resources = {
  users: {
    item: { id: string; name: string };
    create: { name: string };
    update: { name?: string };
  };
};

const api = createApiClient({
  apiBaseUrl: 'https://api.example.test',
  getToken: () => authStore.token,
});
const users = useModuleApi<Resources, 'users'>(api, 'users');
const response = await users.query({ page: 1, perPage: 25 });

createApiClient targets /api/v1, sends Request-Source: web and a timezone by default, and adds Authorization only if getToken supplies one. Supply resolveBaseUrl for tenant-aware host rewriting and requestSource if the backend distinguishes clients.

📊 Use remote state without a UI dependency

import { useTable } from '@querry-kit/nuxt/table';

const table = useTable({
  api,
  endpoint: 'users',
  persistenceKey: 'users',
  columns: ref([{ id: 'name' }, { id: 'team', fields: ['name'] }]),
  staticFilter: computed(() => ({ tenantId: activeTenant.value })),
});

await table.initialize();

The table selects id,name,team{name}, serializes its query with qs, persists user preferences through a configurable storage adapter, and discards stale responses. useAutocomplete similarly keeps selected resources present if the current search no longer returns them.

The package stays independent of Nuxt runtime configuration, application authentication, routers, stores, and UI components. Consumers provide their own Axios instance, route ref, storage adapter, and endpoint map.

📖 Documentation

• Getting Started
• Controller Contract
• Remote Tables
• Autocomplete
• Query conventions
• Example App
• Client and endpoints
• Table API
• Autocomplete API
• Backend compatibility

Run the VitePress documentation locally:

pnpm docs:dev

Build the documentation:

pnpm docs:build

🛠 Development

pnpm install
pnpm lint
pnpm check
pnpm test
pnpm test:coverage
pnpm build
pnpm examples:check
pnpm examples:build
pnpm docs:build

pnpm test:coverage collects all source files, prints the coverage summary, and writes HTML and LCOV reports to coverage/. GitHub Actions runs the same command and retains the report as a workflow artifact.