How elisepatrikainen/nuxt-usefetchquery works
Project type and purpose
• This is an open-source Nuxt module named “nuxt-usefetchquery.”
• It provides a composable (useFetchQuery) for caching, synchronizing, and updating server state inside Nuxt applications.
• A “playground” folder contains a minimal Nuxt app demonstrating the module in action.
File structure
Top-level directories/files
• src/
– module.ts ← the Nuxt module registration entry point
– runtime/ ← code loaded at runtime by Nuxt
• composables/ ← the useFetchQuery composable implementation
• plugins/ ← client/server plugin entry points for caching logic
• playground/ ← example Nuxt application
– pages/ ← Vue pages demonstrating useFetchQuery
– server/api/ ← example endpoint (slow-endpoint.ts)
– nuxt.config.ts ← configuration that registers the module
• test/ ← Vitest tests and test fixtures (basic Nuxt app)
• README.md ← detailed description, features, setup, and development scripts
Configuration and build scripts
• tsconfig.json ← TypeScript configuration for the package
• playground/tsconfig.json, server/tsconfig.json ← local compile settings
• package.json ← dependencies, scripts (dev, build, test, release)
Key README insights
• Describes core features: caching, refreshTime, background revalidation, window-event triggers.
• Shows how to install and register nuxt-usefetchquery in a Nuxt config.
• Points out dependencies on Nuxt’s useFetch/useAsyncData under the hood.
• Outlines development commands (install, dev, build, lint, test, release).
a. Main components
1. Nuxt Application (Playground / User’s App)
– Vue pages, Layouts
– Server API endpoints (e.g., /api/slow-endpoint)
2. nuxt-usefetchquery Module
– module.ts (Nuxt hook for registering runtime plugins)
– Runtime Plugins (client & server)
– Composable (useFetchQuery)
3. Nuxt Framework
– Module system (hooks)
– Composable system (useFetch/useAsyncData)
4. Cache Store (in-memory caching layer inside plugin)
5. External Triggers
– Browser events: focus, reconnect
– Suspense / lifecycle hooks
6. Developer Tooling
– TypeScript compiler, Vitest, ESLint, Release script
b. Relationships and interactions
• Developer writes pages that import and call useFetchQuery
• Nuxt loads nuxt-usefetchquery via nuxt.config.ts
• module.ts registers two runtime plugins: client and server
• At runtime, the composable delegates to the appropriate plugin
– On server: plugin caches in-memory, prefetches on SSR
– On client: plugin sets up window-event listeners for revalidation
• Composable issues underlying useFetch / useAsyncData calls
• Cache layer intercepts fetch calls, dedupes, stores data, triggers background re-fetch
• API endpoint returns JSON payload
• Browser receives data, reactive refs (data, fetching, refreshing) update UI
• Vitest harness uses test fixtures mimicking the playground to verify behavior
c. Architectural patterns and design principles
• Plugin pattern: separate client/server plugin entry points
• Composable pattern: single API (useFetchQuery) abstracting underlying logic
• In-memory caching strategy with configurable staleness and background revalidation
• SSR/CSR branching: server prefetch vs. client hydration & revalidation
• Extensibility: users can override refresh options (focus, reconnection, suspense)
d. Key technologies, frameworks, libraries
• Nuxt 3 (module and composable APIs)
• Vue 3 composables (setup, reactivity)
• TypeScript (strict types, tsconfig settings)
• Vitest (unit tests and fixtures)
• ESLint (code quality)
Detail without overcomplicating
• Don’t just show Nuxt app vs. module—break down into module.ts, plugins, composable, cache subsystem.
• Test harness as an extension point under developer tooling.
• SSR vs. CSR branches, window-event triggers, and underlying useFetch calls to fully represent the architecture.