Quasar Component Library

A collection of reusable Vue 3 + Quasar components with TypeScript support, perfect for building modern web applications.

📦 Components

QuasarButton

A fully customizable button component that wraps Quasar's QBtn with all props support.

View Full Button Documentation →

Quick example:

<script setup>
import { QuasarButton } from 'quasar-component-library'
</script>

<template>
  <QuasarButton 
    label="Click Me" 
    color="primary" 
    icon="save"
    @click="handleClick" 
  />
</template>

Features

• ✅ Vue 3 with Composition API
• ✅ Quasar Framework support
• ✅ TypeScript for type safety
• ✅ Fully Typed Props - Complete IntelliSense support
• ✅ Reusable Components - Decoupled and prop-driven
• ✅ Vite for fast builds
• ✅ Dual Format Build - ES Modules and CommonJS

Installation

npm install quasar-component-library
# or
pnpm install quasar-component-library

Peer Dependencies Required:

npm install quasar vue

Usage

<script setup>
import { QuasarButton } from 'quasar-component-library'

const handleClick = () => {
  console.log('Button clicked!')
}
</script>

<template>
  <div>
    <!-- Basic button -->
    <QuasarButton label="Save" color="primary" @click="handleClick" />
    
    <!-- Button with icon -->
    <QuasarButton label="Delete" color="negative" icon="delete" />
    
    <!-- Loading button -->
    <QuasarButton label="Loading..." :loading="true" color="primary" />
    
    <!-- Outlined button -->
    <QuasarButton label="Cancel" outline color="primary" />
  </div>
</template>

Component Documentation

• QuasarButton - Full Documentation - Comprehensive guide with all props and features
• Quick Reference - Cheat sheet for common use cases
• Examples - Complete working examples and demos

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 MyComponent } from "./components/MyComponent.vue";
     export * from "./utils/helpers";

Usage

Path Aliases

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

// ✅ Good - Using path alias
import { API_BASE_URL } from "src/consts";
import MyComponent from "src/components/MyComponent.vue";
import { helper } from "src/utils/helpers";

// ❌ Avoid - Relative paths (still works, but not recommended)
import { API_BASE_URL } from "../consts";
import MyComponent from "./components/MyComponent.vue";

Adding More Path Aliases

To add additional path aliases (e.g., @/, @components/, etc.):

1. Update tsconfig.json:

   {
     "compilerOptions": {
       "baseUrl": ".",
       "paths": {
         "src/*": ["./src/*"],
         "@/*": ["./src/*"],
         "@components/*": ["./src/components/*"],
         "@utils/*": ["./src/utils/*"]
       }
     }
   }

2. Update vite.config.ts:

   resolve: {
     alias: {
       'src': resolve(__dirname, './src'),
       '@': resolve(__dirname, './src'),
       '@components': resolve(__dirname, './src/components'),
       '@utils': resolve(__dirname, './src/utils')
     }
   }

   The vite-tsconfig-paths plugin will automatically read from tsconfig.json, but explicit aliases in Vite config ensure build-time resolution works correctly.

3. Restart your TypeScript server (in VS Code/Cursor: Cmd+Shift+P → "TypeScript: Restart TS Server")

Project Structure

├─ src/
│   ├─ components/          # Vue components
│   │   └─ ExampleComponent.vue
│   ├─ utils/              # Utility functions (optional)
│   ├─ types/              # TypeScript type definitions (optional)
│   ├─ consts.ts           # Constants
│   ├─ index.ts            # Main export file
│   └─ 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

Build Output Structure

dist/
└─ src/
   ├─ index.js              # ES Module entry
   ├─ index.cjs             # CommonJS entry
   ├─ components/
   │   └─ ...
   └─ ...

Testing Locally

Option 1: Using pnpm link (Recommended)

1. In your plugin directory:

   pnpm link --global

2. In your test project:

   pnpm link --global <your-package-name>

3. Use in your project:

   <script setup>
   import { ExampleComponent } from "<your-package-name>";
   // or
   import { ExampleComponent } from "<your-package-name>/src/components/ExampleComponent.vue";
   </script>

Option 2: Using File Path

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

   {
     "dependencies": {
       "<your-package-name>": "file:../path/to/your/plugin"
     }
   }

2. Install:

   pnpm install

3. Use in your project:

   <script setup>
   import { ExampleComponent } from "<your-package-name>";
   </script>

Development Workflow

For active development with auto-rebuild:

Run in watch mode:

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 semver)
   • Add description, keywords, author, license
   • Verify files array includes only what should be published:

     {
       "files": ["dist"]
     }

2. Build the package:

   pnpm run build

3. Test the build locally (see Testing Locally section above)

Publishing Steps

1. Login to npm:

   npm login

2. Verify you're logged in:

   npm whoami

3. Check what will be published:

   npm pack --dry-run

