tessl/npm-unplugin-vue-macros

Explore more macros and syntax sugar to Vue.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

unplugin-vue-macros

Name: tessl/npm-unplugin-vue-macros
Author: tessl

unplugin-vue-macros is a comprehensive collection of macros and syntax sugar for Vue.js that extends the capabilities of <script setup> and Single File Components (SFCs). It provides 20+ macros including defineOptions, defineProps, defineEmit, defineModels, and many more, along with advanced features like reactivity transform, JSX directive support, and setup component syntax.

Package Information

Package Name: unplugin-vue-macros
Package Type: npm
Language: TypeScript
Installation: npm install unplugin-vue-macros
Vue Compatibility: Vue 2.7+ and Vue 3

Core Imports

For bundler plugins:

// Vite
import VueMacros from "unplugin-vue-macros/vite";

// Webpack
import VueMacros from "unplugin-vue-macros/webpack";

// Rollup
import VueMacros from "unplugin-vue-macros/rollup";

// esbuild  
import VueMacros from "unplugin-vue-macros/esbuild";

// Rspack
import VueMacros from "unplugin-vue-macros/rspack";

// Rolldown
import VueMacros from "unplugin-vue-macros/rolldown";

For configuration and types:

import { defineConfig, resolveOptions, type Options } from "unplugin-vue-macros";

For runtime utilities:

import { useRef } from "unplugin-vue-macros/runtime";

For Volar integration:

import { define } from "unplugin-vue-macros/volar";

Basic Usage

Bundler Setup

Vite Configuration:

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import VueMacros from "unplugin-vue-macros/vite";

export default defineConfig({
  plugins: [
    VueMacros({
      plugins: {
        vue: vue(),
        // Additional plugin options
      },
    }),
  ],
});

Nuxt Configuration:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    "@vue-macros/nuxt",
  ],
});

Vue Component Usage

Basic Macro Usage:

<script setup>
// Define component options
defineOptions({
  name: "MyComponent",
  inheritAttrs: false,
});

// Define props with defaults and validation
const { name, age = 18 } = defineProps<{
  name: string;
  age?: number;
}>();

// Define emits
const emit = defineEmit<{
  update: [value: string];
  delete: [];
}>();

// Define models (Vue 3.4+ style with macro)
const modelValue = defineModel<string>();
const checked = defineModel<boolean>("checked");

// Define slots with types
const slots = defineSlots<{
  default(): any;
  header(props: { title: string }): any;
}>();

// Chain call for props
const { count } = $defineProps<{ count: number }>();
</script>

Architecture

Vue Macros uses the unplugin architecture combined with Vue's transform pipeline:

Unplugin Core: Universal plugin system providing adapters for all major bundlers
Transform Pipeline: Multi-stage AST transformation processing Vue SFCs and JavaScript/TypeScript files
Macro Registry: Centralized system managing 20+ macro plugins
Configuration System: Flexible options resolution with per-macro configuration
Type System: Complete TypeScript integration with Vue 2.7 and Vue 3 type definitions
Volar Integration: Language server support for IDE features

Capabilities

Main Plugin

The combined plugin instance that includes all macro plugins.

declare const plugin: UnpluginCombineInstance<Options | undefined>;

// Bundler-specific exports
export default plugin;

Configuration System

Comprehensive configuration options for all macros.

/**
 * Define configuration for Vue Macros
 * @param options - Configuration options
 * @returns Configuration object
 */
function defineConfig(options: Options): Options;

/**
 * Resolve configuration options with defaults
 * @param options - User configuration options  
 * @param cwd - Current working directory
 * @returns Resolved configuration
 */
function resolveOptions(options?: Options, cwd?: string): OptionsResolved;

interface Options extends OptionsCommon {
  // Props & Models
  chainCall?: boolean | OptionsChainCall;
  defineProps?: boolean | OptionsDefineProps;
  definePropsRefs?: boolean | OptionsDefinePropsRefs;
  defineModels?: boolean | OptionsDefineModels;
  defineProp?: boolean | OptionsDefineProp;
  
