Getting Started

Installation

Install and configure Nuxt Crouton in your nuxt 4 project.

Here's how to install and configure Nuxt Crouton in your Nuxt 4 project.

Nuxt 4 Required: Nuxt Crouton requires Nuxt 4 and Nuxt UI 4. It will not work with Nuxt 3 due to the app/ directory structure convention used by layers. See Troubleshooting - Layer Pages 404 if you encounter routing issues.

Prerequisites

You'll need Node.js 18 or 20+, pnpm (recommended) or npm, Nuxt 4.x, and Nuxt UI 4.x. We also recommend using the SuperSaaS starter template for a complete SaaS setup.

Install Nuxt Crouton

# Install core package
pnpm add @friendlyinternet/nuxt-crouton

# Install generator (dev dependency)
pnpm add -D @friendlyinternet/nuxt-crouton-collection-generator

# Optional: i18n support
pnpm add @friendlyinternet/nuxt-crouton-i18n

# Optional: Rich text editor
pnpm add @friendlyinternet/nuxt-crouton-editor @nuxt/icon

Configure Nuxt

Add Nuxt Crouton to your nuxt.config.ts:

nuxt.config.ts

export default defineNuxtConfig({
  extends: [
    '@friendlyinternet/nuxt-crouton',
    // '@friendlyinternet/nuxt-crouton-i18n',     // If using translations
    // '@friendlyinternet/nuxt-crouton-editor',   // If using rich text editor
  ],

  // Recommended: Enable hot reload for development
  vite: {
    server: {
      watch: {
        ignored: ['!**/node_modules/@friendlyinternet/**']
      }
    },
    optimizeDeps: {
      exclude: ['@friendlyinternet/nuxt-crouton']
    }
  }
})

Configure Tailwind CSS

Nuxt Crouton layers use Tailwind CSS classes that need to be scanned by the Tailwind compiler. Due to how Tailwind CSS v4 works with Nuxt Layers, you need to add the @source directive to your app's CSS file to ensure layer components are properly styled.

Automatic Setup: The collection generator (crouton-generate) and installer (crouton-install) will automatically configure the @source directive for you! If you run either of these commands, you can skip manual configuration.

Automatic Setup (Recommended)

When you run the generator or installer, it will:

Detect your existing CSS file (or create app/assets/css/main.css)
Add the required @source directive automatically
Update nuxt.config.ts if a new CSS file was created

# The generator sets up CSS automatically
npx crouton-generate <layer> <collection> --fields-file=./schema.json

Manual Setup

If automatic setup fails or you prefer manual configuration, create or update your main CSS file (e.g., app/assets/css/main.css):

app/assets/css/main.css

@import "tailwindcss";
@import "@nuxt/ui";

/* Scan Nuxt Crouton layers - REQUIRED for proper styling */
@source "../../../node_modules/@friendlyinternet/nuxt-crouton*/app/**/*.{vue,js,ts}";

The @source directive path is relative to your CSS file location. Adjust the ../ depth based on where your CSS file is located:

If CSS is at app/assets/css/main.css: use "../../../node_modules/..."
If CSS is at app.css: use "../node_modules/..."

Why is this needed? Tailwind CSS v4 doesn't automatically scan external layers in node_modules. The @source directive explicitly tells Tailwind where to find classes used in layer components. Without this, hover states and dynamic classes won't work. Learn more

For Multiple Layers

The wildcard pattern nuxt-crouton*/ automatically scans all installed Nuxt Crouton layers:

@friendlyinternet/nuxt-crouton
@friendlyinternet/nuxt-crouton-i18n
@friendlyinternet/nuxt-crouton-editor
@friendlyinternet/nuxt-crouton-assets
@friendlyinternet/nuxt-crouton-supersaas

Alternatively, you can list each layer explicitly:

@source "../../../node_modules/@friendlyinternet/nuxt-crouton/app/**/*.{vue,js,ts}";
@source "../../../node_modules/@friendlyinternet/nuxt-crouton-i18n/app/**/*.{vue,js,ts}";
@source "../../../node_modules/@friendlyinternet/nuxt-crouton-editor/app/**/*.{vue,js,ts}";

Verify Installation

Check that the generator is installed correctly:

npx crouton-generate --help

You should see:

Usage: crouton-generate <layer> <collection> [options]

Pre-Generation Checklist

Before running the generator, ensure you've completed these steps:

Install the package

pnpm add @friendlyinternet/nuxt-crouton

Add to nuxt.config.ts

The generator checks that the package is both installed AND extended. Add it to your config:

extends: ['@friendlyinternet/nuxt-crouton']

Create your schema file(s)

Create JSON schema files defining your collection fields. See Schema Format.

Run the generator

npx crouton-generate <layer> <collection> --fields-file=./schema.json

Common issue: If you get a "Missing Required Dependencies" error even though the package is installed, make sure you've added it to the extends array in nuxt.config.ts.

Next Steps

Now that Nuxt Crouton is installed, continue to Usage to generate your first collection.

What is Nuxt Crouton?

Learn what Nuxt Crouton is, what it does, and how it can help you build CRUD applications faster.

Quick Start

Generate your first CRUD collection in 30 seconds.