Base Stack Admin Frontend Template

Nuxt 4 admin dashboard template with TypeScript, Nuxt UI 4, and Pinia for building modern admin applications.

Prerequisites

Before starting, ensure you have the following installed:

Required

• Node.js 18+ - Install Node.js
• Bun (recommended) - Fast JavaScript runtime and package manager

Install Bun

macOS/Linux:

curl -fsSL https://bun.sh/install | bash

Windows:

powershell -c "irm bun.sh/install.ps1 | iex"

Verify Installation:

bun --version

Add to PATH (if needed):

# Add to your shell profile (.bashrc, .zshrc, etc.)
export PATH="$HOME/.bun/bin:$PATH"

# Reload shell
source ~/.zshrc  # or ~/.bashrc

Setup

Install dependencies using Bun (recommended):

bun install

Alternative package managers:

# npm
npm install

# pnpm
pnpm install

# yarn
yarn install

Configuration

Environment Variables

Create a .env file in the project root:

# API Configuration
NUXT_PUBLIC_API_BASE_URL=http://localhost:8000/api
NUXT_PUBLIC_API_KEY=api

• NUXT_PUBLIC_API_BASE_URL - Backend API URL
• NUXT_PUBLIC_API_KEY - API key header value

Backend Connection

The frontend expects a Base Stack backend running on http://localhost:8000/api by default.

Development mode automatically proxies /api requests to the backend server (configured in nuxt.config.ts).

Development Server

Start the development server on http://localhost:3030:

# Bun (recommended)
bun dev

# npm
npm run dev

# pnpm
pnpm dev

# yarn
yarn dev

Note: The default development port is 3030, not 3000, to avoid conflicts with other applications.

Production

Build

Build the application for production:

# Bun (recommended)
bun build

# npm
npm run build

# pnpm
pnpm build

# yarn
yarn build

Preview

Locally preview production build:

# Bun (recommended)
bun preview

# npm
npm run preview

# pnpm
pnpm preview

# yarn
yarn preview

Deployment

The application is built as a SPA (Single Page Application) by default (ssr: false in nuxt.config.ts).

Static assets are generated in .output/public/ and can be deployed to any static hosting service:

• Netlify
• Vercel
• AWS S3 + CloudFront
• Nginx/Apache

Production Environment:

NUXT_PUBLIC_API_BASE_URL=https://api.yourdomain.com/api
NUXT_PUBLIC_API_KEY=your-production-api-key

Project Structure

admin-template/
├── app/
│   ├── components/        # Vue components
│   ├── composables/       # Composition functions
│   ├── layouts/          # Nuxt layouts
│   ├── middleware/       # Route middleware
│   ├── modules/          # Feature modules (generated by Bui)
│   ├── pages/            # Nuxt pages (routes)
│   ├── stores/           # Pinia stores
│   ├── types/            # TypeScript interfaces
│   └── utils/            # Utility functions
├── public/               # Static assets
├── .env                  # Environment variables
├── nuxt.config.ts        # Nuxt configuration
├── tailwind.config.ts    # Tailwind CSS configuration
└── tsconfig.json         # TypeScript configuration

Features

• Nuxt 4 - Latest Nuxt framework
• TypeScript - Full type safety
• Nuxt UI 4 - Pre-built UI components
• Pinia - State management
• Tailwind CSS - Utility-first CSS
• Vue Router - File-based routing
• Authentication - JWT-based auth with API keys
• Dark Mode - Built-in theme support
• Internationalization - Multi-language support

Development Tips

Linting

Lint TypeScript and Vue files:

bun lint

Type Checking

The project uses TypeScript with strict mode. Type errors are shown during development.

Store Pattern

Always use Pinia stores for API calls, never make direct API calls from components:

// ✅ Correct - Use store
const productsStore = useProductsStore()
await productsStore.fetchProducts()

// ❌ Wrong - Direct API call
const response = await fetch('/api/products')

Generated Modules

Modules generated by Bui CLI follow a consistent pattern:

• Types: app/modules/[module]/types/[module].ts
• Store: app/modules/[module]/stores/[module]s.ts
• Components: app/modules/[module]/components/
• Pages: app/pages/app/[module]s/

Navigation Grouping

The sidebar navigation supports organizing menu items into groups. You can add a group property to your module configuration:

// app/modules/customers/module.config.ts
export default {
  name: 'customers',
  displayName: 'Customers',
  icon: 'i-lucide-users',
  navigation: {
    label: 'Customers',
    icon: 'i-lucide-users',
    to: '/app/customers',
    permission: 'customer:list',
    order: 10,
    group: 'customers'  // Optional: group name for sidebar organization
  }
}

Group Behavior:

• main - Default group (appears at the top, contains Dashboard)
• system - System group (appears at the bottom, contains Settings, Employees, Media)
• Custom groups - Any other group name (appears in the middle, sorted alphabetically)

Without group property: Items default to the main group.

Example navigation structure:

┌─ Main Group ─────────┐
│ Dashboard            │
│ Products             │
│ Orders               │
├─ Customers Group ───┤
│ Customers            │
│ Invoices             │
├─ System Group ──────┤
│ Media                │
│ Employees            │
│ Settings             │
└──────────────────────┘

Check out the deployment documentation for more information.