---
metaTitle: Getting Started | AwesCode UI
meta:
  - name: description
    content: Quick start guide for AwesCode UI component library - installation, setup, and basic usage.
title: Getting Started
---

# Getting Started

Get up and running with AwesCode UI component library in minutes.

## Framework Overview

The AwesCode UI framework consists of 4 integrated packages:

1. **@awes-io/ui** - UI component library (this package)
2. **@awes-io/nuxt-laravel** - Laravel backend integration
3. **@awes-io/nuxt-auth** - Authentication with JWT and 2FA
4. **vue-mc** - Model and collection layer for API data

For complete integration guide, see [Framework Integration](./integrations.md).

## Installation

Install the packages via npm or yarn:

```bash
# UI components (required)
npm install @awes-io/ui

# Laravel integration (recommended)
npm install @awes-io/nuxt-laravel

# Authentication (recommended)
npm install @awes-io/nuxt-auth

# or install all at once
npm install @awes-io/ui @awes-io/nuxt-laravel @awes-io/nuxt-auth
```

## Setup

### Nuxt.js Setup

Add the modules to your `nuxt.config.js`:

```javascript
export default {
  modules: [
    '@awes-io/nuxt-laravel',  // 1. Laravel integration
    '@awes-io/nuxt-auth',     // 2. Authentication
    '@awes-io/ui'             // 3. UI components
  ],

  // Required: Enable components auto-import
  components: true,

  // Required: Enable Vuex store
  store: true,

  // Environment variables
  env: {
    LARAVEL_URL: process.env.LARAVEL_URL || 'http://localhost:8000'
  }
}
```

### Configuration

The framework supports two types of configuration:

1. **Static Configuration** (`awes.config.js`) - For logos, colors, fonts, and i18n settings
2. **Dynamic Component Configuration** (Plugin) - For component defaults that may change at runtime

#### Quick Setup

Create `awes.config.js` in your project root:

```javascript
export default {
  logo: {
    src: '/logo.svg',
    alt: 'My App'
  }
}

export const dark = {
  logo: {
    src: '/logo-dark.svg'
  }
}

// Optional: Configure i18n if you need to customize language settings
// Defaults are: locale: 'en', locales: ['en']
export const lang = {
  locales: ['en', 'es', 'fr'],
  locale: 'en'
}
```

Create `plugins/components.js` for dynamic component configuration:

```javascript
import Vue from 'vue'
import { CONFIG_VAR } from '@AwUtils/component'

export default async ({ app }) => {
  Vue.prototype[CONFIG_VAR] = Vue.prototype[CONFIG_VAR] || {}

  // Configure component defaults
  Vue.prototype[CONFIG_VAR].AwButton = {
    size: 'md',
    color: 'accent',
    theme: 'solid'
  }
}
```

Register the plugin in `nuxt.config.js`:

```javascript
export default {
  plugins: ['~/plugins/components.js']
}
```

For complete configuration options, see the [Configuration Guide](./configuration.md).

## Component System

Components are organized into 5 categories following atomic design:

### 1. Atoms (Global)

Basic building blocks automatically available everywhere:

```markup
<template>
  <div>
    <AwButton>Click me</AwButton>
    <AwInput v-model="name" label="Name" />
    <AwCheckbox v-model="agreed">I agree</AwCheckbox>
  </div>
</template>
```

### 2. Molecules (Global)

Combinations of atoms, mostly global:

```markup
<template>
  <div>
    <AwSelect v-model="country" :options="countries" label="Country" />
    <AwTextarea v-model="bio" label="Bio" rows="4" />
    <AwAlert>This is an alert message</AwAlert>
  </div>
</template>
```

### 3. Organisms (Dynamic)

Complex components, dynamically imported:

```markup
<template>
  <div>
    <AwForm url="/api/submit" @sended="onSuccess">
      <AwInput name="title" label="Title" />
      <AwButton type="submit">Submit</AwButton>
    </AwForm>

    <AwModal :show="showModal" @close="showModal = false">
      <template #title>Modal Title</template>
      <p>Modal content</p>
    </AwModal>

    <AwTable :data="items" :columns="columns" />
  </div>
</template>
```

### 4. Pages (Dynamic)

Top-level page components:

```markup
<template>
  <AwPage title="My Page">
    <AwCard>
      <p>Page content</p>
    </AwCard>
  </AwPage>
</template>
```

### 5. Layouts (Dynamic)

Root-level layout components:

```markup
<template>
  <AwLayout>
    <AwPage title="Dashboard">
      <!-- content -->
    </AwPage>
  </AwLayout>
</template>
```

## Your First Page

### 1. Create a Menu Plugin

Create `plugins/menu.js` to configure navigation menus:

