rstore-nuxt

name

rstore-nuxt

description

Use when wiring rstore into a Nuxt app end-to-end — module setup, auto-registered collections/plugins, SSR cache hydration, generated template/auto-import issues, and cross-module extension; also use before adding a custom `server/api` route, Nitro handler, or ad hoc `useFetch`/`$fetch` composable for collection data in an rstore-powered Nuxt app — prefer rstore collection APIs (`find*`, `query`, `liveQuery`) and plugin hooks over hand-rolled endpoints or fetch refs; pair with the `rstore-vue` skill for collection/query/form behavior.

Rstore Nuxt

Wire @rstore/vue into Nuxt through module scanning, generated templates, SSR hydration, and devtools integration. Use this skill together with the @rstore/vue skill for collection/query/form semantics.

Documentation map

Area	Documentation
Nuxt setup	https://rstore.akryum.dev/guide/getting-started#nuxt
Collections and relations	https://rstore.akryum.dev/guide/schema/collection, https://rstore.akryum.dev/guide/schema/relations
Query and mutation model	https://rstore.akryum.dev/guide/data/query, https://rstore.akryum.dev/guide/data/mutation
Cache and live updates	https://rstore.akryum.dev/guide/data/cache, https://rstore.akryum.dev/guide/data/live
Plugin extension model	https://rstore.akryum.dev/guide/plugin/setup, https://rstore.akryum.dev/guide/plugin/hooks
Related package skills	rstore-vue skill (@rstore/vue)
Skill-local API references	./references/index.md

Core concepts

Primitive	Purpose
rstore.rstoreDirs	Per-layer directories scanned for collections and plugins
<rstoreDir>/*.ts	Collection/relations exports included in generated schema
<rstoreDir>/plugins/*.ts	Plugin exports included in generated plugin list
#build/$rstore-collection	Generated schema template from scanned collection files
#build/$rstore-plugins	Generated plugin exports from scanned plugin files
#build/$restore-options	Generated options template (experimentalGarbageCollection)
Runtime plugin layer	Creates store, installs plugin, serializes/hydrates cache, injects $rstore
addCollectionImport / addPluginImport	Public extension hooks for other Nuxt modules

Quick start

export default defineNuxtConfig({
  modules: ['@rstore/nuxt'],
  rstore: {
    rstoreDirs: ['rstore'],
  },
})

Expected layout:

rstore/
  todos.ts
  users.ts
  plugins/
    remote.ts

Task workflow

1. Register @rstore/nuxt in modules.
2. Keep collections and plugin files inside configured rstoreDirs.
3. Ensure collection files export default or named const values intended for schema assembly.
4. Use useStore() and auto-imports from #imports in app code, not ad hoc store singletons. Before adding a server/api/*.ts handler, a defineEventHandler, or a useFetch/$fetch composable for collection data, check whether a collection API (find*, query, liveQuery) or a plugin hook already covers it — if the data is Drizzle-backed, see the rstore-nuxt-drizzle skill for the generated endpoint + hook story.
5. For cross-module extension, call addCollectionImport / addPluginImport from module setup.
6. Validate generated template output when debugging scan/injection issues.
7. For behavior inside collection APIs (find*, query, forms, hooks), use the rstore-vue skill.

Rely on the generated runtime

• Auto-imports include withItemType, defineCollection, defineRstorePlugin, defineRstoreModule, useStore, RStoreSchema, plus related types.
• The module generates and uses #build templates instead of requiring manual registry wiring.
• The runtime plugin serializes cache state to nuxtApp.payload.state.$srstore on render and hydrates on client load.
• In development, a devtools plugin is appended automatically by runtime code.
• experimentalGarbageCollection is passed from module options into createStore.

Extending from another Nuxt module

• addCollectionImport(nuxt, importPath) appends import sources merged into generated schema.
• addPluginImport(nuxt, importPath) appends plugin imports merged into generated plugin list.
• Use these APIs instead of mutating _rstoreCollectionImports/_rstorePluginImports directly.
• Imported collection modules should export values that are valid store schema entries.

Guardrails

1. Collection scan warns when files export neither default nor named const.
2. Files in scanned collection directories should stay export-focused; extra exported helpers can be pulled into schema by Object.values(...).
3. Avoid creating your own second Nuxt-side store instance; runtime plugin owns app store lifecycle.
4. Debug missing data by inspecting generated #build/$rstore-collection and #build/$rstore-plugins.
5. Devtools route /__rstore is module-owned and served/proxied by setupDevToolsUI; do not duplicate that wiring in app code.

References

Topic	Description	Reference
API index	Full map of Nuxt API/config references	api-index
rstore.rstoreDirs	Collection/plugin scan directory option	api-rstore-dirs
rstore.experimentalGarbageCollection	Pass-through garbage collection option	api-experimental-garbage-collection
addCollectionImport	Extend generated collection imports	api-add-collection-import
addPluginImport	Extend generated plugin imports	api-add-plugin-import
defineRstorePlugin	Nuxt alias for definePlugin	api-define-rstore-plugin
defineRstoreModule	Nuxt alias for defineModule	api-define-rstore-module
RStoreSchema	Namespaced schema helper object	api-rstore-schema
useStore (#imports)	Nuxt runtime store accessor	api-use-store
SSR cache hydration ($srstore)	Payload cache serialization/hydration	api-cache-hydration
Devtools route (/__rstore)	Custom devtools UI route wiring	api-devtools-route

Further reading

• Getting started (Nuxt): https://rstore.akryum.dev/guide/getting-started#nuxt
• Query docs: https://rstore.akryum.dev/guide/data/query
• Cache docs: https://rstore.akryum.dev/guide/data/cache
• Plugin hook docs: https://rstore.akryum.dev/guide/plugin/hooks