Fundamentals

Package Architecture

Understanding the Nuxt Crouton ecosystem and package structure

Nuxt Crouton is a modular ecosystem consisting of 11 packages (1 core, 1 generator CLI, and 9 addon layers). This architecture provides flexibility, keeps bundle sizes small, and allows you to use only what you need.

Core Packages

1. @friendlyinternet/nuxt-crouton

Purpose: Core runtime library Install: pnpm add @friendlyinternet/nuxt-crouton

Contains:

Composables (useCollectionQuery, useCollectionMutation, useCrouton)
Base components (CroutonList, CroutonButton, CroutonForm)
Modal management
Cache invalidation system
TypeScript types

When to use:

Required for all Nuxt Crouton projects
This is the foundation everything else builds on

Config:

// nuxt.config.ts
export default defineNuxtConfig({
  extends: ['@friendlyinternet/nuxt-crouton']
})

2. @friendlyinternet/nuxt-crouton-collection-generator

Purpose: CLI tool for code generation Install: npm install -g @friendlyinternet/nuxt-crouton-collection-generator

Contains:

CLI commands (crouton-generate, crouton-rollback)
Code generators
Template system
Schema validation

When to use:

During development to generate collections
Not needed in production (generated code doesn't depend on it)

Commands:

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

Key insight: This is a dev-time dependency, not a runtime dependency. Once code is generated, your app doesn't need this package.

3. @friendlyinternet/nuxt-crouton-i18n

Purpose: Translation and multi-language support Install: pnpm add @friendlyinternet/nuxt-crouton-i18n

Contains:

TranslationsInput component
LanguageSwitcher component
DevModeToggle component
useEntityTranslations composable
Translation management UI

When to use:

Building multi-language applications
Need per-field translation UI
Want automatic locale-based data fetching

Config:

// nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    '@friendlyinternet/nuxt-crouton',
    '@friendlyinternet/nuxt-crouton-i18n'  // Add this
  ]
})

Optional: Only install if you need translations.

4. @friendlyinternet/nuxt-crouton-editor

Purpose: Rich text editing with Tiptap Install: pnpm add @friendlyinternet/nuxt-crouton-editor

Contains:

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

When to use:

Need rich text editing (blog posts, descriptions, content)
Want WYSIWYG instead of plain textareas

Config:

// nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    '@friendlyinternet/nuxt-crouton',
    '@friendlyinternet/nuxt-crouton-editor'  // Add this
  ]
})

Optional: Only install if you need rich text editing.

5. @friendlyinternet/nuxt-crouton-supersaas

Purpose: SuperSaaS integration layer - connectors, app-level translations, and utilities Install: pnpm add @friendlyinternet/nuxt-crouton-supersaas

Contains:

SuperSaaS connector (team-based user management)
App-level i18n locale files (common UI strings)
External collection utilities
API endpoint helpers

When to use:

Building apps with SuperSaaS for team/user management
Need to reference users from your auth system in forms
Want pre-built app-level translations (common UI, auth, navigation, teams, errors)
Building multi-tenant apps with team-scoped user selection

Config:

// app.config.ts
import { usersConfig } from './composables/useUsers'

export default defineAppConfig({
  croutonCollections: {
    users: usersConfig
  }
})

i18n Locale Files: This package includes app-level translation strings (en, nl, fr) that merge with your layer translations. See SuperSaaS Integration for details.

Optional: Only install if you're using SuperSaaS or need the bundled translations.

6. @friendlyinternet/nuxt-crouton-ai

Purpose: AI chat and completion integration Install: pnpm add @friendlyinternet/nuxt-crouton-ai

Contains:

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

When to use:

Building AI-powered chat interfaces
Need text completion/generation
Want multi-provider support (OpenAI, Anthropic)

Config:

// nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    '@friendlyinternet/nuxt-crouton',
    '@friendlyinternet/nuxt-crouton-ai'
  ]
})

Environment Variables:

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

Optional: Only install if you need AI features.

7. @friendlyinternet/nuxt-crouton-assets

Purpose: Centralized asset management with NuxtHub blob storage Install: pnpm add @friendlyinternet/nuxt-crouton-assets

Contains:

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

When to use:

Building a centralized media library
Need reusable assets across collections
Want visual asset picker in forms

Config:

// nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    '@friendlyinternet/nuxt-crouton',
    '@friendlyinternet/nuxt-crouton-assets'
  ],
  hub: {
    blob: true  // Required for blob storage
  }
})

Optional: Only install if you need centralized asset management.

8. @friendlyinternet/nuxt-crouton-events

Purpose: Event management with calendar integration Install: pnpm add @friendlyinternet/nuxt-crouton-events

Contains:

Calendar components for event scheduling
Date/time picker fields
Recurring event patterns
Event collection schema

When to use:

Building event management features
Need calendar UI components
Want date/time aware form fields

Config:

// nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    '@friendlyinternet/nuxt-crouton',
    '@friendlyinternet/nuxt-crouton-events'
  ]
})

Optional: Only install if you need event/calendar features.

9. @friendlyinternet/nuxt-crouton-maps

Purpose: Map integration with location fields Install: pnpm add @friendlyinternet/nuxt-crouton-maps

Contains:

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

When to use:

Building location-aware features
Need map display in your app
Want address input with geocoding

Config:

// nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    '@friendlyinternet/nuxt-crouton',
    '@friendlyinternet/nuxt-crouton-maps'
  ]
})

Optional: Only install if you need map features.

10. @friendlyinternet/nuxt-crouton-flow

Purpose: Visual flow builder with drag-and-drop Install: pnpm add @friendlyinternet/nuxt-crouton-flow

Contains:

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

When to use:

Building workflow automation features
Need visual flow/diagram builder
Want drag-and-drop workflow creation

Config:

// nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    '@friendlyinternet/nuxt-crouton',
    '@friendlyinternet/nuxt-crouton-flow'
  ]
})

Optional: Only install if you need workflow/flow features.

11. @friendlyinternet/nuxt-crouton-devtools

Purpose: Development tools and debugging utilities Install: pnpm add @friendlyinternet/nuxt-crouton-devtools

Contains:

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

When to use:

During development for debugging
Want to inspect collection state
Need to test generated APIs

Config:

// nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    '@friendlyinternet/nuxt-crouton',
    '@friendlyinternet/nuxt-crouton-devtools'  // Dev only
  ]
})

Optional: Only install during development.

Package Dependencies

┌─────────────────────────────────────┐
│  Your Nuxt App                      │
│  - Generated collections            │
│  - Custom components                │
└─────────────────────────────────────┘
              │ depends on
              ↓
┌─────────────────────────────────────┐
│  @friendlyinternet/nuxt-crouton     │ ← Core (Required)
│  - Composables, components          │
└─────────────────────────────────────┘
              ↑
              │ extends (pick what you need)
    ┌─────────┼────────┬────────┬────────┬────────┐
    │         │        │        │        │        │
┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ ...
│ i18n  │ │editor │ │super- │ │  ai   │ │assets │
│       │ │       │ │ saas  │ │       │ │       │
└───────┘ └───────┘ └───────┘ └───────┘ └───────┘

Additional addons: events, maps, flow, devtools

        (generator CLI is dev-only, not shown in runtime graph)

Installation Patterns

Minimal Setup (No Translations, No Editor)

pnpm add @friendlyinternet/nuxt-crouton
npm install -g @friendlyinternet/nuxt-crouton-collection-generator

// nuxt.config.ts
export default defineNuxtConfig({
  extends: ['@friendlyinternet/nuxt-crouton']
})

Full Featured Setup

# Core
pnpm add @friendlyinternet/nuxt-crouton
pnpm add -D @friendlyinternet/nuxt-crouton-collection-generator

# All addon layers
pnpm add @friendlyinternet/nuxt-crouton-i18n
pnpm add @friendlyinternet/nuxt-crouton-editor
pnpm add @friendlyinternet/nuxt-crouton-supersaas
pnpm add @friendlyinternet/nuxt-crouton-ai
pnpm add @friendlyinternet/nuxt-crouton-assets
pnpm add @friendlyinternet/nuxt-crouton-events
pnpm add @friendlyinternet/nuxt-crouton-maps
pnpm add @friendlyinternet/nuxt-crouton-flow
pnpm add @friendlyinternet/nuxt-crouton-devtools

// nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    '@friendlyinternet/nuxt-crouton',
    '@friendlyinternet/nuxt-crouton-i18n',
    '@friendlyinternet/nuxt-crouton-editor',
    '@friendlyinternet/nuxt-crouton-supersaas',
    '@friendlyinternet/nuxt-crouton-ai',
    '@friendlyinternet/nuxt-crouton-assets',
    '@friendlyinternet/nuxt-crouton-events',
    '@friendlyinternet/nuxt-crouton-maps',
    '@friendlyinternet/nuxt-crouton-flow',
    '@friendlyinternet/nuxt-crouton-devtools',
  ]
})

// app.config.ts (for connector)
import { usersConfig } from './composables/useUsers'

export default defineAppConfig({
  croutonCollections: {
    users: usersConfig
  }
})

Add Features Later

Start minimal, add addons as needed:

# Start with core
pnpm add @friendlyinternet/nuxt-crouton

# Later: add translations
pnpm add @friendlyinternet/nuxt-crouton-i18n

# Later: add rich text
pnpm add @friendlyinternet/nuxt-crouton-editor

# Later: add SuperSaaS integration
pnpm add @friendlyinternet/nuxt-crouton-supersaas

# Later: add AI features
pnpm add @friendlyinternet/nuxt-crouton-ai

# Later: add asset management
pnpm add @friendlyinternet/nuxt-crouton-assets

