@maropost-ui/liquidsky-ui

@maropost-ui/liquidsky-ui

A shared UI component library, composables, and utilities for Vue 3 + Vuetify applications. This package provides reusable components and common functionality to accelerate development across multiple frontend applications.

Features

• 🎨 UI Components: Pre-built, accessible Vue components built with Vuetify
• 🔧 Composables: Reusable Vue 3 composition API functions
• 📦 Directives: Custom Vue directives for enhanced functionality
• 📝 TypeScript Support: Full TypeScript definitions and type safety
• 📖 Documentation: Auto-generated component documentation

Peer Dependencies

The following packages are required as peer dependencies:

• vue (^3.5.11) - Vue.js framework
• vue-router (^4.4.5) - Vue router
• date-fns-tz (^3.2.0) - Date utilities with timezone support
• lz-string (^1.5.0) - String compression library

Quick Start

npm install @maropost-ui/liquidsky-ui

import { AppBreadcrumb, TheThemeSwitcher } from '@maropost-ui/liquidsky-ui'

Theme lives in TheUserDropdown: click Theme for Classic / Marobase. Light / Dark sun–moon controls appear on the right only for Marobase. Persist key is liquidsky-theme.

Test identifiers (v-mp-test)

Default data-testids per component (root + built-in actions) live in source:

• src/directives/mpTestComponentDefaults.ts — MP_TEST_COMPONENT_DEFAULTS
• src/directives/mpTestConfig.ts — MP_TEST_IDS string constants

import { MP_TEST_COMPONENT_DEFAULTS, MP_TEST_IDS } from '@maropost-ui/liquidsky-ui'

MP_TEST_COMPONENT_DEFAULTS.AppDialogWrapper.ids
// → [{ role: 'root', id: 'mp-dialog' }, { role: 'cancel', … }, { role: 'save', … }]

Storybook: Directives → MpTest (catalog of defaults).

Liquidsky UI in Nuxt (Vue 3 + Vuetify)

Use these steps with Nuxt 4 (srcDir defaults to the app/ directory).

1. Install packages

npm install @maropost-ui/liquidsky-ui

Liquidsky ships Maropost’s Vuetify setup (themes, defaults, registration) and lists Vuetify and other runtime libraries as dependencies of the package, so they are installed automatically with @maropost-ui/liquidsky-ui. You do not add vuetify (or similar) as a separate install step in your app.

Nuxt already provides Vue and Vue Router for a normal app shell.

2. Import Liquidsky global styles (nuxt.config.ts)

Liquidsky’s CSS entry wires up Vuetify and library styles:

export default defineNuxtConfig({
  css: ['@maropost-ui/liquidsky-ui/styles'],
})

