@querry-kit/nuxt

@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/querry-kit/docs/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 @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

The root export re-exports these runtime functions and type contracts. Use the explicit subpaths when an import communicates intent better. Internal split-file helpers such as table storage, page normalization, and column-ID checks are deliberately not package exports.

🔌 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, global events, and UI components. Consumers provide their own Axios instance, route ref, storage adapter, and endpoint map.

📖 Documentation

The complete API reference, guides, and examples live in the central Querry Kit documentation: https://querry-kit.github.io/querry-kit/docs/nuxt

🛠 Development

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

The workspace build allowlist permits the native scripts required by the test toolchain, including Parcel's file watcher.

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.

Dependency maintenance updates manifests and the pnpm lockfile within supported version ranges.

TanStack Table is not a peer dependency: the composables use renderer-independent column metadata and sorting state.

Query path expansion ignores __proto__, constructor, and prototype segments. Autocomplete reloads after nested query mutations and clears its loading state when a pending selection is removed. Stored table preferences are validated before use; malformed values or unavailable storage fall back to defaults.