  // Component Options
  defineOptions?: boolean | OptionsDefineOptions;
  defineSlots?: boolean | OptionsDefineSlots;
  defineEmit?: boolean | OptionsDefineEmit;
  defineRender?: boolean | OptionsDefineRender;
  
  // Advanced Features
  betterDefine?: boolean | OptionsBetterDefine;
  reactivityTransform?: boolean | OptionsReactivityTransform;
  setupComponent?: boolean | OptionsSetupComponent;
  setupSFC?: boolean | OptionsSetupSFC;
  setupBlock?: boolean | OptionsSetupBlock;
  
  // Syntax Sugar
  shortEmits?: boolean | OptionsShortEmits;
  shortVmodel?: boolean | OptionsShortVmodel;
  shortBind?: boolean | OptionsShortBind;
  booleanProp?: boolean | OptionsBooleanProp;
  
  // Export Features
  exportExpose?: boolean | OptionsExportExpose;
  exportProps?: boolean | OptionsExportProps;
  exportRender?: boolean | OptionsExportRender;
  
  // Optimization
  hoistStatic?: boolean | OptionsHoistStatic;
  
  // JSX Features
  jsxDirective?: boolean | OptionsJsxDirective;
  
  // Language Features
  scriptLang?: boolean | OptionsScriptLang;
  
  // Styling
  defineStyleX?: boolean | OptionsDefineStyleX;
  
  // Templates
  namedTemplate?: boolean | OptionsNamedTemplate;
}

interface OptionsCommon {
  root?: string;
  plugins?: {
    vue?: any;
    vueJsx?: any;
    vueRouter?: any;
  };
}

Configuration

Props and Models Macros

Enhanced props and model definition capabilities.

// Chain call syntax for props
declare const $defineProps: typeof definePropsChainCall;
declare const defineProps: DefineProps;

// Props refs for easy reactive access
declare function definePropsRefs<T>(): PropsRefs<T>;

// Individual prop definition
declare function defineProp<T>(name: string, options?: PropOptions<T>): T;

// Enhanced models
declare function defineModels<T>(): Models<T>;

Props and Models

Component Definition Macros

Core macros for component definition.

// Define component options (Vue 2.7+ / Vue 3.0-3.2)
declare function defineOptions(options: ComponentOptions): void;

// Define component slots with types
declare function defineSlots<T>(): Slots<T>;

// Define single emit function
declare function defineEmit<T>(name: string): EmitFunction<T>;

// Define render function
declare function defineRender(render: RenderFunction): void;

Component Definition

Advanced Features

Advanced macros and transformations.

// Better define integration
declare function betterDefine(): void;

// Reactivity transform
declare const $ref: typeof ref;
declare const $computed: typeof computed;
declare const $shallowRef: typeof shallowRef;

// Setup component syntax
declare function setupComponent(options: SetupComponentOptions): void;

// Setup SFC
declare function setupSFC(): void;

Advanced Features

Syntax Sugar

Shorthand syntax and convenience features.

// Short emits: emits(eventName, ...args)
declare function emits<T>(name: keyof T, ...args: any[]): void;

// Short v-model: ::modelValue
// Short bind: :prop-name

// Boolean props: +prop-name

Syntax Sugar

Runtime Utilities

Runtime helper functions and references.

/**
 * Alias for shallowRef from Vue
 */
export const useRef: typeof shallowRef;

Type Definitions

Complete TypeScript integration with utility types.

// Feature option types
type FeatureName = keyof FeatureOptionsMap;
type FeatureOptions = FeatureOptionsMap[FeatureName];

// Configuration types
type OptionsResolved = Required<OptionsCommon> & {
  [K in keyof FeatureOptionsMap]: false | FeatureOptionsMap[K];
};

// Props utilities
type PropsRefs<T> = {
  [K in keyof T]: Ref<T[K]>;
};

// Model utilities  
type Models<T> = {
  [K in keyof T]: WritableComputedRef<T[K]>;
};

// Generic utilities
type RecordToUnion<T> = T[keyof T];
type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;