@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 } from '@maropost-ui/liquidsky-ui'

@maropost-ui/liquidsky-ui Local Development Guide

Use these methods to test @maropost-ui/liquidsky-ui changes in your consuming project (e.g., commerce-frontend or commerce-backoffice) without publishing to npm. Both leverage npm's linking and packaging features for rapid iteration in your app workflow.

🚀 Method 1: npm link (Recommended for Active Development)

Creates a symlink for instant hot-reloading of changes.

Note: This method does not work well with Webpack. If you are using Vite, this is the preferred approach. Otherwise, use Method 2.

Steps:

1. Clone the repository:

   git clone <repo-url> liquidsky-frontend
   cd liquidsky-frontend
   git checkout main

2. Install dependencies and build the package:

   npm install
   npm run dev

3. Create a local npm link:

   npm link

4. In your consuming project (e.g., commerce-frontend):

   cd /path/to/your/consuming-project
   npm link @maropost-ui/liquidsky-ui

Now, any changes you make in the liquidsky-frontend package will be reflected in your consuming project after rebuilding the library. This is useful for rapid development and testing across multiple projects locally.

📦 Method 2: Local npm pack (For Stable Builds)

Generates a distributable .tgz file for one-off installs.

Step 1: Clone and build the library

git clone <repo-url> liquidsky-frontend
cd liquidsky-frontend
git checkout main
npm install
npm run build

Step 2: Create package

npm pack
Creates liquidsky-ui-<version>.tgz.

Step 3: Install in consuming project

cd /path/to/commerce-backoffice  # or your project
npm install ../../path/to/liquidsky-frontend/liquidsky-ui-<version>.tgz

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

📂 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

Best Practices for Auto-Documentation

1. Use JSDoc Comments

/**
 * @description Search functionality composable with route integration
 * @example
 * ```typescript
 * const { keyword, submitSearch } = useSearch()
 * submitSearch()
 * ```
 */
export function useSearch(): SearchInterface

2. Document Component Props

export interface SearchBarProps {
  /** Search placeholder text */
  placeholder?: string
  /** Enable automatic route integration */
  useRouteIntegration?: boolean
}

3. Provide Usage Examples

<!--
Usage Example:
<TheSearchBar 
  placeholder="Search products..."
  @search="handleSearch"
/>
-->

4. Use TypeScript Types

// Explicit return types help documentation
export function useValidation(): ValidationInterface {
  // ...
}

Contributing

1. Follow the existing code style and patterns
2. Add JSDoc comments for new functions and components
3. Update this README when adding new features
4. Ensure all components are properly typed with TypeScript