Package Architecture

Nuxt Crouton is a modular ecosystem consisting of a main module and multiple feature packages. The architecture provides flexibility through config-based feature enabling, keeping bundle sizes small while allowing you to use only what you need.

Architecture Overview

@fyit/crouton (main module)
│
├── Always includes:
│   └── @fyit/crouton-core (base CRUD layer)
│
├── Core add-ons (enabled by default):
│   ├── @fyit/crouton-auth (authentication)
│   ├── @fyit/crouton-admin (admin dashboard)
│   └── @fyit/crouton-i18n (translations)
│
├── Optional add-ons (disabled by default):
│   ├── @fyit/crouton-editor (TipTap)
│   ├── @fyit/crouton-flow (Vue Flow)
│   ├── @fyit/crouton-assets (media library)
│   ├── @fyit/crouton-maps (Mapbox)
│   ├── @fyit/crouton-ai (LLM integration)
│   ├── @fyit/crouton-email (Vue Email)
│   ├── @fyit/crouton-events (audit trail)
│   ├── @fyit/crouton-collab (real-time)
│   ├── @fyit/crouton-pages (CMS)
│   ├── @fyit/crouton-devtools (dev tools)
│   └── @fyit/crouton-themes (UI themes)
│
└── Mini-apps (experimental):
    ├── @fyit/crouton-bookings
    └── @fyit/crouton-sales

Main Module

@fyit/crouton

Purpose: Unified Nuxt module that aggregates all Crouton packages with opt-in features Install: pnpm add @fyit/crouton

This is the main entry point for the Crouton ecosystem. It automatically includes core features and allows enabling optional add-ons via configuration.

Configuration:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@fyit/crouton'],

  crouton: {
    // Global settings
    apiPrefix: '/api',
    defaultPageSize: 20,

    // Core add-ons (enabled by default, can disable)
    auth: true,
    admin: true,
    i18n: true,

    // Optional add-ons (disabled by default)
    editor: false,
    flow: false,
    assets: false,
    maps: false,
    ai: false,
    email: false,
    events: false,
    collab: false,
    pages: false,
    devtools: undefined,  // Auto-detect in dev mode
    themes: false,

    // Mini-apps (experimental, disabled by default)
    bookings: false,
    sales: false
  }
})

Minimal setup (core features only):

export default defineNuxtConfig({
  modules: ['@fyit/crouton']
  // Gets: core, auth, admin, i18n automatically
})

Core Packages (Auto-Included)

These packages are automatically included when you install @fyit/crouton. No separate installation needed.

@fyit/crouton-core

Purpose: Base CRUD layer with collections, composables, and components Status: Always included

Contains:

• Composables (useCollectionQuery, useCollectionMutation, useCrouton, useCroutonApps)
• Base components (CroutonCollection, CroutonFormActionButton, CroutonForm)
• Container management (slideover, modal, dialog, inline)
• Cache invalidation system
• App auto-discovery system
• TypeScript types

@fyit/crouton-auth

Purpose: Authentication layer with teams, passkeys, and 2FA Status: Enabled by default

Contains:

• Better Auth integration
• Team/organization management (multi-tenant, single-tenant, personal modes)
• Passkey/WebAuthn support
• Two-factor authentication (TOTP)
• OAuth providers (Google, GitHub, etc.)
• Auth composables (useAuth, useSession, useTeam)
• Pre-built auth components

