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.

Before You Start

• Ensure you are currently on FireCMS v3.0.x
• Back up your project or commit your current state to version control
• Ensure you are using Node.js 18+

Update FireCMS Packages

Update all @firecms/* packages to version 3.1:

npm i @firecms/core@3.1.0 @firecms/ui@3.1.0 @firecms/firebase@3.1.0 @firecms/collection_editor@3.1.0 @firecms/collection_editor_firebase@3.1.0 @firecms/data_enhancement@3.1.0 @firecms/data_export@3.1.0 @firecms/data_import@3.1.0 @firecms/schema_inference@3.1.0 @firecms/user_management@3.1.0

Make sure to include all @firecms/* packages listed in your package.json. Mixing v3.0 and v3.1 packages will cause issues.

---

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.

Caution

This is a breaking change. Your project will not work correctly until you complete all steps in this section.

Update Dependencies

Install TailwindCSS v4 and the Vite plugin:

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;
}

If you skip this step, your custom theme colors will not be applied and FireCMS will fall back to its default palette. The --fcms-primary-dark and --fcms-primary-bg variables are no longer needed — they are computed automatically from --color-primary.

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

Verify Your Migration

After completing all steps, run:

npm run build

The build should complete without errors. If you see CSS-related warnings, double-check that your index.css matches the structure above.

---

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
• TipTap V3 migration for improved markdown editor performance

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

Note

enableLocalChangesBackup defaults to true, matching the previous behavior. Set it to false in your collection config if you want to disable local backup of unsaved changes.

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

---

AI Features for Self-Hosted (PRO)

FireCMS v3.1 brings AI-powered features to self-hosted PRO users that were previously only available in FireCMS Cloud.

AI Collection Generation

You can now use AI to generate and modify collections directly in the collection editor. The AI can create collection schemas from natural language descriptions, add or modify properties, and understand relationships with your existing collections.

Enable it by passing a generateCollection callback to the collection editor plugin:

import {
    useCollectionEditorPlugin,
    buildCollectionGenerationCallback
} from "@firecms/collection_editor";
import { useFirebaseAuthController } from "@firecms/firebase";

const authController = useFirebaseAuthController({ firebaseApp });

const collectionEditorPlugin = useCollectionEditorPlugin({
    collectionConfigController,
    collectionInference: buildCollectionInference(firebaseApp),
    getData: (path, parentPaths) => getFirestoreDataInPath(firebaseApp, path, parentPaths, 200),
    generateCollection: buildCollectionGenerationCallback({
        getAuthToken: authController.getAuthToken
    })
});

The buildCollectionGenerationCallback helper uses the default FireCMS API endpoint. You can optionally provide a custom endpoint:

generateCollection: buildCollectionGenerationCallback({
    getAuthToken: authController.getAuthToken,
    apiEndpoint: "https://your-custom-endpoint.com/collections/generate"
})

DataTalk AI Chat

DataTalk allows you to query and update your Firestore data using natural language. You can ask questions about your data, create charts and visualizations, and even modify entities through conversation.

Enable DataTalk in your self-hosted app:

import {
    useBuildDataTalkConfig,
    DataTalkProvider,
    DataTalkRoutes
} from "@firecms/datatalk";


// Configure DataTalk - only enable when user is logged in
const userEmail = authController.user?.email;
const dataTalkConfig = useBuildDataTalkConfig({
    enabled: Boolean(userEmail),
    firebaseApp,
    userSessionsPath: userEmail ? `__FIRECMS/config/users/${userEmail}/datatalk_sessions` : undefined,
    getAuthToken: authController.getAuthToken,
    loadSamplePrompts: true
    // apiEndpoint defaults to https://api.firecms.co
});

// Add DataTalk as a view in your navigation
const navigationController = useBuildNavigationController({
    collections,
    views: [
        ...yourViews,
        {
            path: "datatalk/*",
            name: "DataTalk",
            group: "AI",
            view: <DataTalkRoutes
                getAuthToken={authController.getAuthToken}
            />
        }
    ],
    // ... other config
});

// Wrap your app with the DataTalkProvider
return (
    <DataTalkProvider config={dataTalkConfig}>
        <FireCMS navigationController={navigationController} /* ... */ >
            {/* your app */}
        </FireCMS>
    </DataTalkProvider>
);

DataTalk automatically reads your collection schema from the navigation controller to understand your data structure and provide more accurate responses.

Note

AI features require a valid FireCMS PRO license. The API endpoints authenticate using your Firebase auth token.

---

Troubleshooting

Cannot find namespace 'JSX'

If you see TypeScript errors like error TS2503: Cannot find namespace 'JSX', update your return type annotations from JSX.Element to React.ReactElement or simply remove the explicit return type and let TypeScript infer it.

Styles not applying after migration

• Verify your index.css includes the @source directives for your project files and node_modules/@firecms
• Ensure you removed the old tailwind.config.js and postcss.config.js
• Clear your node_modules folder and reinstall: rm -rf node_modules && npm install

Build errors after updating packages

Ensure all @firecms/* packages are on the same version. Mixing v3.0 and v3.1 packages will cause type mismatches and runtime errors.