​
Getting Started

This guide will help you set up the Back-Office development environment on your local machine.

​
Prerequisites

Before you begin, ensure you have the following installed:
ToolMinimum VersionPurpose
Node.js18.x or higherJavaScript runtime
pnpm8.x or higherPackage manager
GitLatestVersion control
Verify installations:
node --version    # Should show v18.x or higher
pnpm --version    # Should show 8.x or higher
git --version     # Any recent version

​
Installation

​
1. Clone the Repository

git clone https://github.com/your-org/cms-full.git
cd cms-full/cms-bo/bo

​
2. Install Dependencies

pnpm install
This will install all required npm packages defined in package.json.

​
3. Configure Environment

Create a .env file in the project root: 
cp .env.example .env
Development configuration (.env): 
# API Configuration
VITE_API_BASE_URL=https://local.api.cms
VITE_TENANT_ID=demo

# Use mock authentication for local development
VITE_USE_MOCK_AUTH=true

# Storage base URL (MinIO/S3)
VITE_STORAGE_BASE_URL=https://local.api.minio.cms/cms-storage

# (Optional) Keycloak for real OIDC
# VITE_KEYCLOAK_URL=https://local.api.cms/keycloak
# VITE_KEYCLOAK_REALM=cms
# VITE_KEYCLOAK_CLIENT_ID=cms-backoffice
# VITE_KEYCLOAK_REDIRECT_URI=https://local.bo.cms/auth/callback
The default configuration uses mock authentication so you can develop without running Keycloak locally.

​
4. Start Development Server

pnpm dev
The application will start at http://localhost:5173

​
Mock Authentication

With mock authentication enabled, you can log in with these test credentials:

​
Admin User

Email: admin@example.com
Password: admin123
Permissions: Full system access (all features)

​
Editor User

Email: editor@example.com
Password: editor123
Permissions: Content management only (no user or settings management)

​
Development Workflow

​
Running the Back-Office

# Start dev server with hot reload
pnpm dev

# Build for production
pnpm build

# Preview production build
pnpm preview

​
Code Quality

# TypeScript type checking
pnpm typecheck

# Linting
pnpm lint

# Run unit tests
pnpm test

# Run unit tests in watch mode
pnpm test:watch

# Run E2E tests (Playwright)
pnpm e2e

​
Connecting to the API

The Back-Office requires the Symfony API backend to be running.

​
Option 1: Use the API in Dev Mode

If the API is running via Docker (accessible at https://local.api.cms), the default configuration will work automatically.

​
Option 2: Use a Remote API

Update .env: 
VITE_API_BASE_URL=https://api-dev.example.com

​
Option 3: Use Mock API (MSW)

For isolated development, you can set up Mock Service Worker (MSW) to intercept API calls.
MSW setup is optional and not included by default. Refer to the API integration documentation for setup instructions.

​
Project Structure

src/
├── components/        # Reusable Vue components
│   ├── articles/     # Article-specific components
│   ├── pages/        # Page-specific components
│   ├── settings/     # Settings editors
│   └── system/       # System-level components
├── views/            # Route-level components (pages)
│   ├── articles/     # Article views (list, form)
│   ├── pages/        # Page views (list, form)
│   ├── auth/         # Authentication views
│   ├── dashboard/    # Dashboard view
│   └── layouts/      # Layout components
├── stores/           # Pinia state stores
│   ├── auth.ts       # Authentication state
│   ├── articles.ts   # Articles CRUD state
│   ├── pages.ts      # Pages CRUD state
│   └── ...           # Other stores
├── services/         # External services
│   ├── api/          # API service layer
│   └── auth/         # Auth service (OIDC/mock)
├── router/           # Vue Router configuration
│   └── index.ts      # Routes and guards
├── i18n/             # Internationalization
│   └── locales/      # Translation files (FR/EN/NL)
├── types/            # TypeScript type definitions
│   └── api.ts        # API types
├── utils/            # Utility functions
├── composables/      # Vue composables
├── main.ts           # Application entry point
└── App.vue           # Root component

​
Common Tasks

​
Adding a New Feature

1

Create View Component

Add a new view in src/views/[feature]/
2

Create API Service

Add API methods in src/services/api/[feature].ts
3

Create Pinia Store

Add state management in src/stores/[feature].ts
4

Define Types

Add TypeScript types in src/types/api.ts
5

Add Routes

Register routes in src/router/index.ts
6

Add Translations

Add i18n keys in src/i18n/locales/*.json
7

Update Navigation

Add menu item in PrivateLayout.vue

​
Debugging Tips

​
Vue Devtools

Install Vue Devtools browser extension for:
  • Component inspector
  • Pinia store state viewer
  • Router inspector
  • Performance profiling

​
Network Debugging

Monitor API calls in browser DevTools:
  • Check Network tab for API requests
  • Inspect request/response headers
  • View payload data

​
Console Logs

Development mode includes helpful console logs:
  • API client logs (if DEV mode)
  • Auth flow logs
  • ETag tracking

​
Troubleshooting

​
Port Already in Use

If port 5173 is busy: 
# Use a different port
pnpm dev --port 3000

​
API CORS Errors

Ensure the API backend has CORS configured for http://localhost:5173: 
# API config/packages/nelmio_cors.yaml
nelmio_cors:
    defaults:
        origin_regex: true
        allow_origin: ['^http://localhost:[0-9]+$']
        allow_methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']
        allow_headers: ['*']

​
Module Not Found Errors

Clear cache and reinstall: 
rm -rf node_modules pnpm-lock.yaml
pnpm install

​
TypeScript Errors

Run type checking: 
pnpm typecheck
Fix reported errors before committing.

​
Next Steps

Architecture

Learn about the technical architecture

Features

Explore available features

API Integration

Understand API communication patterns

State Management

Learn about Pinia stores

​
Additional Resources