3. Register the Liquidsky / Vuetify plugin (app/plugins/**)

Liquidsky’s default export installs Vuetify (defaults, directives, aliases). Plugins must live under app/plugins/, not project-root plugins/, so Nuxt 4 discovers them automatically.

Example app/plugins/liquidsky-ui.ts:

import LiquidskyUI from '@maropost-ui/liquidsky-ui'

export default defineNuxtPlugin({
  name: 'liquidsky-ui',
  enforce: 'post',
  async setup(nuxtApp) {
    // Liquidsky’s install() is async; Vue does not await app.use(). Awaiting avoids
    // SSR rendering before Vuetify is registered.
    await Promise.resolve(LiquidskyUI.install(nuxtApp.vueApp))
  },
})

Notes:

• Prefer LiquidskyUI.install + await as above rather than vueApp.use(LiquidskyUI), so SSR waits for registration.
• To adjust Vuetify (themes, defaults, component overrides, etc.), pass a second argument to install. It is merged with Liquidsky’s built-in config (the same options shape as createLiquidSkyVuetify from @maropost-ui/liquidsky-ui):

await Promise.resolve(
  LiquidskyUI.install(nuxtApp.vueApp, {
    defaults: {
      // e.g. change overlay attach away from ".maropost-app"
      global: { attach: '#app' },
    },
  }),
)

4. Wrap the shell with v-app (maropost-app optional)

Put a root v-app around your UI app/app.vue (often with v-main for page content)—that matches normal Vuetify usage for layout and app-wide behavior.

Adding class="maropost-app" is optional:

• With Liquidsky’s defaults, Vuetify uses defaults.global.attach: '.maropost-app', so floated layers (menus, tooltips, dialogs) expect an element with that class. For example <v-app class="maropost-app"> is an easy match.
• If you prefer not to use that class, override defaults.global.attach when you create/customize Liquidsky’s Vuetify instance so it points at your own wrapper—or another attach target—as long as it exists in the DOM.

<template>
  <v-app class="maropost-app">
    <!-- Nuxt replaces this with layouts/pages -->
    <NuxtLayout />
  </v-app>
</template>

5. Use components

Import from the package wherever you need them:

<script setup lang="ts">
import { AppBreadcrumb, TheNotificationIcon } from '@maropost-ui/liquidsky-ui'
</script>

You may also keep using v-btn, v-tooltip, etc., after Liquidsky is installed—they are registered on the Vue app globally.

Local development in a consuming app

Use npm install for CI, teammates, and anything that should match production. Use npm link only when you are changing Liquidsky locally and want the app to pick up rebuilt dist/ without publishing.

Liquidsky ships Vuetify as a dependency. Commerce apps typically do not declare vuetify themselves.

Webpack vue.config.js (required for Vue CLI apps)

Add this whether the app uses npm install or npm link. It keeps a single Vue copy and tells webpack where Vuetify is.

const path = require('path')
const { createLiquidskyWebpackResolve } = require('@maropost-ui/liquidsky-ui/webpack')

const liquidskyResolve = createLiquidskyWebpackResolve(__dirname)

module.exports = {
  transpileDependencies: ['@maropost-ui/liquidsky-ui'],
  configureWebpack: {
    resolve: {
      ...liquidskyResolve,
      alias: {
        '@': path.resolve(__dirname, 'src'),
        ...liquidskyResolve.alias,
      },
    },
  },
}

@maropost-ui/liquidsky-ui/webpack exists only in Liquidsky versions that include this helper. Install from this repo (pack / path) until that version is published.

Method 1: npm install (normal / published / pack)

No link:webpack. No --app. npm hoists Vuetify into the app’s node_modules.

From the registry (after the helper is published):

cd /path/to/maropost-frontend-app   # or maropost-cloud-frontend / commerce-backoffice-frontend
npm install @maropost-ui/liquidsky-ui

From this repo, without publishing:

cd liquidsky-frontend
npm install
npm run build
npm pack

cd /path/to/maropost-frontend-app   # or maropost-cloud-frontend / commerce-backoffice-frontend
npm unlink --no-save @maropost-ui/liquidsky-ui   # only if you previously npm-linked
npm install /path/to/liquidsky-frontend/maropost-ui-liquidsky-ui-<version>.tgz

Prefer the .tgz over npm install /path/to/liquidsky-frontend. A folder install can still symlink and hit the same webpack issue as a repo-root npm link.

Method 2: npm link (local Liquidsky changes)

Do not npm link from this repo root in a Webpack app. Webpack follows that symlink into Liquidsky’s node_modules and loads a second Vue.

Vite consumers

cd liquidsky-frontend
npm install
npm run dev
npm link

cd /path/to/your-vite-app
npm link @maropost-ui/liquidsky-ui

Webpack consumers (maropost-frontend-app / maropost-cloud-frontend / commerce-backoffice-frontend)

--app is one-time setup for that app (creates node_modules/vuetify if it is missing). You do not pass the path on later rebuilds.

The -- after npm run link:webpack forwards flags to the script.

Once per webpack app:

cd liquidsky-frontend
npm install
npm run build
npm run link:webpack -- --app /path/to/maropost-frontend-app
# or
npm run link:webpack -- --app /path/to/maropost-cloud-frontend
# or
npm run link:webpack -- --app /path/to/commerce-backoffice-frontend

cd /path/to/maropost-frontend-app   # or maropost-cloud-frontend / commerce-backoffice-frontend
npm unlink --no-save @maropost-ui/liquidsky-ui   # if you previously linked the repo root
npm link @maropost-ui/liquidsky-ui

If a repo-root link is still registered globally:

npm unlink -g @maropost-ui/liquidsky-ui

Every later rebuild (no --app):

cd liquidsky-frontend
npm run link:webpack
# or, rebuild on save:
npm run link:webpack:watch

Then restart or refresh the webpack app. link:webpack copies dist/ to ../.liquidsky-ui-link (a folder with no Liquidsky Vue) and runs npm link from there.

Use --app again only if you clone a new consumer, delete node_modules, or Vuetify disappears from the app.

Updating and Publishing Liquidsky Package with npm

✅ 1. Commit changes including version update

Before publishing, make sure everything is committed and pushed to your main branch.

• Update your code
• Then update the version in package.json

You can do it manually or run:

npm version patch --no-git-tag-version   # bug fixes
npm version minor --no-git-tag-version   # new features
npm version major --no-git-tag-version   # breaking changes

• Then run npm run changelog:generate to generate changelog.md file

Commit and push everything:

git add .
git commit -m "feat: update package (vX.X.X)"
git push origin main

✅ 2. Login to npm

If not already logged in:

npm login

✅ 3. Publish your package

Run:

npm publish

For scoped packages:

npm publish --access public

✅ That's it --- your changes are now live.

Documentation

This package features automated Storybook documentation that stays synchronized with your components and keeps docs always up-to-date with your code.

# Start Storybook dev server (recommended for development)
npm run storybook

# Build Storybook for static deployment
npm run storybook:build

Default URL: http://localhost:6006

Development standards

Linting, type checking, tests, and git hooks are documented in CONTRIBUTING.md.

Quick reference:

npm run lint          # ESLint
npm run typecheck     # vue-tsc
npm run test          # Vitest unit tests (tests/)
npm run test:storybook # Vitest story tests in browser (Storybook addon)
npm run storybook     # UI with testing widget + pass/fail on stories
npm run generate-test -- src/components/MyComponent.vue

📂 Story Organization

stories/
├── custom-components/   # Component stories
│   ├── AppBreadcrumbs.stories.ts
│   └── AppDropdown.stories.tsx
├── composables/         # Composables stories
|── Directive 
|── vuetify-components   # All vuetify component stories 
├── utils/               # Utility stories