Routes provided: /auth/* (login, register, forgot-password, etc.)

Disable if needed:

crouton: {
  auth: false  // Use your own auth system
}

@fyit/crouton-admin

Purpose: Super admin dashboard for system-wide management Status: Enabled by default

Contains:

• Super admin dashboard with stats
• User management (list, create, ban, unban, delete)
• Team oversight (view all teams/members)
• User impersonation (debug as any user)
• Super admin middleware

Routes provided: /super-admin/*

@fyit/crouton-i18n

Purpose: Translation and multi-language support Status: Enabled by default

Contains:

• CroutonI18nInput component
• LanguageSwitcher component
• DevModeToggle component
• useEntityTranslations composable
• useT composable for translations
• Database-backed team overrides

Provides:

• common.* - Generic UI strings
• forms.* - Form field labels
• errors.* - Error messages
• time.* - Time formatting strings
• navigation.* - Navigation labels

Optional Add-ons

Enable these features in your crouton config as needed.

@fyit/crouton-editor

Purpose: Rich text editing with Tiptap Enable: crouton: { editor: true }

Contains:

• EditorSimple component (WYSIWYG editor)
• EditorToolbar component
• Tiptap integration
• Pre-configured extensions

When to use: Blog posts, descriptions, content management

@fyit/crouton-ai

Purpose: AI chat and completion integration Enable: crouton: { ai: true }

Contains:

• useChat() composable (streaming chat with conversation history)
• useCompletion() composable (single-turn text completion)
• useAIProvider() composable (provider/model configuration)
• CroutonAiChatbox, CroutonAiMessage, CroutonAiInput components
• Server utilities for OpenAI and Anthropic
• Chat conversations persistence schema

Environment Variables:

NUXT_OPENAI_API_KEY=sk-...
NUXT_ANTHROPIC_API_KEY=sk-ant-...

@fyit/crouton-assets

Purpose: Centralized asset management with NuxtHub blob storage Enable: crouton: { assets: true }

Contains:

• CroutonAssetsPicker component (visual asset browser)
• CroutonAssetsUploader component (file upload with metadata)
• useAssetUpload() composable
• Assets collection schema
• NuxtHub blob storage integration

Requires: hub: { blob: true } in nuxt.config

@fyit/crouton-events

Purpose: Event management with audit trail Enable: crouton: { events: true }

Contains:

• Lifecycle hooks (beforeCreate, afterUpdate, etc.)
• Custom event handlers
• Event bus integration
• Webhooks support
• Audit trail tracking

@fyit/crouton-maps

Purpose: Map integration with location fields Enable: crouton: { maps: true }

Contains:

• Map display components
• Location input fields with geocoding
• Marker and pin support
• Address autocomplete

@fyit/crouton-flow

Purpose: Visual flow builder with drag-and-drop Enable: crouton: { flow: true }

Contains:

• Visual flow editor component
• Configurable node types
• Flow execution engine
• Flow collection schema
• Vue Flow integration

@fyit/crouton-email

Purpose: Email infrastructure with Vue Email templates and Resend Enable: crouton: { email: true }

Contains:

• useEmailService() composable
• Convenience senders (sendVerificationEmail, sendMagicLink, etc.)
• Vue Email templates
• Client flow components (EmailVerificationFlow, MagicLinkSent)
• Resend integration

Environment Variables:

RESEND_API_KEY=re_xxx

Integration: Works with @fyit/crouton-auth for auth emails

@fyit/crouton-collab

Purpose: Real-time collaboration with Yjs CRDTs Enable: crouton: { collab: true }

Contains:

• Cloudflare Durable Objects for Yjs sync
• useCollabConnection, useCollabSync, useCollabPresence composables
• useCollabEditor for TipTap integration
• CollabStatus, CollabPresence, CollabCursors components
• Presence tracking and cursor sharing

Room types: page (TipTap), flow (graphs), document (text), generic

Note: Sync mode requires Cloudflare Durable Objects

@fyit/crouton-pages

Purpose: CMS-like page management system Enable: crouton: { pages: true }

Contains:

• Page types from app packages
• Tree/sortable layout for page ordering
• Public page rendering at /[team]/[slug]
• Block-based page editor
• Custom domain support with automatic team resolution
• usePageTypes, useDomainContext, useNavigation composables

URL Structure:

• Public pages: /[team]/[slug]
• Admin: /admin/[team]/pages

@fyit/crouton-devtools

Purpose: Development tools and debugging utilities Enable: crouton: { devtools: true } (auto-detected in dev mode)

Contains:

• Debug panel for inspecting collections
• API explorer for testing endpoints
• Schema viewer for collection schemas
• Development helpers

Note: Auto-enabled in development mode

@fyit/crouton-themes

Purpose: Swappable UI themes for Nuxt UI applications Enable: crouton: { themes: true } or extend directly

Available Themes:

Usage (theme-specific extend):

export default defineNuxtConfig({
  extends: ['@fyit/crouton-themes/ko']
})

Contains:

• Design tokens (CSS custom properties)
• Nuxt UI component variant overrides (variant="ko")
• Theme-specific components (KoLed, KoKnob, KoPanel)

Experimental Mini-Apps

These are experimental domain-specific applications built on Crouton. APIs may change.

@fyit/crouton-bookings

Purpose: Booking system for slots and inventory Enable: crouton: { bookings: true }Status: Experimental ⚠️

Contains:

• Slot-based bookings (courts, rooms, appointments)
• Inventory-based reservations (equipment, rentals)
• Customer booking wizard
• useBookingAvailability, useBookingCart composables
• Email template management (opt-in)

Requires: @fyit/crouton-auth, optionally @fyit/crouton-email

@fyit/crouton-sales

Purpose: Event-based Point of Sale (POS) system Enable: crouton: { sales: true }Status: Experimental ⚠️

Contains:

• Products, categories, orders
• Customer-facing order interface
• Helper authentication (PIN-based)
• Optional thermal receipt printing
• usePosOrder, useHelperAuth composables

Requires: @fyit/crouton-auth

Development Tools (Not Runtime)

These packages are used during development and are not included in your production bundle.

@fyit/crouton-cli

Purpose: CLI tool for code generation Install: pnpm add -D @fyit/crouton-cli

Commands:

crouton generate <layer> <collection>
crouton rollback <layer> <collection>
crouton rollback-bulk --layer=<name>
crouton rollback-interactive
crouton init
crouton install

Key insight: Dev-time dependency only. Generated code doesn't depend on it.

@fyit/crouton-mcp

Purpose: MCP server for AI-assisted collection generation Install: Dev tool, configured in .claude/settings.json

Contains:

• Schema design tools
• Validation tools
• CLI wrapper for generation
• Collection/layer scanning

Tools: design_schema, validate_schema, generate_collection, list_collections, dry_run, rollback

@fyit/crouton-designer

Purpose: Visual schema design tool Install: Dev tool

Contains:

• Visual schema builder UI
• Field type selector
• Schema export to JSON

Installation Patterns

Standard Setup (Recommended)

# Install main module
pnpm add @fyit/crouton

# Install CLI for code generation (dev dependency)
pnpm add -D @fyit/crouton-cli

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@fyit/crouton']
  // Gets: core, auth, admin, i18n automatically
})

Enable Optional Features

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@fyit/crouton'],

  crouton: {
    // Enable features you need
    editor: true,
    assets: true,
    events: true,
    pages: true
  }
})

Full-Featured App

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@fyit/crouton'],

  crouton: {
    // All optional features
    editor: true,
    flow: true,
    assets: true,
    maps: true,
    ai: true,
    email: true,
    events: true,
    collab: true,
    pages: true
  }
})

Booking Application

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@fyit/crouton'],

  crouton: {
    bookings: true,
    email: true,
    pages: true
  }
})

Three-Tier Route Architecture

Field Types and Required Packages

When defining collection schemas, certain field types require specific features to be enabled.

Why This Architecture?

Benefits

1. Small Bundle Sizes

• Only include what you need
• Features are tree-shaken when disabled
• No unused code in production

2. Independent Updates

• Core can be updated without breaking add-ons
• Add-ons can evolve independently
• Generator improvements don't require core updates

3. Clear Separation

• Generated code vs runtime code
• Core features vs optional add-ons
• Development tools vs production dependencies

4. Flexible Adoption

• Start simple, add complexity as needed
• Disable features you're not using
• Mix and match capabilities

Design Decisions

Q: Why is the generator a separate package? A: It's a dev-time tool. Your production app doesn't need the generator, templates, or CLI code.

Q: Why use module-based config instead of extends? A: Cleaner config, better tree-shaking, and automatic feature discovery.

Q: Can I use the core without the module? A: Yes! You can extend individual packages directly if you prefer the layer pattern.

Q: Do add-ons depend on each other? A: Mostly no. Each add-on depends on core. Some have optional integrations (e.g., email + auth).

Troubleshooting

"Module not found: @fyit/crouton"

The core package isn't installed:

pnpm add @fyit/crouton

"crouton-generate command not found"

The generator isn't installed:

pnpm add -D @fyit/crouton-cli

Feature component not found

Make sure the feature is enabled:

crouton: {
  editor: true  // Enable the feature
}

TypeScript errors after enabling feature

Run Nuxt prepare to regenerate types:

npx nuxt prepare
npx nuxt typecheck

Related Sections

• Installation - Setup guide
• Generator Commands - CLI usage
• Team-Based Auth - Authentication with teams
• Admin Dashboard - User management
• Translations - i18n feature
• AI Integration - AI feature