4. Publish:

   npm publish

   For scoped packages (e.g., @your-org/package-name):

   npm publish --access public

5. Verify on npm: Visit https://www.npmjs.com/package/<your-package-name>

Version Management

Use npm version commands to bump versions:

# Patch version (1.0.0 → 1.0.1)
npm version patch

# Minor version (1.0.0 → 1.1.0)
npm version minor

# Major version (1.0.0 → 2.0.0)
npm version major

Then publish:

npm publish

Configuration

External Dependencies

By default, vue and quasar are marked as external (not bundled). To add more:

Update vite.config.ts:

rollupOptions: {
  external: (id) => {
    return (
      id === "vue" ||
      id === "quasar" ||
      id.startsWith("@quasar/") ||
      id.startsWith("quasar/") ||
      id === "some-other-package"
    ); // Add here
  };
}

Build Formats

The template builds both ES Modules and CommonJS. To change formats:

Update vite.config.ts:

build: {
  lib: {
    formats: ["es", "cjs"]; // or ['es'], ['cjs'], etc.
  }
}

Handling External Dependencies

Using Quasar Extras and Icon Sets

If your plugin requires dependencies like @quasar/extras, FontAwesome icons, or other Quasar-related packages that may not be present in the target project, you should declare them as peer dependencies rather than regular dependencies.

Why Peer Dependencies?

• Smaller bundle size: External dependencies aren't bundled into your package
• Version control: Consumers control which versions to install
• Avoid conflicts: Prevents duplicate packages in the consumer's project
• Best practice: Standard approach for library/plugin packages

Step 1: Add Peer Dependencies

Update your package.json to include peer dependencies:

{
  "peerDependencies": {
    "quasar": "^2.18.6",
    "vue": "^3.5.25",
    "@quasar/extras": "^1.0.0"
  },
  "peerDependenciesMeta": {
    "@quasar/extras": {
      "optional": true
    }
  }
}

Notes:

• peerDependencies: Required dependencies that consumers must install
• peerDependenciesMeta: Mark dependencies as optional if they're not always needed
• Keep quasar and vue in dependencies for development, but also list them in peerDependencies for consumers

Step 2: Ensure Externalization in Build Config

Your vite.config.ts should already externalize @quasar/ packages (this is already configured):

rollupOptions: {
  external: (id) => {
    return (
      id === "vue" ||
      id === "quasar" ||
      id.startsWith("@quasar/") || // ✅ Already covers @quasar/extras
      id.startsWith("quasar/")
    );
  };
}

If you need to externalize additional packages, add them to the external function:

rollupOptions: {
  external: (id) => {
    return (
      id === "vue" ||
      id === "quasar" ||
      id.startsWith("@quasar/") ||
      id.startsWith("quasar/") ||
      id === "some-other-package" || // Add specific packages
      id.startsWith("@some-scope/") // Or entire scopes
    );
  };
}

Step 3: Document for Consumers

Add installation instructions to your README for consumers:

## Installation

```bash
npm install your-package @quasar/extras
# or
pnpm install your-package @quasar/extras
```

Quasar Configuration

If you're using FontAwesome icons or other icon sets from @quasar/extras, configure them in your Quasar project:

For Quasar CLI projects (quasar.conf.js):

module.exports = function (ctx) {
  return {
    extras: [
      "fontawesome-v6", // or 'fontawesome-v5', 'material-icons', etc.
      "material-icons-outlined",
    ],
    // ... rest of config
  };
};

For Vite projects (quasar.config.js):

export default {
  extras: ["fontawesome-v6", "material-icons-outlined"],
  // ... rest of config
};

Step 4: Handle Missing Dependencies Gracefully (Optional)

If you want to provide fallbacks when dependencies aren't available, you can check for them:

<script setup>
import { computed } from "vue";

const props = defineProps({
  icon: { type: String, default: "close" },
});

// Example: Fallback to Material Icons if FontAwesome not available
const safeIcon = computed(() => {
  // If using FontAwesome icon (fa- prefix), ensure @quasar/extras is installed
  if (props.icon?.startsWith("fa-") || props.icon?.startsWith("fas ")) {
    // Document that @quasar/extras is required for FontAwesome icons
    return props.icon;
  }
  return props.icon;
});
</script>

Best Practices

• ✅ Use peer dependencies for packages that should be provided by the consumer
• ✅ Use regular dependencies only for packages that are internal to your plugin
• ✅ Document all peer dependencies in your README
• ✅ Use Material Icons by default (built into Quasar) when possible
• ✅ Only require @quasar/extras when you specifically need FontAwesome, Material Symbols, etc.
• ❌ Don't bundle large dependencies like icon sets into your package
• ❌ Don't assume consumers have specific Quasar extras installed

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 (e.g., 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

License

ISC (or update to your preferred license)

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! 🚀