# Later: add calendar/events
pnpm add @friendlyinternet/nuxt-crouton-events

# Later: add maps
pnpm add @friendlyinternet/nuxt-crouton-maps

# Later: add visual flows
pnpm add @friendlyinternet/nuxt-crouton-flow

Why This Architecture?

✅ Benefits

1. Small Bundle Sizes

Only include what you need
No unused translation code if you don't need i18n
No Tiptap bundle if you don't need rich text

2. Independent Updates

Core can be updated without breaking addons
Addons can evolve independently
Generator improvements don't require core updates

3. Clear Separation

Generated code vs runtime code
Core features vs optional addons
Development tools vs production dependencies

4. Flexible Adoption

Start simple, add complexity as needed
Remove addons you're not using
Mix and match features

🎯 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. Keeping it separate reduces bundle size.

Q: Why are i18n, editor, and supersaas separate? A: Not every app needs translations, rich text, or SuperSaaS integration. By making them optional, we keep the core package lean.

Q: Can I use the core without the generator? A: Yes! You can write components manually and still use the core composables and utilities.

Q: Do addons depend on each other? A: No. Each addon only depends on the core. You can use i18n without editor or supersaas, and vice versa.

Field Types and Required Packages

When defining collection schemas, certain field types require additional packages to be installed. The generator does not automatically install these dependencies—you must install them manually.

Field Type → Package Mapping

Field Type	Required Package	Install Command
`editor`	`@friendlyinternet/nuxt-crouton-editor`	`pnpm add @friendlyinternet/nuxt-crouton-editor`
`i18n` / `translation`	`@friendlyinternet/nuxt-crouton-i18n`	`pnpm add @friendlyinternet/nuxt-crouton-i18n`
`asset` (refTarget: assets)	`@friendlyinternet/nuxt-crouton-assets`	`pnpm add @friendlyinternet/nuxt-crouton-assets`
`map` / `location`	`@friendlyinternet/nuxt-crouton-maps`	`pnpm add @friendlyinternet/nuxt-crouton-maps`
`flow`	`@friendlyinternet/nuxt-crouton-flow`	`pnpm add @friendlyinternet/nuxt-crouton-flow`

Example

If your schema uses an editor field type:

product-schema.json

[
  { "name": "title", "type": "string" },
  { "name": "content", "type": "editor" }
]

You must install the editor package:

pnpm add @friendlyinternet/nuxt-crouton-editor

And add it to your nuxt.config.ts:

nuxt.config.ts

export default defineNuxtConfig({
  extends: [
    '@friendlyinternet/nuxt-crouton',
    '@friendlyinternet/nuxt-crouton-editor'  // Required for 'editor' field type
  ]
})

Tip: Check your schema files for special field types before running the generator. Install all required packages first to avoid runtime errors.

Package Versions

Nuxt Crouton follows semantic versioning:

Core package version: 1.2.0

Major: Breaking changes
Minor: New features (backward compatible)
Patch: Bug fixes

Addon packages: Independent versions

Each addon can update independently
Core version compatibility specified in peer dependencies

Check versions:

pnpm list @friendlyinternet/nuxt-crouton
pnpm list @friendlyinternet/nuxt-crouton-i18n
pnpm list @friendlyinternet/nuxt-crouton-editor
pnpm list @friendlyinternet/nuxt-crouton-supersaas
pnpm list @friendlyinternet/nuxt-crouton-ai
pnpm list @friendlyinternet/nuxt-crouton-assets
pnpm list @friendlyinternet/nuxt-crouton-events
pnpm list @friendlyinternet/nuxt-crouton-maps
pnpm list @friendlyinternet/nuxt-crouton-flow
pnpm list @friendlyinternet/nuxt-crouton-devtools

Troubleshooting

"Module not found: @friendlyinternet/nuxt-crouton"

The core package isn't installed:

pnpm add @friendlyinternet/nuxt-crouton

"TranslationsInput is not defined"

The i18n addon isn't installed:

pnpm add @friendlyinternet/nuxt-crouton-i18n

Then add to nuxt.config.ts extends.

"EditorSimple is not defined"

The editor addon isn't installed:

pnpm add @friendlyinternet/nuxt-crouton-editor

Then add to nuxt.config.ts extends.

"crouton-generate command not found"

The generator isn't installed globally:

npm install -g @friendlyinternet/nuxt-crouton-collection-generator

Peer dependency warnings

Install the required peer dependencies:

pnpm add @nuxt/ui @nuxt/icon

Installation - Setup guide
Generator Commands - CLI usage
Translations - i18n addon
SuperSaaS Integration - SuperSaaS addon
AI Integration - AI chat and completion addon
Assets - Asset management addon
Collections & Layers - Understanding the structure

Caching

How caching works in Nuxt Crouton

Generated vs Core Code

Understanding the difference between generated code and core library