@devxcommerce/strapi-plugin-cm-groups

Group and collapse collection types in the Strapi 5 Content Manager and Content Type Builder 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).
Matching grouping in the Content Type Builder nav.
Drag-and-drop board on the Settings page — drag content types between groups and the Unassigned tray. Also assignable from CTB → Edit → Advanced Settings.
Reorder groups — drag a group card by its handle to set the order groups appear in the nav.
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, the Settings page, and the CTB group selector.

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 groups, rename them, and drag content types from the Unassigned tray into a group (or between groups / back out). The × on a chip sends it back to Unassigned.
Assign from the builder: open any collection or single type → Edit → Advanced Settings → pick a group from the Group dropdown. The nav updates immediately.
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
Content Type Builder sidebar	Vite/esbuild plugin patches `useContentTypeBuilderMenu` to group collection types by the same config
CTB Advanced Settings	`bootstrap()` extends the CTB forms API with a `select-ct-group` custom input
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