Adding Modules

This guide covers how to add optional Crouton modules to your existing Nuxt app. Each module provides domain-specific functionality with its own database tables, components, and APIs.

Quick Start with crouton add

The fastest way to add modules is using the CLI command:

# Add a single module (handles everything automatically)
crouton add auth

# Add multiple modules at once
crouton add bookings i18n

# Preview what will be done without making changes
crouton add auth --dry-run

# List all available modules
crouton add --list

The crouton add command automatically:

1. Installs the package via your package manager (pnpm/yarn/npm)
2. Updates nuxt.config.ts - adds to extends array
3. Updates server/db/schema.ts - adds schema exports (if applicable)
4. Generates database migrations
5. Applies migrations to your database

Available Modules

Auto-Included (with core)

These packages are automatically included when you install @fyit/crouton:

Optional Add-ons

Use crouton add <module> to install these optional packages:

CLI Options

Module Dependencies

Some optional modules require the core package (which includes auth). Since auth is auto-included with the core package, you only need to install the optional module:

The CLI handles dependencies automatically when you use crouton add.

Manual Installation Steps

If you prefer to install manually or need more control:

pnpm add @fyit/crouton-bookings

export default defineNuxtConfig({
  extends: [
    '@fyit/crouton',       // Includes auth, admin, i18n
    '@fyit/crouton-bookings'    // Add new module here
  ],
  modules: ['@nuxthub/core', '@nuxt/ui'],
  hub: { db: 'sqlite' }
})

// Existing exports
export * from '@fyit/crouton-auth/server/database/schema/auth'

// Add new module schemas
export * from '@fyit/crouton-bookings/server/database/schema'

npx nuxt db:generate

npx nuxt db:migrate

Module-Specific Setup

Auth Module (Auto-Included)

The auth module is automatically included with @fyit/crouton. No separate installation needed.

Required environment variables:

BETTER_AUTH_SECRET=your-secret-key-here
BETTER_AUTH_URL=http://localhost:3000

Optional OAuth providers:

GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=

i18n Module (Auto-Included)

The i18n module is automatically included with @fyit/crouton. No separate installation needed.

Optional locale configuration:

export default defineNuxtConfig({
  i18n: {
    locales: [
      { code: 'en', file: 'en.json' },
      { code: 'nl', file: 'nl.json' }
    ],
    langDir: './locales'
  }
})

Bookings Module

The bookings module provides a complete booking system.

crouton add bookings

The module provides components and composables. You'll typically generate collections using crouton config with a schema that references booking types.

Assets Module

The assets module provides file upload and media library functionality.

crouton add assets

Required NuxtHub config:

export default defineNuxtConfig({
  hub: {
    db: 'sqlite',
    blob: true  // Required for assets
  }
})

Troubleshooting

500 Server Error on API calls

Symptom: API endpoints return 500 errors after adding a module.

Cause: Database tables weren't created. The module's schema was added to nuxt.config.ts but migrations weren't generated/applied.

Solution:

# Generate migration for new tables
npx nuxt db:generate

# Apply the migration
npx nuxt db:migrate

If migrations were already generated but tables still don't exist:

sqlite3 .data/db/sqlite.db < server/db/migrations/sqlite/XXXX_migration.sql

"Cannot resolve entry module" error

Symptom: Build fails with "Cannot resolve entry module .nuxt/hub/db/schema.entry.ts"

Cause: Using hub: { database: true } instead of hub: { db: 'sqlite' }.

Solution:

// Wrong
hub: { database: true }

// Correct
hub: { db: 'sqlite' }

Module components not found

Symptom: Components from the module aren't available in templates.

Cause: Module not properly added to extends array.

Solution: Verify the module is listed in nuxt.config.ts:

extends: [
  '@fyit/crouton',
  '@fyit/crouton-bookings'  // Must be here
]

Then restart the dev server:

pnpm dev

Missing core package error

Symptom: Module features don't work or components aren't available.

Cause: The core package @fyit/crouton isn't installed.

Solution: Install the core package first:

pnpm add @fyit/crouton

The core package automatically includes auth, admin, and i18n—no need to install them separately.

Quick Reference

# List available modules
crouton add --list

# Add a module (automatic)
crouton add bookings

# Add multiple modules
crouton add bookings maps

# Preview what will happen
crouton add bookings --dry-run

# Skip migrations (configure manually later)
crouton add bookings --skip-migrations

# Force reinstall
crouton add bookings --force

Next Steps

• Schema Format - Define custom collections
• Troubleshooting - Common issues and solutions