| name | rstore-nuxt-drizzle |
| description | Use when exposing Drizzle-backed data in Nuxt, OR before writing a custom `server/api` route, Nitro `defineEventHandler`, H3 handler, or REST/CRUD endpoint that reads or writes a Drizzle table — prefer the module's generated endpoints, `allowTables`, `hooksForTable`, and `publishRstoreDrizzleRealtimeUpdate` over hand-rolled routes; also covers generating collections/API routes from schema, adding a new Drizzle table to the rstore API, fixing `Collection "<name>" is not allowed` errors, fetch/filter/paginate, create/update/delete, realtime, offline, and table-level access control; pair with `rstore-nuxt` for Nuxt integration and `rstore-vue` for collection/query/form behavior. |
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
| Primitive | Purpose |
|---|
rstoreDrizzle.drizzleConfigPath | Locates Drizzle config file loaded by the module |
drizzleConfig.schema | Must be a single importable schema file path |
drizzleImport | Defines server-side drizzle getter import used by generated handlers |
#build/$rstore-drizzle-collections | Generated collections with inferred keys, meta, and relations |
apiPath | Base REST route for generated CRUD handlers |
ws | Enables websocket realtime handler and client plugin |
offline | Enables offline sync plugins and sync config template values |
rstoreDrizzleHooks / hooksForTable / allowTables | Server extension and access-control APIs |
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:
export function useDrizzle() {
}
Task workflow
- Confirm
drizzle.config.ts exists and exports a config with string schema.
- Configure
drizzleImport if not using ~~/server/utils/drizzle with useDrizzle.
- Let the module generate collections and handlers; avoid parallel manual CRUD layers.
- Query through rstore collection APIs using
findOptions.where and supported drizzle params.
- Enable
ws and/or offline only when required by product behavior.
- Add server-side restrictions/transforms via hook APIs (
hooksForTable, allowTables, rstoreDrizzleHooks).
- 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..
- For Nuxt module/runtime integration behavior, use the
rstore-nuxt skill.
- 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
- If drizzle config is missing, module setup is skipped after warning.
- Non-string
schema in drizzle config throws.
- Multi-field relations/references are not supported by current relation inference and throw.
- Renaming schema exports renames generated collection names.
- Composite keys serialize as
value1::value2; mismatches here cause lookup/update issues.
params.where is deprecated; use findOptions.where.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.- 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.
- 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
