@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 — each with a count badge, 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.

License

MIT

JSPM