Quick Start Guide

December 3, 2025 · View on GitHub

Get up and running with Vue Material Admin in minutes!

Prerequisites

  • Node.js: 18.x or higher
  • Package Manager: Yarn (recommended) or npm
  • IDE: VS Code with Volar extension (recommended)

Installation

1. Clone the Repository

git clone https://github.com/tookit/vue-material-admin.git
cd vue-material-admin

2. Install Dependencies

# Using Yarn (recommended)
yarn install

# Or using npm
npm install

3. Start Development Server

yarn dev

The application will be available at http://localhost:9527

Project Structure

vue-material-admin/
├── src/
│   ├── api/              # API services
│   ├── components/       # Reusable components
│   ├── composables/      # Vue composables (NEW!)
│   ├── layouts/          # Layout components
│   ├── plugins/          # Plugin configurations
│   ├── router/           # Vue Router
│   ├── store/            # Pinia stores
│   ├── views/            # Page components
│   └── main.ts           # Entry point
├── public/               # Static assets
└── docs/                 # Documentation

Key Features

🎨 Vuetify 3.11

Latest Material Design components with full TypeScript support.

<template>
  <VBtn color="primary">Click Me</VBtn>
  <VCard>
    <VCardTitle>Card Title</VCardTitle>
    <VCardText>Card content</VCardText>
  </VCard>
</template>

🔧 Composables

Reusable logic with Vue Composition API.

import { useApi, useFormValidation } from '@/composables';

// API calls with loading states
const { data, loading, execute } = useGet('/api/users');

// Form validation
const { rules } = useFormValidation();

🎯 TypeScript

Full type safety throughout the project.

interface User {
  id: number;
  name: string;
  email: string;
}

const users = ref<User[]>([]);

🌍 Internationalization

Multi-language support with Vue I18n.

import { useI18n } from 'vue-i18n';

const { t } = useI18n();
const greeting = t('hello');

Common Tasks

Creating a New Page

  1. Create component in src/views/:
<!-- src/views/MyPage.vue -->
<script setup lang="ts">
import { ref } from 'vue';

const message = ref('Hello World');
</script>

<template>
  <VContainer>
    <h1>{{ message }}</h1>
  </VContainer>
</template>
  1. Add route in src/router/:
{
  path: '/my-page',
  name: 'MyPage',
  component: () => import('@/views/MyPage.vue')
}

Making API Calls

import { useGet, usePost } from '@/composables';

// GET request
const { data: users, loading } = useGet('/api/users', {
  immediate: true
});

// POST request
const { execute: createUser } = usePost('/api/users');

const handleSubmit = async (userData) => {
  await createUser({ data: userData });
};

Form Validation

<script setup lang="ts">
import { ref } from 'vue';
import { useFormValidation } from '@/composables';

const { rules } = useFormValidation();
const email = ref('');
const password = ref('');
</script>

<template>
  <VForm>
    <VTextField
      v-model="email"
      label="Email"
      :rules="[rules.required(), rules.email()]"
    />
    <VTextField
      v-model="password"
      label="Password"
      type="password"
      :rules="[rules.required(), rules.minLength(8)]"
    />
  </VForm>
</template>

State Management with Pinia

// stores/user.ts
import { defineStore } from 'pinia';

export const useUserStore = defineStore('user', {
  state: () => ({
    user: null,
    isAuthenticated: false
  }),
  actions: {
    setUser(user) {
      this.user = user;
      this.isAuthenticated = true;
    }
  }
});

// In component
import { useUserStore } from '@/store/user';

const userStore = useUserStore();
userStore.setUser({ name: 'John' });

Customizing Theme

Edit src/plugins/vuetify/constants.ts:

export const PRIMARY_COLOR = '#304FFD'; // Change this!

export const LIGHT_THEME_COLORS = {
  primary: PRIMARY_COLOR,
  secondary: '#FF965D', // Or this!
  // ...
};

Available Scripts

# Development server with hot-reload
yarn dev

# Type-check and build for production
yarn build

# Preview production build
yarn preview

# Run TypeScript type checking
yarn typecheck

# Lint and fix files
yarn lint

IDE Setup

Install these extensions:

  1. Volar - Vue 3 language support
  2. TypeScript Vue Plugin - TypeScript support for Vue
  3. ESLint - Code linting
  4. Prettier - Code formatting

Settings

Add to .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }
}

Troubleshooting

Port Already in Use

Change port in vite.config.ts:

server: {
  port: 3000 // Change from 9527
}

Module Not Found

Clear cache and reinstall:

rm -rf node_modules yarn.lock
yarn install

TypeScript Errors

Run type checking:

yarn typecheck

Build Errors

Clear dist and rebuild:

rm -rf dist
yarn build

Learning Resources

Next Steps

  1. ✅ Explore the demo pages
  2. ✅ Read the Composables Reference
  3. ✅ Check out the Migration Guide
  4. ✅ Customize the theme colors
  5. ✅ Build your first page!

Getting Help

Happy coding! 🚀