Clarify withCollections hot reload design

[AliiiBenn]

Current Implementation vs Expected Behavior

Current (Incorrect)

The current implementation of withCollections tries to load collections from a config file, which is not the intended design.

Expected Design

withCollections should ONLY be a hot reload mechanism, not a config loader.

1. Separate Configuration

Users define their collections using defineConfig from @deessejs/collections:

// collections/config.ts
import { defineConfig, collection, field, f, pgAdapter } from '@deessejs/collections'

// IMPORTANT: Use named export, not default export
export const { collections, db, $meta } = defineConfig({
  database: pgAdapter({ url: process.env.DATABASE_URL }),
  collections: [
    collection({
      slug: 'users',
      fields: {
        name: field({ fieldType: f.text() }),
        email: field({ fieldType: f.email() })
      }
    })
  ]
})

2. withCollections is Only for Hot Reload

The withCollections function should ONLY watch for config file changes and trigger Next.js hot reload:

// next.config.mjs
import { withCollections } from '@deessejs/collections/next'

export default withCollections({
  // Next.js config
}, {
  configPath: './collections/config.ts'
})

What withCollections should do:

• Watch the config file for changes
• Trigger Next.js hot reload when the config changes
• NOT load or process collections itself

3. Auto-Push on Config Change

When a config file changes during development, the following should happen:

1. Hot reload - Next.js triggers a rebuild
2. Auto push - The database schema is automatically pushed to the database

This uses the existing migration functions (push(), generate(), migrate()) from @deessejs/collections:

import { push, generate, migrate } from '@deessejs/collections'

Note: These functions currently use drizzle-kit CLI via child_process.spawn() since drizzle-kit doesn't provide a programmatic API.

4. Usage Pattern

Import collections directly from the config file where you defined them:

// lib/collections.ts
import { collections, db } from '@/collections/config'

// Re-export for convenience
export { collections, db }

Or import directly where needed:

// app/page.tsx
import { collections, db } from '@/collections/config'

// collections is an object keyed by slug
console.log(collections.users.fields)

// db is a Drizzle instance
await db.users.findMany()

Why This Design?

1. Separation of concerns: Config definition is separate from hot reload
2. Consistency: Matches how users already use defineConfig
3. Simplicity: withCollections has one job - trigger reload on config change
4. Flexibility: Users can import their collections however they want
5. Developer Experience: Auto-push makes development seamless

Implementation Notes

• Use Next.js webpack plugin API to watch config files
• Emit a warning or trigger reload when config changes
• The actual collections loading happens via normal imports
• Use child_process.spawn() to call drizzle-kit CLI for push operations

Related Functions

The following migration functions exist in @deessejs/collections but need implementation:

// packages/core/src/migrations.ts
export const push = async (adapter, collections) => { /* TODO */ }
export const generate = async (adapter, collections) => { /* TODO */ }
export const migrate = async (adapter) => { /* TODO */ }

These should be used by the Next.js hot reload mechanism to automatically push schema changes when config files are modified during development.