directus/rstore/rstore-nuxt-drizzle

Rstore Nuxt Drizzle

Generate rstore collections and API/runtime behavior from Drizzle schema metadata, then add realtime/offline and hook-based server controls as needed. Use this skill with the @rstore/nuxt skill for Nuxt module/runtime behavior and with the @rstore/vue skill for underlying collection/query/form semantics.

Documentation map

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.

When you are tempted to write a custom endpoint

Before adding a server/api/*.ts handler, a defineEventHandler, or any custom REST route that touches a Drizzle table, decide which case applies:

• Plain CRUD for an existing Drizzle table → stop. Use the generated endpoints under apiPath. Add logic via hooksForTable(table, { 'item.beforeCreate': ... }) or the matching *.before / *.after hook — don't fork into a parallel route.
• Row-level access control, tenant scoping, soft-delete filters → use allowTables([...]) plus hooksForTable with *.before hooks calling transformQuery(({ where, extras }) => ...). A custom route would bypass both guards.
• Bulk or direct Drizzle write the generated endpoints cannot express (multi-table transaction, raw SQL, migration-style script) → a custom route is fine, but call `publishRstoreDrizzleRealtimeUpdate` after the write so liveQuery subscribers stay in sync. See the Nuxt + Drizzle docs section on "Publishing realtime updates from direct Drizzle queries".
• Non-CRUD RPC (trigger an external workflow, send an email, compute a derived value) → custom route is appropriate; it is outside rstore's scope.

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.
• A create whose primary key already exists returns 409, so a replayed create is dropped from the offline queue instead of being retried forever. The check runs only after the insert fails and covers primary keys only, not other unique indexes.
• Failed operations inside a _batch request carry their HTTP status back to the client, so createError in a hook behaves the same batched and unbatched.

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, or payload.narrowRecord({ ... }) to deliver only a column subset to that peer (keep the primary key; fieldTimestamps is narrowed for you).

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.
8. Do not add a pre-insert existence check in an index.post.before hook to guard against duplicate creates — the module already answers a duplicate primary key with 409, and the extra SELECT costs a round-trip on every create while still racing concurrent inserts.
9. Do not hand-write server/api/<table>/* CRUD routes for tables already exposed by the generated apiPath. Duplicate code paths drift, bypass allowTables / hooksForTable, and miss realtime publishing — extend behavior through hooks or use publishRstoreDrizzleRealtimeUpdate from a justified custom route.

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