Vue + Quasar Plugin Template

A modern starter template for building Vue 3 + Quasar plugins/libraries with TypeScript, Vite, and path aliases support.

Features

• ✅ Vue 3 with Composition API
• ✅ Quasar Framework support
• ✅ TypeScript for type safety
• ✅ Vite for fast builds
• ✅ Path Aliases - Import without relative paths (e.g., src/components/...)
• ✅ Dual Format Build - ES Modules and CommonJS
• ✅ Preserved Directory Structure - Maintains src/ structure in output
• ✅ SCSS/SASS support for styling

Getting Started

Prerequisites

• Node.js 20.19+ or 22.12+
• pnpm (recommended) or npm/yarn

Installation

1. Clone or use this template:

   git clone <your-repo-url>
   cd <your-project-name>

2. Install dependencies:

   pnpm install
   # or
   npm install

3. Update package.json:

   • Change name to your package name
   • Update version, description, author, license, and keywords
   • Adjust dependencies and devDependencies as needed

4. Update src/index.ts:

   • Export your main components/utilities
   • Example:

     export { default as ItcNavigationMenu } from './components/ItcNavigationMenu.vue'
     export { itcNavigationMenu } from './plugin'
     export type { ItcNavLink, ItcNavSubLink } from './types'

Usage

Path Aliases

This template supports importing files using the src/ prefix without relative paths:

// ✅ Good - Using path alias
import type { ItcNavLink } from 'src/types'
import ItcNavigationMenu from 'src/components/ItcNavigationMenu.vue'

// ❌ Avoid - Relative paths (still works, but not recommended)
import type { ItcNavLink } from '../types'
import ItcNavigationMenu from './components/ItcNavigationMenu.vue'

Example: itc-navigation-menu (basic)

<script setup lang="ts">
import { ref } from 'vue'
import { ItcNavigationMenu } from 'itc-navigation-menu'

const mini = ref(false)

const navLinks = [
  { label: 'Dashboard', icon: 'home', hash: '/' },
  {
    label: 'Task',
    icon: 'task',
    hash: '/cards-table',
    subLinks: [
      { label: 'Board', hash: '/cards-table/board' },
      { label: 'List', hash: '/cards-table/list' }
    ]
  }
]
</script>

<template>
  <q-drawer :model-value="true" bordered :mini="mini">
    <ItcNavigationMenu :nav-links="navLinks" :mini="mini" />
  </q-drawer>
</template>

Quick Demo File

If you want a ready example page, copy:

• src/examples/ItcNavigationMenuDemo.vue

Project Structure

src/
  components/          # Vue components
  examples/            # Demo SFCs for quick testing
  types.ts             # Component types
  index.ts             # Main export file
  plugin.ts            # Global install plugin
  vue-shim.d.ts        # Vue type declarations

dist/                  # Build output (generated)
package.json
tsconfig.json
vite.config.ts

Building

Build for Production

pnpm run build
# or
npm run build

This will:

• Compile TypeScript to JavaScript
• Bundle Vue components
• Generate both ES Modules (.js) and CommonJS (.cjs) formats
• Output to dist/ directory with preserved src/ structure

Testing Locally

Option 1: Using pnpm link (Recommended)

1. In your plugin directory:

   pnpm link --global

2. In your test project:

   pnpm link --global itc-navigation-menu

3. Use in your project:

   <script setup>
   import { ItcNavigationMenu } from "itc-navigation-menu"
   </script>

Option 2: Using File Path

1. In your test project's package.json:

   {
     "dependencies": {
       "itc-navigation-menu": "file:../path/to/itc-navigation-menu"
     }
   }

2. Install:

   pnpm install
   # or
   npm install

Development Workflow

For active development with auto-rebuild:

pnpm run dev

Changes will rebuild automatically. Restart your test project's dev server to pick up changes.

Publishing to npm

Before Publishing