```javascript
export default function({ store }) {
  store.commit('awesIo/SET_MENU_ITEMS', {
    main: [
      { text: 'Dashboard', href: '/', icon: 'dashboard' },
      { text: 'Users', href: '/users', icon: 'users' },
      { text: 'Settings', href: '/settings', icon: 'settings' }
    ],
    user: [
      { text: 'Profile', href: '/profile', icon: 'user' },
      { text: 'Settings', href: '/settings', icon: 'cogs' },
      { text: 'Logout', href: '/logout', icon: 'logout' }
    ]
  })
}
```

Register the plugin in `nuxt.config.js`:

```javascript
export default {
  plugins: [
    '~/plugins/menu.js'
  ]
}
```

### 2. Create a Layout

```markup
<!-- layouts/default.vue -->
<template>
  <AwLayout>
    <nuxt />
  </AwLayout>
</template>
```

### 3. Create a Page

```markup
<!-- pages/index.vue -->
<template>
  <AwPage title="Dashboard">
    <template #buttons>
      <AwButton href="/create" icon="plus">
        Create New
      </AwButton>
    </template>

    <AwGrid :cols="{ default: 1, md: 2, lg: 3 }" :gap="4">
      <AwCard title="Total Users">
        <div class="text-4xl font-bold">1,234</div>
        <AwDescription>Active users</AwDescription>
      </AwCard>

      <AwCard title="Revenue">
        <div class="text-4xl font-bold">$45,678</div>
        <AwDescription>This month</AwDescription>
      </AwCard>

      <AwCard title="Growth">
        <div class="text-4xl font-bold">+23%</div>
        <AwDescription>Compared to last month</AwDescription>
      </AwCard>
    </AwGrid>
  </AwPage>
</template>
```

### 4. Create a Form Page

```markup
<!-- pages/users/create.vue -->
<template>
  <AwPage title="Create User">
    <AwCard>
      <AwForm url="/api/users" method="post" @sended="onUserCreated">
        <AwGrid :cols="2" :gap="4">
          <AwInput name="first_name" label="First Name" required />
          <AwInput name="last_name" label="Last Name" required />
        </AwGrid>

        <AwInput name="email" label="Email" type="email" required />

        <AwSelect
          name="role"
          label="Role"
          :options="['Admin', 'Editor', 'User']"
          required
        />

        <AwPassword name="password" label="Password" required minlength="8" />

        <AwFlow justify="end" :gap="2">
          <AwButton href="/users" color="mono">Cancel</AwButton>
          <AwButton type="submit">Create User</AwButton>
        </AwFlow>
      </AwForm>
    </AwCard>
  </AwPage>
</template>

<script>
export default {
  methods: {
    onUserCreated(response) {
      this.$notify({ title: 'User created successfully!' })
      this.$router.push('/users')
    }
  }
}
</script>
```

## Common Patterns

### Using Forms

```markup
<AwForm url="/api/endpoint" method="post" @sended="onSuccess" @error="onError">
  <AwInput name="field" label="Label" required />
  <AwButton type="submit">Submit</AwButton>
</AwForm>
```

### Data Tables

```markup
<AwTableBuilder
  url="/api/users"
  :columns="[
    { name: 'name', label: 'Name', sortable: true },
    { name: 'email', label: 'Email', sortable: true },
    { name: 'role', label: 'Role' }
  ]"
/>
```

### Modals

```markup
<template>
  <div>
    <AwButton @click="showModal = true">Open Modal</AwButton>

    <AwModal :show="showModal" @close="showModal = false">
      <template #title>Modal Title</template>
      <p>Modal content</p>
      <template #buttons>
        <AwButton @click="showModal = false">Close</AwButton>
      </template>
    </AwModal>
  </div>
</template>
```

### Notifications

```markup
<script>
export default {
  methods: {
    showNotification() {
      this.$notify({
        message: 'Operation completed successfully!',
        type: 'success'
      })
    }
  }
}
</script>
```

## Navigation Setup

Set up your app navigation using a menu plugin (`plugins/menu.js`):

```javascript
export default function({ store }) {
  // Main navigation menu
  store.commit('awesIo/SET_MENU_ITEMS', {
    main: [
      {
        text: 'Dashboard',
        href: '/',
        icon: 'dashboard'
      },
      {
        text: 'Users',
        icon: 'users',
        key: 'users',
        href: '/users',
        children: [
          { text: 'All Users', href: '/users' },
          { text: 'Add User', href: '/users/create' },
          { text: 'Roles', href: '/roles' }
        ]
      },
      {
        text: 'Products',
        href: '/products',
        icon: 'box',
        badge: 5
      }
    ],
    user: [
      { text: 'Profile', href: '/profile', icon: 'user' },
      { text: 'Settings', href: '/settings', icon: 'settings' },
      { text: 'Logout', href: '/logout', icon: 'logout' }
    ]
  })
}
```

