Frontend - Nuxt

Purpose

This page documents the Nuxt frontend layer used by Maqsafy, including project structure, routing, build process, environment configuration, API communication, and operational rules.

Frontend Responsibilities

The frontend is responsible for:

• Rendering user-facing web interfaces
• Communicating with backend APIs
• Handling client-side navigation
• Managing UI state
• Displaying validation errors
• Handling authentication state on the client side
• Presenting dashboards, forms, reports, and operational workflows

Nuxt Project Structure

Nuxt applications follow a structured directory layout. The root directory contains the Nuxt configuration file, and folders such as components, pages, and composables are used to organize the application code. Nuxt officially documents this directory-based structure as the standard way to organize a Nuxt application.

Directory / File	Purpose
nuxt.config.ts	Main Nuxt configuration file
pages/	Page-based routing
components/	Reusable Vue components
layouts/	Shared layout wrappers
composables/	Reusable composition functions
plugins/	Client or server plugins
middleware/	Route middleware
public/	Public static assets
assets/	Source assets such as styles and images

Components

Reusable UI components should be placed under the components/ directory. Nuxt automatically imports components from this directory, according to the official Nuxt documentation.

Example:

components/
├── AppHeader.vue
├── AppSidebar.vue
├── DataTable.vue
└── StatusBadge.vue

Composables

Reusable logic should be placed under the composables/ directory. Nuxt officially documents that composables in this directory can be auto-imported into the application.

Example:

composables/
├── useAuth.ts
├── useApi.ts
├── usePermissions.ts
└── usePagination.ts

API Communication

Frontend API calls must use environment-based API URLs.

Example placeholder:

NUXT_PUBLIC_API_BASE_URL=https://api.example.com

Example usage pattern:

const config = useRuntimeConfig()

const response = await $fetch('/profile', {
  baseURL: config.public.apiBaseUrl,
  headers: {
    Authorization: `Bearer <ACCESS_TOKEN>`,
  },
})

Authentication State

The frontend should manage authentication state securely.

Rules:

• Do not store sensitive tokens in insecure locations.
• Do not expose tokens in URLs.
• Do not log tokens in the browser console.
• Redirect unauthenticated users to login.
• Enforce role-based navigation visibility.
• Backend authorization remains mandatory even if frontend hides UI elements.

Route Protection

Frontend route guards or middleware may be used to protect dashboard routes.

Example placeholder:

export default defineNuxtRouteMiddleware((to, from) => {
  const user = useCurrentUser()

  if (!user.value) {
    return navigateTo('/login')
  }
})

Build and Preview

Nuxt applications can be deployed in different modes, including Node.js server deployment, static pre-rendering, serverless, or edge environments, according to the official Nuxt deployment documentation.

Common commands:

npm install
npm run build
npm run preview

Nuxt officially states that the preview command starts a server to preview the application after running the build command.

Environment Rules

• Do not commit production environment files.
• Do not expose private backend secrets in frontend variables.
• Only public-safe values should use NUXT_PUBLIC_*.
• API base URLs should be configured per environment.
• Production builds must use production-safe configuration.

Error Handling

Frontend errors should be displayed clearly without exposing internal stack traces.

Recommended format:

{
  "message": "Unable to complete the request.",
  "reference_id": "REF-EXAMPLE-001"
}

Performance Notes

• Use pagination for large lists.
• Avoid loading heavy reports directly in the browser.
• Use server-side filtering where applicable.
• Optimize images and static assets.
• Avoid exposing large datasets to unauthorized users.

Security Rules

• Do not expose access tokens in logs.
• Do not expose private API keys in frontend code.
• Do not rely on frontend-only authorization.
• Validate permissions again on the backend.
• Do not include real user data in examples.
• Use placeholders for domains, tokens, and credentials.