We just released Vuestic Admin 3.0 🤗
🔥🔥🔥 Hire us

Structure
#

Here you can learn about Vuestic UI file structure and understand how to keep your work synced with our conventions. It's great to check when you're unsure, though sometimes it's easier to understand just by looking on file contents.

Components
#

va-[component-name]
components
Va[SubComposableName].vue
hooks
use[ComposableName].ts
plugins
index.ts
tests
Va[ComponentName].spec.js
use[ComposableName].spec.js
utils
_variables.scss
index.ts
types.ts
Va[ComponentName].demo.vue
Va[ComponentName].vue

From ./types.ts export all types: prop types, emit events etc.

From ./index.ts export both component and its sub-components using named exports. Then you should also connect it in /src/components/index.ts - all components should be registered there.

From ./plugin/index.ts export plugin with named export. It should use defineVuesticPlugin. This plugin will be available in vuestic-ui root exports.

We write all component with Composition API. Key reason is high reuse value of composables.

Here's a checklist you can go through when working on component:

  • Component name should always have Va prefix.
  • All CSS variables should have va- prefix.
  • CSS variables are meant as a part of interface. We expect users to change them. CSS variables are pretty expensive though, so please don't use them on styles that are unlikely to be changed by user (also user can directly override class if it's a must). Here's some examples:
    • good: color, font, border;
    • bad: align-items, top, left.
  • Use props from composables if needed.
  • Provide typing for complex types via PropType.
  • Don't use required for props, use default instead. User expects component to work with as few props as possible.
  • Make sure component supports stateful mode.
  • Explicitly define emits so that typescript would be able to derive type. We also use emits in documentation.
  • Check existing composables before creating new one.
  • Remember about SSR. Use SSR-friendly composables like useClickOnly, useDocument, useEvent etc.
  • Remember that user can access component methods with ref. Expose methods like focus, validate from setup function.
  • Follow CSS variables guide.
  • Use BEM for component classes. We support tailwind, but it's only for external usage.
  • Use SCSS mixins.
  • Do not use scoped styles in components.
  • Follow Accessibility best practices: use semantic tags, aria attributes, hover state etc.

Composables
#

Composable - function that is used inside of component setup block. Usually it provides reactive variables, computeds or methods.

Check https://vueuse.org/ when you work with composables. They already have a lot of functionality we need. You also may check how they implement composables.

Here's a checklist you can go through when working on composable:

  • Start composable name with use.
  • Write composable in one file. If you have large composable, split it in multiple small composables. If these composables are useless without each other, use folder with index.ts and export one composable from here.
  • Composable can return one object (reactive or ref) or object that contains refs, methods computes.
  • Reuse composables if possible.
  • Export (or even re-export) types in composable.
  • Attach your composable to /src/composables/index.ts;
  • Write tests under /src/composables/tests/use[ComposableName].spec.ts. It's a great idea to uint-test composables.

Styles
#

There are three types of styles:

  • CSS modules - css file with global styles. CSS modules must be independent and focus on one feature. For example: typography, grid, normalize.
  • SCSS resources - there must be only SCSS variables (! prefer CSS variables instead) or SCSS mixins. Resources can be used in modules, but they should never expose global styles by themselves.
  • Essential - css that must be included in user's app or components will break. For example - CSS variables.
styles
essential.scss
[module]
index.scss
mixins.scss
variables.scss
resources
index.scss
mixins.scss
variables.scss

Services
#

Ideally all services must be independent so that user is able to use only what they want. But we have two exceptions: GlobalConfig, ColorConfig - these are essential for Vuestic components, at least for now. Please don't implement services without planning or discussion with team.

services
[service-name]
tests
plugin
index.ts
config
index.ts
types.ts
index.ts

Utils
#

Utils are helper functions that can be used in multiple places. Usually utils are not related to Vuestic UI. e.g. isDefined