docs for humans by humans

Author: stackoverfloweth

README.md

@@ -5,6 +5,7 @@ A type-safe, composable query system designed specifically for Vue.js applicatio
 [![NPM Version][npm-badge]][npm-url]
 [![Netlify Status][netlify-badge]][netlify-url]
 [![Discord chat][discord-badge]][discord-url]
+[![Open in StackBlitz][stackblitz-badge]][stackblitz-url]
 
 <img src="https://kitbag.dev/kitbag-logo.svg" width="20%" />
 
@@ -63,5 +64,7 @@ const user = useQuery(userQuery, { params: [123] })
 [npm-url]: https://www.npmjs.org/package/@kitbag/query
 [netlify-badge]: https://api.netlify.com/api/v1/badges/c12f79b8-49f9-4529-bc23-f8ffca8919a3/deploy-status
 [netlify-url]: https://app.netlify.com/sites/kitbag-query/deploys
+[stackblitz-badge]: https://developer.stackblitz.com/img/open_in_stackblitz_small.svg
+[stackblitz-url]: https://stackblitz.com/~/github.com/kitbagjs/query-preview
 [discord-badge]: https://img.shields.io/discord/1079625926024900739?logo=discord&label=Discord
 [discord-url]: https://discord.gg/zw7dpcc5HV

docs/.vitepress/config.ts

@@ -49,20 +49,13 @@ export default defineConfig({
         {
           text: 'Core Concepts',
           items: [
-            { text: 'Query Client', link: '/core-concepts/query-client' },
             { text: 'Queries', link: '/core-concepts/queries' },
-            { text: 'Mutations', link: '/core-concepts/mutations' },
             { text: 'Tags & Invalidation', link: '/core-concepts/tags-invalidation' },
+            { text: 'Mutations', link: '/core-concepts/mutations' },
+            { text: 'Query Client', link: '/core-concepts/query-client' },
             { text: 'Caching', link: '/core-concepts/caching' },
           ],
         },
-        {
-          text: 'Composables',
-          items: [
-            { text: 'useQuery', link: '/composables/useQuery' },
-            { text: 'useMutation', link: '/composables/useMutation' },
-          ],
-        },
         {
           text: 'Advanced Concepts',
           items: [
@@ -72,6 +65,7 @@ export default defineConfig({
             { text: 'Optimistic Updates', link: '/advanced-concepts/optimistic-updates' },
           ],
         },
+        { text: 'Migrating from Tanstack', link: '/compare-to-tanstack' },
       ]
     },
 

docs/advanced-concepts/background-updates.md

@@ -1,6 +1,6 @@
 # Background Updates
 
-Background updates allow your application to keep data fresh without interrupting the user experience. @kitbag/query provides several mechanisms for updating data in the background.
+<!-- Background updates allow your application to keep data fresh without interrupting the user experience. Kitbag query provides several mechanisms for updating data in the background.
 
 ## Automatic Background Updates
 
@@ -506,18 +506,18 @@ Show non-intrusive indicators for background updates:
 ```vue
 <template>
   <div class="content-container">
-    <!-- Subtle refresh indicator -->
+    // Subtle refresh indicator
     <div 
       v-if="user.executing && user.data" 
       class="refresh-indicator"
     >
       <div class="refresh-bar"></div>
     </div>
     
-    <!-- Main content -->
+    // Main content
     <UserProfile v-if="user.data" :user="user.data" />
     
-    <!-- Toast notification for successful updates -->
+    // Toast notification for successful updates
     <Teleport to="body">
       <Toast 
         v-if="showUpdateToast"
@@ -762,4 +762,4 @@ const user = useQuery(userQuery, {
 
 - [Optimistic Updates](/advanced-concepts/optimistic-updates) - Improving perceived performance
 - [Caching](/core-concepts/caching) - Understanding cache behavior
-- [Error Handling](/advanced-concepts/error-handling) - Handling background update errors
+- [Error Handling](/advanced-concepts/error-handling) - Handling background update errors -->

docs/advanced-concepts/error-handling.md

@@ -1,6 +1,6 @@
 # Error Handling
 
-Effective error handling is crucial for building robust applications. @kitbag/query provides multiple layers of error handling for both queries and mutations.
+<!-- Effective error handling is crucial for building robust applications. Kitbag query provides multiple layers of error handling for both queries and mutations.
 
 ## Basic Error Handling
 
@@ -16,7 +16,7 @@ Effective error handling is crucial for building robust applications. @kitbag/qu
       <button @click="user.execute()">Retry</button>
     </div>
     <div v-else-if="user.data">
-      <!-- User data -->
+      // User data
     </div>
   </div>
 </template>
@@ -182,7 +182,7 @@ export const { query, useQuery, mutation, useMutation } = createQueryClient({
 Create reusable error boundary components:
 
 ```vue
-<!-- ErrorBoundary.vue -->
+// ErrorBoundary.vue
 <template>
   <div class="error-boundary">
     <div v-if="hasError" class="error-container">
@@ -337,14 +337,14 @@ const canShowSettings = computed(() => !userSettings.error)
 <template>
   <div>
     <div v-if="canShowProfile">
-      <!-- User profile section -->
+      // User profile section
     </div>
     <div v-else class="error">
       Failed to load profile
     </div>
     
     <div v-if="canShowPosts">
-      <!-- User posts section -->
+      // User posts section
     </div>
     <div v-else class="error">
       Failed to load posts
@@ -401,12 +401,12 @@ Provide clear feedback during error recovery:
 ```vue
 <template>
   <div>
-    <!-- Loading state -->
+    // Loading state
     <div v-if="user.executing && !user.data" class="loading">
       Loading user profile...
     </div>
     
-    <!-- Error state with retry -->
+    // Error state with retry
     <div v-else-if="user.error" class="error">
       <h3>Unable to load profile</h3>
       <p>{{ getErrorMessage(user.error) }}</p>
@@ -419,9 +419,9 @@ Provide clear feedback during error recovery:
       </div>
     </div>
     
-    <!-- Success state -->
+    // Success state
     <div v-else-if="user.data">
-      <!-- Profile content -->
+      // Profile content
     </div>
   </div>
 </template>
@@ -461,7 +461,7 @@ watch(isOnline, (online) => {
       You are currently offline
     </div>
     
-    <!-- Rest of component -->
+    // Rest of component
   </div>
 </template>
 ```
@@ -526,7 +526,7 @@ const user = useQuery(userQuery, {
 Create an error reporting component:
 
 ```vue
-<!-- ErrorReporter.vue -->
+// ErrorReporter.vue
 <template>
   <div class="error-reporter">
     <h3>Something went wrong</h3>
@@ -622,7 +622,7 @@ const queryClient = createQueryClient({
 ### 3. Provide Recovery Options
 
 ```vue
-<!-- ✅ Always provide a way to recover -->
+// ✅ Always provide a way to recover
 <div v-if="error" class="error">
   <p>{{ error.message }}</p>
   <button @click="retry">Try Again</button>
@@ -661,4 +661,4 @@ const user = useQuery(userQuery, {
 
 - [Loading States](/advanced-concepts/loading-states) - Managing loading UX
 - [Background Updates](/advanced-concepts/background-updates) - Handling background data refresh
-- [Optimistic Updates](/advanced-concepts/optimistic-updates) - Improving perceived performance
+- [Optimistic Updates](/advanced-concepts/optimistic-updates) - Improving perceived performance -->