How to Configure Sidebar and Header Settings in Celeris Web

Sidebar and header settings in Celeris Web are configured through the centralized ProjectSetting configuration object, which defines default layouts in apps/admin/src/setting/projectSetting.ts and exposes reactive state management through Pinia store getters and dedicated Vue composables (useHeaderSetting and useMenuSetting).

Customizing the admin dashboard layout in the kirklin/celeris-web repository relies on a type-safe configuration system that controls the visibility and behavior of the global header and sidebar navigation. These settings are initialized with sensible defaults in TypeScript, managed reactively through the application's Pinia store in apps/admin/src/store/modules/app.ts, and consumed by Vue components to programmatically toggle UI elements or persist user preferences across sessions.

Configuration Architecture and Type Definitions

Celeris Web centralizes UI layout preferences within the ProjectSetting interface, which aggregates both header and menu (sidebar) configurations into a single project-wide object.

Default Project Settings

The default values for all layout configurations reside in apps/admin/src/setting/projectSetting.ts. This file exports DEFAULT_PROJECT_SETTING, which populates the Pinia store on initialization. Changing these defaults affects the initial state of every new session before any user overrides are applied.

Type Definitions

The TypeScript interfaces defining the shape of these settings are located in packages/web/types/src/config.ts. This file declares HeaderSetting and MenuSetting, ensuring type safety across the monorepo. The HeaderSetting interface controls the top navigation bar's visibility and features, while MenuSetting manages the left-hand sidebar navigation state.

Configuring Header Settings

Header configuration is governed by the HeaderSetting interface, which provides granular control over individual header elements. In apps/admin/src/setting/projectSetting.ts, the default headerSetting object initializes the following properties:

• shouldShow: Boolean flag to show or hide the entire top header bar (default: true)
• shouldShowFullScreen: Displays the full-screen toggle button (default: true)
• shouldShowSearch: Shows the global search input in the header (default: true)
• shouldShowNotice: Displays the notification bell icon (default: true)
• shouldShowSettingDrawer: Controls visibility of the settings drawer toggle button (default: false)

To modify header settings programmatically, import the useHeaderSetting composable from apps/admin/src/composables/setting/useHeaderSetting.ts:

import { useHeaderSetting } from "~/composables/setting/useHeaderSetting";

const { 
  getShouldShowHeader, 
  setHeaderSetting,
  toggleShouldShowSettingDrawer 
} = useHeaderSetting();

// Hide the header entirely
setHeaderSetting({ shouldShow: false });

// Toggle the settings drawer button
toggleShouldShowSettingDrawer();

The setHeaderSetting method accepts a Partial<HeaderSetting> object, merging updates with existing state rather than replacing the entire configuration.

Configuring Sidebar (Menu) Settings

Sidebar behavior is managed through the MenuSetting interface, which primarily controls the collapsed state of the left-hand navigation. The key property is collapsed, a boolean defaulting to false in DEFAULT_PROJECT_SETTING.

The useMenuSetting composable in apps/admin/src/composables/setting/useMenuSetting.ts provides the primary API for sidebar manipulation:

import { useMenuSetting } from "~/composables/setting/useMenuSetting";

const { getCollapsed, setCollapsed, toggleCollapsed } = useMenuSetting();

// Programmatically collapse the sidebar
setCollapsed(true);

// Toggle current state
toggleCollapsed();

// React to state changes
watchEffect(() => {
  console.log('Sidebar collapsed:', getCollapsed.value);
});

The sidebar layout component at apps/admin/src/layouts/sidebar/index.vue consumes these reactive getters to apply CSS transitions and layout adjustments when the collapsed state changes.

State Management with Pinia

The apps/admin/src/store/modules/app.ts file defines the central Pinia store that holds the ProjectSetting state. The store exposes specific getters and actions for header and menu settings:

• getHeaderSetting: Returns the current HeaderSetting object
• getMenuSetting: Returns the current MenuSetting object
• setHeaderSetting(headerSetting: Partial<HeaderSetting>): Merges partial updates into the header configuration
• setMenuSetting(menuSetting: Partial<MenuSetting>): Merges partial updates into the menu configuration

Direct store access is available through useAppStore(), though the composables provide a more convenient abstraction for components.

Persisting Settings Across Sessions

By default, Celeris Web persists ProjectSetting changes to local storage using the PermissionCacheTypeConstants.LOCAL_STORAGE cache type configured in DEFAULT_PROJECT_SETTING. When you invoke setHeaderSetting or setMenuSetting, the Pinia store automatically serializes the updated state to local storage. On application initialization, the store hydrates itself from this cached data, ensuring user preferences survive page reloads without requiring additional boilerplate code.

Key Source Files Reference

Purpose	File Path	Description
Default Configuration	apps/admin/src/setting/projectSetting.ts	Exports DEFAULT_PROJECT_SETTING with initial header and menu values
Type Definitions	packages/web/types/src/config.ts	Contains HeaderSetting and MenuSetting TypeScript interfaces
Pinia Store	apps/admin/src/store/modules/app.ts	Central state management for project settings
Header Composable	apps/admin/src/composables/setting/useHeaderSetting.ts	Vue composable exposing header getters and mutations
Menu Composable	apps/admin/src/composables/setting/useMenuSetting.ts	Vue composable for sidebar collapsed state management
Header Layout	apps/admin/src/layouts/header/index.vue	Component rendering the top navigation bar
Sidebar Layout	apps/admin/src/layouts/sidebar/index.vue	Component rendering the left navigation menu

Summary

• ProjectSetting acts as the single source of truth for both header and sidebar configurations in Celeris Web.
• Default values are defined in apps/admin/src/setting/projectSetting.ts and typed in packages/web/types/src/config.ts.
• The Pinia store (apps/admin/src/store/modules/app.ts) manages reactive state through dedicated getters and mutation actions.
• Composables (useHeaderSetting and useMenuSetting) provide the recommended developer API for reading and modifying layout state within Vue components.
• Changes persist automatically to local storage via the configured cache mechanism.

Frequently Asked Questions

Where are the default sidebar and header settings defined in Celeris Web?

Default settings are defined in apps/admin/src/setting/projectSetting.ts within the DEFAULT_PROJECT_SETTING object. The header defaults are nested under the headerSetting property, while sidebar defaults live under menuSetting. Type definitions for these objects are located in packages/web/types/src/config.ts.

How do I programmatically collapse the sidebar in Celeris Web?

Import the useMenuSetting composable from ~/composables/setting/useMenuSetting and call either setCollapsed(true) to explicitly collapse it or toggleCollapsed() to switch between states. The composable returns reactive getters that automatically update the UI when the state changes.

Can I hide specific elements like the search box or fullscreen button in the header?

Yes. Use the useHeaderSetting composable and call setHeaderSetting() with the specific boolean flags you want to modify, such as { shouldShowSearch: false } or { shouldShowFullScreen: false }. Each property controls a distinct UI element independently.

Are sidebar and header settings persisted automatically between page reloads?

Yes. Celeris Web automatically persists ProjectSetting mutations to local storage when configured with PermissionCacheTypeConstants.LOCAL_STORAGE. The Pinia store hydrates from this cache on application startup, maintaining user preferences across sessions without requiring manual local storage handling.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}