|
| 1 | +# Vue Plugin Template |
| 2 | + |
| 3 | +A comprehensive template for creating Vue 3 plugins with TypeScript, testing, and development tools pre-configured. |
| 4 | + |
| 5 | +## 🚀 Features |
| 6 | + |
| 7 | +- ✅ **Vue 3** support with TypeScript |
| 8 | +- ✅ **Local playground** for testing your plugin during development |
| 9 | +- ✅ **Unit testing** with Vitest and Vue Test Utils |
| 10 | +- ✅ **Linting** with ESLint and Prettier |
| 11 | +- ✅ **GitHub Actions** CI/CD pipeline |
| 12 | +- ✅ **Build configuration** for npm package publishing |
| 13 | +- ✅ **Example components** and composables |
| 14 | + |
| 15 | +## 🏁 Getting Started |
| 16 | + |
| 17 | +### 1. Clone this template |
| 18 | + |
| 19 | +```bash |
| 20 | +git clone https://github.com/monterail/vue-plugin-template.git |
| 21 | +cd vue-plugin-template |
| 22 | +``` |
| 23 | + |
| 24 | +### 2. Install dependencies |
| 25 | + |
| 26 | +```bash |
| 27 | +npm install |
| 28 | +``` |
| 29 | + |
| 30 | +### 3. Customize your plugin |
| 31 | + |
| 32 | +Update the following files: |
| 33 | + |
| 34 | +- `package.json` - Change name, description, author, etc. |
| 35 | +- `src/index.ts` - Rename your plugin and customize functionality |
| 36 | +- `src/components/` - Add or modify components |
| 37 | +- `src/composables/` - Add or modify composables |
| 38 | +- `README.md` - Update documentation for your plugin |
| 39 | + |
| 40 | +### 4. Start development |
| 41 | + |
| 42 | +```bash |
| 43 | +# Run the playground for local development |
| 44 | +npm run dev |
| 45 | + |
| 46 | +# Or run tests in watch mode |
| 47 | +npm run test:watch |
| 48 | +``` |
| 49 | + |
| 50 | +## 🛠️ Development |
| 51 | + |
| 52 | +### Basic Plugin Structure |
| 53 | + |
| 54 | +```typescript |
| 55 | +// src/index.ts |
| 56 | +import type { App, Plugin } from 'vue' |
| 57 | + |
| 58 | +export interface MyPluginOptions { |
| 59 | + // Your options here |
| 60 | +} |
| 61 | + |
| 62 | +const MyPlugin: Plugin = { |
| 63 | + install(app: App, options: MyPluginOptions = {}) { |
| 64 | + // Register components |
| 65 | + app.component('MyComponent', MyComponent) |
| 66 | + |
| 67 | + // Add global properties |
| 68 | + app.config.globalProperties.$myPlugin = { |
| 69 | + // Your global methods |
| 70 | + } |
| 71 | + |
| 72 | + // Provide data |
| 73 | + app.provide('myData', someData) |
| 74 | + } |
| 75 | +} |
| 76 | + |
| 77 | +export default MyPlugin |
| 78 | +``` |
| 79 | + |
| 80 | +### Registering Components |
| 81 | + |
| 82 | +```typescript |
| 83 | +// Register globally |
| 84 | +app.component('MyComponent', MyComponent) |
| 85 | + |
| 86 | +// Register with prefix |
| 87 | +const prefix = options.prefix || 'My' |
| 88 | +app.component(`${prefix}Component`, MyComponent) |
| 89 | +``` |
| 90 | + |
| 91 | +### Adding Global Properties |
| 92 | + |
| 93 | +```typescript |
| 94 | +app.config.globalProperties.$myPlugin = { |
| 95 | + greet: (name: string) => `Hello, ${name}!` |
| 96 | +} |
| 97 | + |
| 98 | +// TypeScript types |
| 99 | +declare module '@vue/runtime-core' { |
| 100 | + export interface ComponentCustomProperties { |
| 101 | + $myPlugin: { |
| 102 | + greet: (name: string) => string |
| 103 | + } |
| 104 | + } |
| 105 | +} |
| 106 | +``` |
| 107 | + |
| 108 | +### Creating Composables |
| 109 | + |
| 110 | +```typescript |
| 111 | +// src/composables/useMyPlugin.ts |
| 112 | +import { ref, computed } from 'vue' |
| 113 | + |
| 114 | +export function useMyPlugin() { |
| 115 | + const count = ref(0) |
| 116 | + const double = computed(() => count.value * 2) |
| 117 | + |
| 118 | + const increment = () => count.value++ |
| 119 | + |
| 120 | + return { count, double, increment } |
| 121 | +} |
| 122 | +``` |
| 123 | + |
| 124 | +## 🔧 Using Your Published Plugin |
| 125 | + |
| 126 | +Once published, users can install and use your plugin: |
| 127 | + |
| 128 | +```bash |
| 129 | +npm install your-plugin-name |
| 130 | +``` |
| 131 | + |
| 132 | +```typescript |
| 133 | +// main.ts |
| 134 | +import { createApp } from 'vue' |
| 135 | +import App from './App.vue' |
| 136 | +import MyPlugin from 'your-plugin-name' |
| 137 | + |
| 138 | +const app = createApp(App) |
| 139 | + |
| 140 | +app.use(MyPlugin, { |
| 141 | + // Plugin options |
| 142 | +}) |
| 143 | + |
| 144 | +app.mount('#app') |
| 145 | +``` |
| 146 | + |
| 147 | +```vue |
| 148 | +<!-- Using in components --> |
| 149 | +<template> |
| 150 | + <MyComponent /> |
| 151 | +</template> |
| 152 | +
|
| 153 | +<script setup> |
| 154 | +import { useMyPlugin } from 'your-plugin-name' |
| 155 | +
|
| 156 | +const { count, increment } = useMyPlugin() |
| 157 | +</script> |
| 158 | +``` |
| 159 | + |
| 160 | +## 🤝 Contributing |
| 161 | + |
| 162 | +Contributions are welcome! Please feel free to submit a Pull Request. |
| 163 | + |
| 164 | +## 📄 License |
| 165 | + |
| 166 | +MIT |
| 167 | + |
| 168 | +## 🙏 Acknowledgments |
| 169 | + |
| 170 | +Built with: |
| 171 | +- [Vue 3](https://vuejs.org/) |
| 172 | +- [Vite](https://vitejs.dev/) |
| 173 | +- [Vitest](https://vitest.dev/) |
| 174 | +- [TypeScript](https://www.typescriptlang.org/) |
| 175 | +- [Vue Test Utils](https://test-utils.vuejs.org/) |
| 176 | + |
| 177 | +--- |
| 178 | + |
| 179 | +**Happy plugin building! 🎉** |
| 180 | + |
| 181 | +If you find this template helpful, please give it a ⭐️ on GitHub! |
0 commit comments