Rstore Nuxt Drizzle

Core concepts

Quick start

export default defineNuxtConfig({
  modules: ['@rstore/nuxt-drizzle'],
  rstoreDrizzle: {
    drizzleImport: {
      name: 'useDrizzle',
      from: '~~/server/utils/drizzle',
    },
    apiPath: '/api/rstore',
  },
})

Also provide the server import the module expects by default:

// server/utils/drizzle.ts
export function useDrizzle() {
  // return your drizzle instance
}

Task workflow

1. Confirm drizzle.config.ts exists and exports a config with string schema.
2. Configure drizzleImport if not using ~~/server/utils/drizzle with useDrizzle.
3. Let the module generate collections and handlers; avoid parallel manual CRUD layers.
4. Query through rstore collection APIs using findOptions.where and supported drizzle params.
5. Enable ws and/or offline only when required by product behavior.
6. Add server-side restrictions/transforms via hook APIs (hooksForTable, allowTables, rstoreDrizzleHooks).
7. When adding a new Drizzle table to a project that already calls allowTables, register the new table in the same allowTables([...]) list — once initialized the allow-list is permanent and unlisted tables throw Collection "<name>" is not allowed..
8. For Nuxt module/runtime integration behavior, use the rstore-nuxt skill.
9. For non-drizzle-specific store/query/form behavior, use the rstore-vue skill.

Query and cache conventions

• Prefer findOptions.where over the deprecated params.where.
• Use findOptions.include for relation loading; relation include objects support where, orderBy, columns, limit, and nested include.
• Use params.limit, offset, columns, orderBy, and keys to shape Drizzle-backed queries.
• Use params.with only as a low-level Drizzle override; when both are provided, params.with takes precedence over findOptions.include.
• Query params and request bodies are serialized with SuperJSON, so keep them serializable.
• The runtime plugin parses createdAt and updatedAt string values into Date objects through collection defaults.
• fetchRelations translates included relations into follow-up equality queries against the generated target collections.
• Cache filtering for findFirst and findMany reuses the same where and orderBy semantics client-side.

Realtime and offline behavior

• ws: true (or object form) enables websocket handler registration and client subscription plugin wiring.
• Realtime subscriptions are keyed by collection, key, and where; exact filter shape impacts topic reuse.
• On websocket reconnect, the runtime re-sends active subscriptions and triggers realtimeReconnectEventHook, which makes liveQuery refresh.
• offline enables offline plugin generation and sync config wiring.
• Offline sync expects stable keys and usable updatedAt comparison values.
• offline.serializeDateValue exists for non-default date comparison serialization.

Server extension points

• Use hooksForTable(table, hooks) to scope API hooks to a specific Drizzle table.
• Use rstoreDrizzleHooks.hook(...) when the extension needs to work across multiple tables.
• *.before hooks can call transformQuery(({ where, extras }) => ...) to add constraints before execution.
• Use allowTables([...]) to deny access to unlisted generated collections.
• Use the realtime.filter hook to reject websocket updates for a peer when row-level rules apply.

Guardrails

1. If drizzle config is missing, module setup is skipped after warning.
2. Non-string schema in drizzle config throws.
3. Multi-field relations/references are not supported by current relation inference and throw.
4. Renaming schema exports renames generated collection names.
5. Composite keys serialize as value1::value2; mismatches here cause lookup/update issues.
6. params.where is deprecated; use findOptions.where.
7. allowTables flips the default from "all tables exposed" to "deny by default". After the first call, every new Drizzle table you add to the schema must also be added to allowTables — otherwise endpoints throw Collection "<name>" is not allowed. at runtime.

References

Further reading

• Nuxt + Drizzle docs: https://rstore.akryum.dev/plugins/nuxt-drizzle
• Query docs: https://rstore.akryum.dev/guide/data/query
• Live docs: https://rstore.akryum.dev/guide/data/live
• Offline docs: https://rstore.akryum.dev/guide/data/offline
• @rstore/nuxt skill: rstore-nuxt
• @rstore/vue skill: rstore-vue