@devxcommerce/strapi-plugin-cm-groups

Group and collapse collection types in the Strapi 5 Content Manager navigation.

Before: every collection type listed flat and unsorted in the left nav. After: collapsible, labelled groups styled like Strapi's native grouped nav — search that filters within groups, an auto Other group for anything ungrouped, and single types marked with an S badge.

Group assignments are stored server-side (shared across all admins, durable). Each user's sidebar collapse state stays in their own browser.

Features

• Grouped, collapsible Content Manager left nav (custom GroupedLeftMenu).
• Settings board — assign content types to a group via the group's searchable "Add content types" dropdown, or drag chips between groups; remove with the × on each chip.
• Reorder groups — drag a group card by its handle to set the order groups appear in the nav.
• Unsaved-changes guard — a native confirm dialog when you navigate away with pending edits (in-app nav + tab close).
• Shared config across the team (server store) — not per-browser.
• RBAC-gated editing (plugin::cm-groups.configure).
• Theme-aware (light/dark) — design-system tokens, no hardcoded colours.
• Fails safe and visible: if the Vite helper isn't applied, the Settings page shows a clear "grouping inactive" warning with the fix; if a Strapi upgrade changes the internals it patches, grouping quietly turns off (with a build-time warning) rather than breaking the panel.

Requirements

• Strapi ^5
• Node >=20 <=24

The nav grouping is a build-time patch of Strapi admin internals (no public API exists for it). Tested against Strapi 5.x. Re-verify after Strapi minor/major upgrades: the Settings page warns if the Vite helper isn't applied, and the admin build logs a [cm-groups] warning if Strapi's internals moved.

Installation

bun add @devxcommerce/strapi-plugin-cm-groups
# or: npm install @devxcommerce/strapi-plugin-cm-groups

Setup

1. Enable the plugin

The package is auto-discovered (via its strapi.kind: 'plugin' marker), so this step is optional — add it only if you keep an explicit plugins map:

// config/plugins.ts
export default () => ({
  'cm-groups': { enabled: true },
});

This registers the server config API + RBAC permission and the Settings page.

2. Add the Vite helper

The navigation grouping is a build-time patch of Strapi's admin, so it must hook the admin Vite build — it cannot be enabled from config/plugins.ts alone:

// src/admin/vite.config.ts
import cmGroups from '@devxcommerce/strapi-plugin-cm-groups/vite';
import type { UserConfig } from 'vite';

export default (config: UserConfig) => cmGroups(config);

3. Rebuild the admin

bun run build   # or: npm run build

After installing or upgrading, always rebuild the admin (and clear .strapi/ / node_modules/.strapi/ if you've previously built) so the patched nav is regenerated.

Usage

• Manage groups: Settings → Global Settings → Content Manager Groups — add/rename groups, reorder them by dragging the handle, and assign content types via each group's Add content types dropdown (or drag a chip between groups). The × on a chip removes it from the group.
• Anything not assigned to a group falls into an automatic Other group.

Permissions

Group config is shared across all admins:

• Read (so the grouped nav renders) — any authenticated admin.
• Edit (the Settings page + the config write API) — gated by the plugin::cm-groups.configure RBAC action. Granted to Super Admin by default; assign it to other roles in Settings → Roles.

How it works

| Part | Mechanism | |------|-----------| | Content Manager sidebar | Vite/esbuild plugin replaces @strapi/content-manager's LeftMenu with the bundled GroupedLeftMenu at admin build time | | Settings page | bootstrap() registers a settings link to GroupsManager (gated on plugin::cm-groups.configure) | | Group config | Server store (strapi.store) via GET / PUT /cm-groups/config; synced on admin load into a localStorage cache (strapi-cm-groups) the nav patches read synchronously | | Collapse state | Per-user localStorage (strapi-cm-groups-collapsed) |

Storage model

The server store is the source of truth. On admin load the config is fetched and written into a small localStorage cache, because the nav patches read it synchronously at render time. Saves write the cache (instant nav refresh) and push to the server. If the server is unreachable, the local cache still applies — no crash, just no sync.

Troubleshooting

• Grouping isn't showing after install/upgrade: rebuild the admin (step 3) and clear .strapi/ + node_modules/.strapi/; hard-refresh the browser.
• It worked, then stopped after a Strapi upgrade: this plugin patches Strapi admin internals that have no public API, so a Strapi release can move them. The patch fails safe (ungrouped nav) and logs a [cm-groups] … internals may have changed WARN during the admin build — check the build output, and upgrade the plugin to a release that supports your Strapi version.
• A teammate doesn't see my groups: config is shared via the server, synced on admin load — have them reload the admin. Sidebar collapse state is intentionally per-browser.

Links

• npm
• Repository
• Issues
• Changelog

License

MIT