1. Update package.json:

   • Set correct name (must be unique on npm)
   • Update version (follow https://semver.org/)
   • Add description, keywords, author, license
   • Verify files array includes only what should be published (typically dist)

2. Build the package:

   pnpm run build

3. Test the build locally

Publishing Steps

1. Login to npm:

   npm login

2. Publish:

   npm publish

Configuration

External Dependencies

By default, vue, quasar, and vue-router are marked as external (not bundled). This is handled in vite.config.ts.

Build Formats

The template builds both ES Modules and CommonJS formats.

Troubleshooting

TypeScript Errors

• "Cannot find module 'src/...'": Restart TypeScript server
• "Path aliases not working": Check both tsconfig.json and vite.config.ts

Build Errors

• "Rollup failed to resolve import": Ensure the package imports are externalized in vite.config.ts

License

MIT

itc-navigation-menu

Reusable menu-list component for Vue 3 + Quasar, built as a reusable library.

It renders navigation links with Quasar primitives (QList, QExpansionItem, QItem) and supports:

• Dynamic link arrays (navLinks)
• Parent/subLink active matching
• Mini mode behavior for drawer usage
• App-friendly route matching via matchPrefix

Features

• ✅ Vue 3 + Composition API
• ✅ Quasar 2 components under the hood (QList, QExpansionItem, QItem, QIcon)
• ✅ Dynamic menu links from a navLinks array
• ✅ Nested subLinks support
• ✅ Mini mode support for drawer integration
• ✅ Active matching for parent and subLinks
• ✅ TypeScript support (ItcNavLink, ItcNavSubLink)
• ✅ Built with Vite (ESM + CJS outputs, preserved src/ structure)

Installation

From npm (when published)

npm install itc-navigation-menu
# or
pnpm add itc-navigation-menu

Local file install

In your app's package.json:

{
  "dependencies": {
    "itc-navigation-menu": "file:../../project/itc-navigation-menu"
  }
}

Then:

npm install

Basic Usage

1. Import and use as a local component

<script setup>
import { ref } from 'vue'
import { ItcNavigationMenu } from 'itc-navigation-menu'

const mini = ref(false)

const navLinks = [
  { label: 'Dashboard', icon: 'home', hash: '/' },
  {
    label: 'Task',
    icon: 'task',
    hash: '/cards-table',
    subLinks: [
      { label: 'Board', hash: '/cards-table/board' },
      { label: 'List', hash: '/cards-table/list' }
    ]
  }
]
</script>

<template>
  <q-layout view="lHh Lpr lFf">
    <q-header bordered>
      <q-toolbar>
        <q-btn flat round dense icon="o_menu" @click="mini = !mini" />
        <q-toolbar-title>Demo</q-toolbar-title>
      </q-toolbar>
    </q-header>

    <q-drawer :model-value="true" bordered show-if-above :mini="mini">
      <ItcNavigationMenu :nav-links="navLinks" :mini="mini" />
    </q-drawer>
  </q-layout>
</template>

2. Register globally via plugin

// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import { itcNavigationMenu } from 'itc-navigation-menu'

const app = createApp(App)

app.use(itcNavigationMenu) // registers <ItcNavigationMenu> globally

app.mount('#app')

Props Overview (main ones)

Core

• navLinks (ItcNavLink[]) – navigation definitions array
• mini (boolean) – drawer mini state
• activeClass (string) – active class name for selected item
• matchPrefix (boolean) – prefix-based route matching when true

Notes

• Root path '/' uses exact matching to avoid "always active dashboard".
• Parent items with subLinks are considered active if any child route is active.
• In mini mode, expansion items are auto-opened to keep links usable.

See src/components/ItcNavigationMenu.vue for the full prop list.

Example File

A small playground is shipped in the package:

• src/examples/ItcNavigationMenuDemo.vue

You can copy this file into your app to get a working demo page quickly.

Project Structure

itc-navigation-menu/
├─ src/
│  ├─ components/
│  │  └─ ItcNavigationMenu.vue        # main component
│  ├─ examples/
│  │  └─ ItcNavigationMenuDemo.vue    # demo you can copy into your app
│  ├─ types.ts                        # ItcNavLink, ItcNavSubLink
│  ├─ index.ts                        # library entry (exports)
│  ├─ plugin.ts                       # global install plugin
│  └─ vue-shim.d.ts                   # Vue type declarations
├─ dist/                              # build output (generated)
├─ package.json
├─ tsconfig.json
└─ vite.config.ts

Building the Library

npm run build

This runs:

• vite build -> JS bundle (ESM + CJS, preserved modules)
• vue-tsc -p tsconfig.build.json -> type declarations into dist/src

The built entries are:

• dist/src/index.js / index.cjs
• plus preserved module files for components and types.

Local Development & Testing

Option 1: Using pnpm link (Recommended)

1. In your plugin directory:

   pnpm link --global

2. In your test project:

   pnpm link --global itc-navigation-menu

3. Use in your project:

   <script setup>
   import { ItcNavigationMenu } from 'itc-navigation-menu'
   </script>

Option 2: Using File Path

1. In your test project's package.json:

   {
     "dependencies": {
       "itc-navigation-menu": "file:../path/to/itc-navigation-menu"
     }
   }

2. Install:

   pnpm install
   # or
   npm install

3. Use in your project:

   <script setup>
   import { ItcNavigationMenu } from 'itc-navigation-menu'
   </script>

Unlinking After Local Development

When you're done with local development and want to switch back:

For Option 1 (pnpm/npm link)

1. Unlink:

   pnpm unlink --global itc-navigation-menu
   # or
   npm unlink itc-navigation-menu

For Option 2 (File Path)

1. Remove the file dependency from package.json
2. Run install again

Troubleshooting

TypeScript Errors

• "Cannot find module 'src/...'" : Restart TypeScript server
• "Cannot find module 'path'" : Ensure @types/node is installed
• Path aliases not working: Check both tsconfig.json and vite.config.ts have matching aliases

Build Errors

• "Rollup failed to resolve import": Add the package to external in vite.config.ts
• "Preprocessor dependency not found": Install required preprocessors (for example sass-embedded for SCSS)

Import Errors in Test Project

• Ensure the package is built (pnpm run build)
• Check package.json exports are correct
• Verify the import path matches your exports

Notes

• vue, quasar, and vue-router are peer dependencies and are treated as externals in vite.config.ts.
• Component renders only the navigation list. You control drawer/layout in your app.

License

MIT (or update to your preferred license in package.json).

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Build and test locally
5. Submit a pull request

Happy coding!