Pagination
@websideproject/nuxt-auto-api supports both offset-based and cursor-based pagination.
Pagination
@websideproject/nuxt-auto-api supports both offset-based and cursor-based pagination.
Offset Pagination
Traditional page-based pagination:
GET /api/users?page=2&limit=20
Response:
{
"data": [...],
"meta": {
"page": 2,
"limit": 20,
"total": 156
}
}
Cursor Pagination
For infinite scroll and better performance:
GET /api/users?limit=20&cursor=eyJpZCI6MTIzfQ
Response:
{
"data": [...],
"meta": {
"limit": 20,
"hasMore": true,
"nextCursor": "eyJpZCI6MTQzfQ"
}
}
How Cursor Pagination Works
- First request:
GET /api/users?limit=20 - Response includes
nextCursor - Next page:
GET /api/users?limit=20&cursor=<nextCursor> - Continue until
hasMoreis false
Custom Cursor Fields
By default, cursors use id. For custom ordering:
GET /api/users?limit=20&cursorFields=createdAt,id&sort=-createdAt
Configuration
Set default pagination in config:
// nuxt.config.ts
export default defineNuxtConfig({
autoApi: {
pagination: {
default: 'offset', // or 'cursor'
defaultLimit: 20,
maxLimit: 100,
},
},
})
Frontend Usage
With TanStack Query
Offset pagination:
<script setup lang="ts">
const page = ref(1)
const { data: users } = useUsers({
query: {
page: page.value,
limit: 20,
}
})
</script>
Cursor pagination (infinite scroll):
<script setup lang="ts">
import { useInfiniteQuery } from '@tanstack/vue-query'
const { data, fetchNextPage, hasNextPage } = useInfiniteQuery({
queryKey: ['users'],
queryFn: ({ pageParam }) =>
$fetch('/api/users', {
query: { limit: 20, cursor: pageParam }
}),
getNextPageParam: (lastPage) => lastPage.meta.nextCursor,
})
</script>
Best Practices
- Use offset for traditional UIs with page numbers
- Use cursor for infinite scroll, mobile apps, or large datasets
- Set maxLimit to prevent expensive queries
- Index cursor fields for performance (e.g.,
createdAt)
Testing
This guide covers how to write and run tests for Nuxt Auto API, including unit tests, integration tests, and E2E tests with both SQLite and Cloudflare D1.
Soft Deletes
Soft deletes mark records as deleted without removing them from the database.
