Vuestic UI Framework

Common errors

• Error: Vuestic cache plugin is not registered!

  cause The Vuestic UI plugin was not correctly installed or initialized in the application's entry file, or a build cache issue exists.
  fix Ensure `app.use(createVuestic())` is in `main.ts` (or `main.js`). Clear `node_modules/.vite/deps/` (for Vite) or `node_modules/.nuxt/` (for Nuxt) and `npm install` again.

• Component styles are not applying or conflict with existing CSS.

  cause Incorrect CSS import path, especially when mixing Vuestic UI with other frameworks like Tailwind, or general CSS specificity issues.
  fix For Tailwind projects, import `vuestic-ui/styles/essential.css` and `vuestic-ui/styles/typography.css` instead of `vuestic-ui/css`. For other conflicts, inspect generated CSS using developer tools and override specific Vuestic CSS variables (prefixed with `--va-`) for targeted adjustments.

• Cannot access 'composableName' before initialization (e.g., 'Cannot access 'useColors' before initialization')

  cause A Vuestic UI composable (e.g., `useColors`, `useModal`) is being called outside of a Vue component's `setup` function or a valid lifecycle hook, leading to an invalid reactive context.
  fix Ensure Vuestic UI composables are called within the `setup` block of a Vue component (or `<script setup>`) or a function invoked by a lifecycle hook. They rely on Vue's component instance context to function correctly.

Warnings

• gotcha The 'Vuestic cache plugin is not registered!' error often occurs due to incorrect Vuestic UI plugin installation, particularly when using a custom build setup or after package updates. It can also stem from import issues where the plugin isn't properly initialized before components are used.
  Fix: Ensure `app.use(createVuestic())` is called in your main application entry file (e.g., `main.ts` or `main.js`). After updating, clear your build cache (e.g., `node_modules/.vite/deps/` for Vite or `node_modules/.nuxt/` for Nuxt) and reinstall dependencies.
• gotcha When integrating with Tailwind CSS, importing the default `vuestic-ui/css` can lead to style conflicts because Vuestic's reset styles might clash with Tailwind's.
  Fix: Instead of `import 'vuestic-ui/css';`, use specific style imports: `import 'vuestic-ui/styles/essential.css';` and `import 'vuestic-ui/styles/typography.css';`. This ensures only the necessary Vuestic styles are included, allowing Tailwind to manage the base resets.
• deprecated The Web Components build feature in Vuestic UI is currently in 'test mode'. This means its API might change in future releases, and unexpected bugs could occur. Production use should be approached with caution.
  Fix: If using Vuestic UI as Web Components, regularly check the official documentation for updates to the `registerVuesticWebComponents` API. Consider alternative integration methods for critical applications until the feature stabilizes.
• gotcha Globally overriding component props or styles via `createVuestic` can have unintended, widespread effects across your application. While powerful for consistent theming, it can make debugging specific component behavior challenging if not carefully managed.
  Fix: Use global configuration for broad theme and default prop settings. For more localized adjustments, utilize the `VaConfig` component or directly pass props to individual components, as these have higher priority and offer scoped control.

Install

• npm install vuestic-ui npm
• yarn add vuestic-ui yarn
• pnpm add vuestic-ui pnpm

Imports

• createVuestic
  wrong:

  import VuesticUI from 'vuestic-ui'; // VuesticUI is not a default export
  app.use(VuesticUI);

  correct:

  import { createApp } from 'vue';
  import { createVuestic } from 'vuestic-ui';
  import 'vuestic-ui/css';
  
  const app = createApp(App);
  app.use(createVuestic({ /* global config */ }));

  The `createVuestic` function is the factory for the Vuestic UI plugin, used to globally register components, directives, and configure the framework. Always import the main CSS file separately.
• VaButton

  import { VaButton } from 'vuestic-ui';

  Individual components are named exports. For tree-shaking, it's recommended to import components directly rather than relying solely on global registration via `createVuestic` if fine-grained control is needed.
• useColors
  wrong:

  import { useColors } from 'vuestic-ui/dist/composables/useColors'; // Correct path, but direct import is cleaner

  correct:

  import { useColors } from 'vuestic-ui';
  
  const { getColor, getTextColor } = useColors();

  Composables like `useColors` are also named exports directly from the main package and provide reactive utilities. Ensure they are called within Vue's `setup` context or a component lifecycle hook.

Quickstart

Demonstrates how to install Vuestic UI, register it as a Vue plugin with global configuration, and use a basic component like `VaButton` in a Vue 3 application.

import { createApp } from 'vue';
import App from './App.vue';
import { createVuestic, VaButton } from 'vuestic-ui';
import 'vuestic-ui/css';

const app = createApp(App);

// Install Vuestic UI plugin with optional global configuration
app.use(createVuestic({
  colors: {
    // Define custom color palette
    primary: '#4ae387',
    success: '#40e583',
    danger: '#e34a4a'
  },
  components: {
    VaButton: {
      // Globally configure VaButton props
      size: 'medium',
      preset: 'primary'
    }
  }
}));

app.mount('#app');

// App.vue example:
// <template>
//   <div>
//     <h1>Welcome to Vuestic UI</h1>
//     <VaButton>Click Me</VaButton>
//     <VaButton color="success">Success Button</VaButton>
//   </div>
// </template>
// <script setup>
//   // No explicit import needed in <script setup> if globally registered
// </script>