Register the plugin in `nuxt.config.js`:

```javascript
export default {
  plugins: [
    '~/plugins/menu.js'
  ]
}
```

**For sections with submenu items:** See [Mobile Subnavigation Pattern](./guides/mobile-subnavigation.md) to create mobile navigation hubs that automatically redirect desktop users to content pages.

## Theming & Styling

### Dark Theme

The library includes automatic dark theme support:

```javascript
// Toggle dark theme
this.$store.dispatch('awesIo/toggleTheme')

// Check current theme
const isDark = this.$store.getters['awesIo/isDarkTheme']
```

### Custom CSS

Override component styles in your CSS:

```css
/* Override button colors */
.aw-button--accent {
  --btn-bg: #your-color;
  --btn-text: #fff;
}

/* Customize input styles */
.aw-text-field {
  --input-border: #your-border-color;
  --input-focus: #your-focus-color;
}
```

## Responsive Design

All components are mobile-first and responsive:

```markup
<!-- Responsive grid -->
<AwGrid
  :cols="{ default: 1, sm: 2, md: 3, lg: 4 }"
  :gap="{ default: 2, md: 4 }"
>
  <!-- content -->
</AwGrid>

<!-- Responsive visibility -->
<div v-if="$screen.lg">Desktop only</div>
<div v-if="!$screen.lg">Mobile only</div>
```

## Plugins & Utilities

The library provides several utilities:

### Screen Breakpoints

```javascript
// Access screen size
if (this.$screen.lg) {
  // Desktop view
}

// Available breakpoints: xs, sm, md, lg, xl
```

### Router Extensions

```javascript
// Enhanced router methods
this.$router.pushBack('/fallback-url')
this.$router.setBack('/previous-page')
```

### Notifications

```javascript
// Show notification
this.$notify({
  message: 'Success!',
  type: 'success' // success, error, warning, info
})
```

### Config Access

```javascript
// Access config
const logoSrc = this.$awes._config.logo.src
```

## Next Steps

### Essential Guides

- **[Configuration Guide](./configuration.md)** - Complete configuration reference
- **[Framework Integration](./integrations.md)** - Complete setup with all packages
- **[List Pages](./guides/page-patterns/list-pages.md)** - Build list pages with tables
- **[Detail Pages](./guides/page-patterns/detail-pages.md)** - Create/edit forms
- **[Mobile Subnavigation](./guides/mobile-subnavigation.md)** - Mobile navigation hubs with submenus
- **[Best Practices](./guides/best-practices.md)** - Framework patterns and conventions

### Component Documentation

- **[Component Index](./index.md)** - Browse all available components
- **[Forms Guide](./guides/forms-guide.md)** - Form patterns and validation
- **[Component Cookbook](./cookbook/)** - Real-world examples

### Package Documentation

- **[Vue-MC Models & Collections](../../vue-mc/docs/)** - Data layer documentation
- **[Nuxt-Auth](../../nuxt-auth/docs/)** - Authentication setup
- **[Nuxt-Laravel](../../nuxt-laravel/docs/)** - Laravel integration

### Learning Path

**Beginner** (getting started):
1. Read [Framework Integration](./integrations.md)
2. Follow [List Pages Guide](./guides/page-patterns/list-pages.md)
3. Follow [Detail Pages Guide](./guides/page-patterns/detail-pages.md)

**Intermediate** (building features):
1. Study [Best Practices](./guides/best-practices.md)
2. Learn [Data Fetching Patterns](./guides/data-fetching.md)
3. Implement [Error Handling](./guides/error-handling.md)

**Advanced** (complex features):
1. Explore [Common Patterns](./cookbook/common-patterns.md)
2. Study [Advanced Patterns](./cookbook/advanced-patterns.md)
3. Review [Troubleshooting Guide](./reference/troubleshooting.md)

## Common Issues

### Components Not Found

Make sure you have:
1. Added `@awes-io/ui` to `modules` in `nuxt.config.js`
2. Enabled `components: true`
3. Enabled `store: true` for Vuex

### Styles Not Loading

Ensure your Nuxt config includes the module before other modules that might interfere with CSS loading.

### Icons Not Showing

The library uses custom icon sets. Make sure your `awes.config.js` is properly configured and icon assets are available.

## Support

- **Issues**: [GitHub Issues](https://github.com/awes-io/ui/issues)
- **Discussions**: [GitHub Discussions](https://github.com/awes-io/ui/discussions)
- **Documentation**: [Component Docs](index.md)