Migrating from v3.0 to v3.1

This migration guide applies to self-hosted versions of FireCMS, including both Community and PRO editions. FireCMS v3.1 introduces important updates that require configuration changes and offers exciting new features.

TailwindCSS v4 Migration

The most significant change in v3.1 is the migration from TailwindCSS v3 to v4. This involves updating your TailwindCSS configuration and ensuring that your styles are compatible with the new version.

Update Dependencies

Update your FireCMS packages and install TailwindCSS v4:

npm i tailwindcss@4 @tailwindcss/vite

Add the Vite Plugin

Update your vite.config.ts to include the new TailwindCSS v4 plugin:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
    esbuild: {
        logOverride: { "this-is-undefined-in-esm": "silent" }
    },
    build: {
        outDir: "./build",
        target: "ESNEXT",
        sourcemap: true
    },
    optimizeDeps: { include: ["react/jsx-runtime"] },
    plugins: [
        react({}),
        tailwindcss()
    ]
})

Color Variable Changes

The CSS variable names have been updated to follow the TailwindCSS v4 standard. Update your index.css file to reflect these changes:

Before (v3.0):

:root {
    --fcms-primary: #0070F4;
    --fcms-primary-dark: #0061e6;
    --fcms-primary-bg: #0061e610;
    --fcms-secondary: #FF5B79;
}

After (v3.1):

:root {
    --color-primary: #0070F4;
    --color-secondary: #FF5B79;
}

Updated index.css Structure

Your index.css file should now look like this:

@import "tailwindcss";
@import "@firecms/ui/index.css";

@source "../index.html";
@source "./**/*.{js,ts,jsx,tsx}";
@source "../node_modules/@firecms/**/*.{js,ts,jsx,tsx}";

@custom-variant dark (:is(.dark &));

:root {
    --color-primary: #0070F4;
    --color-secondary: #FF5B79;
}

body {
    @apply w-full min-h-screen bg-gray-50 dark:bg-gray-900 flex flex-col items-center justify-center;
}

Clean Up Old Config Files

Remove the following files from your project as they are no longer needed:

• tailwind.config.js
• postcss.config.js

---

New Collection View Modes

FireCMS v3.1 introduces new ways to visualize your collection data beyond the traditional table view.

Cards View

The Cards view displays your entities as visual cards, making it easier to browse content-heavy collections such as blog posts, products, or media libraries. Each card shows a preview of the entity with its key fields.

Kanban/Board View

The Kanban view (also called Board view) allows you to organize entities into columns based on an enum property. This is perfect for:

• Workflow management (e.g., Draft → Review → Published)
• Task tracking (e.g., Todo → In Progress → Done)
• Status-based organization

To use the Kanban view, your collection needs an enum property that defines the columns. You can:

• Drag and drop entities between columns to update their status
• Reorder columns by dragging their headers
• Configure which property to use for column grouping

Both views can be enabled in your collection configuration or switched at runtime using the view toggle in the collection toolbar.

---

Bug Fixes and Improvements

FireCMS v3.1 includes numerous bug fixes and improvements:

Editor & UI

• Improved escape key behavior in editor slash command
• Enhanced suggestion menu behavior
• Small UI adjustments and visual update to dialogs
• Removed font-mono from map preview

Collection Editor

• Added inline editing for property editing
• Fixes for collection editor property saving
• Consistent behavior for editable props in collections and properties

Form Handling

• Displaying pre-save errors in table view
• Improved error focus when saving forms with errors
• Debouncing on values change in Formex
• Changed how dirty values are persisted in local storage

Local Changes

• Added enableLocalChangesBackup to collections for controlling local copy of unsaved entities
• Local changes can now be applied manually
• Clearing unsaved changes indicator when feature is not enabled

Storage & Images

• New image resizing capabilities
• Replaced internal compressing library with compressor.js
• Improved error message when Firebase Storage is not enabled

Data & Performance

• Fixed dates losing focus while typing
• Fixed select enum filters UI glitch
• Fixed full screen entity views with encoded characters in their ID
• TipTap V3 migration for improved markdown editor performance