Unplugin Export Plugin

@talex-touch/unplugin-export-plugin is a build tool plugin for Tuff plugin development, handling automatic resource export, manifest generation, and dev server integration.

Installation

pnpm add -D @talex-touch/unplugin-export-plugin

Quick Start

Vite Configuration

// vite.config.ts
import TouchPluginExport from '@talex-touch/unplugin-export-plugin/vite'
import vue from '@vitejs/plugin-vue'
import UnoCSS from 'unocss/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    vue(),
    UnoCSS(),
    TouchPluginExport()
  ],
  server: {
    port: 6001  // Dev server port
  }
})

Webpack Configuration

// webpack.config.js
const TouchPluginExport = require('@talex-touch/unplugin-export-plugin/webpack')

module.exports = {
  plugins: [
    TouchPluginExport()
  ]
}

Rollup Configuration

// rollup.config.js
import TouchPluginExport from '@talex-touch/unplugin-export-plugin/rollup'

export default {
  plugins: [
    TouchPluginExport()
  ]
}

Features

1. Automatic Manifest Processing

The plugin automatically reads manifest.json from project root and during build:

Validates required fields
Injects version information
Generates production manifest

2. Resource Export

Automatically handles:

HTML entry files: Auto-injects necessary scripts and styles
Static assets: Copies public/ directory to output
Icon files: Processes icons declared in manifest

3. Development Mode Support

In development mode:

Automatic HMR (Hot Module Replacement) configuration
Generates development manifest
Seamless integration with Tuff main process

Configuration Options

import { defineConfig } from '@talex-touch/unplugin-export-plugin/types'

// Use defineConfig for type hints
export default defineConfig({
  // Project root directory
  root: process.cwd(),
  
  // manifest.json path (relative to project root)
  manifest: './manifest.json',
  
  // Output directory
  outDir: 'dist',
  
  // Source directory (for resource loading)
  sourceDir: 'src',
  
  // Widgets directory
  widgetsDir: 'widgets',
  
  // Public assets directory
  publicDir: 'public',
  
  // Index script directory (Prelude script)
  indexDir: 'index',
  
  // Generate source maps
  sourcemap: false,
  
  // Minify output
  minify: true,
  
  // External dependencies (not bundled)
  external: ['electron'],
  
  // Custom asset handling
  assets: {
    // Additional files/directories to copy (glob patterns)
    copy: ['./assets/**/*', './public/icons/*'],
    
    // Excluded files (glob patterns)
    exclude: ['**/*.test.ts', '**/*.spec.js']
  },
  
  // Version sync options
  versionSync: {
    // Enable syncing version from package.json to manifest.json
    enabled: true,
    
    // Auto sync without prompting
    auto: false
  },
  
  // Maximum plugin size (MB) before warning
  maxSizeMB: 10
})

Configuration Reference

Option	Type	Default	Description
`root`	`string`	`process.cwd()`	Project root directory
`manifest`	`string`	`'./manifest.json'`	manifest.json path
`outDir`	`string`	`'dist'`	Output directory
`sourceDir`	`string`	`'src'`	Source directory
`widgetsDir`	`string`	`'widgets'`	Widgets directory
`publicDir`	`string`	`'public'`	Public assets directory
`indexDir`	`string`	`'index'`	Prelude script directory
`sourcemap`	`boolean`	`false`	Generate source maps
`minify`	`boolean`	`true`	Minify output
`external`	`string[]`	`['electron']`	External dependencies
`assets.copy`	`string[]`	`undefined`	Additional files to copy
`assets.exclude`	`string[]`	`undefined`	Files to exclude
`versionSync.enabled`	`boolean`	`false`	Enable version sync
`versionSync.auto`	`boolean`	`false`	Auto sync version
`maxSizeMB`	`number`	`10`	Max plugin size warning threshold

Version Sync

When versionSync.enabled is true, the build process checks if package.json and manifest.json versions match:

Prompts user to sync when versions differ
Set versionSync.auto: true to auto-sync without confirmation
Can also trigger via --sync-version CLI flag

Size Warning

When the packaged .tpex file exceeds maxSizeMB (default 10MB), a warning is shown:

⚠ WARNING  Plugin size (12.34 MB) exceeds 10 MB limit!
  → Consider optimizing assets or splitting into smaller plugins
  → Large plugins may be rejected by the plugin store

Project Structure

Recommended plugin project structure:

my-plugin/
├── public/
│   └── icon.png           # Plugin icon
├── src/
│   ├── main.ts            # Entry file
│   ├── App.vue            # Main component
│   └── components/        # Components directory
├── index.html             # HTML entry
├── manifest.json          # Plugin manifest
├── vite.config.ts         # Vite config
├── package.json
└── tsconfig.json

Manifest Example

{
  "id": "com.example.my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "description": "A sample Tuff plugin",
  "author": "Your Name",
  "icon": "public/icon.png",
  "main": "index.html",
  "features": [
    {
      "id": "search",
      "name": "Search Feature",
      "description": "Quick search",
      "keywords": ["search", "find"],
      "icon": "ri:search-line"
    }
  ],
  "dev": {
    "enable": true,
    "port": 6001
  }
}

Development Mode

Enabling Development Mode

Configure in manifest.json:

{
  "dev": {
    "enable": true,
    "port": 6001
  }
}

Hot Reload

In development mode, these changes trigger hot reload:

Vue component changes
CSS/SCSS changes
JavaScript/TypeScript changes

manifest.json changes trigger plugin reload.

Debugging Tips

Open DevTools: Press Cmd+Option+I (Mac) or Ctrl+Shift+I (Windows) in plugin window
View logs: Main process logs output to terminal
Breakpoint debugging: Use Chrome DevTools to set breakpoints

Building for Production

pnpm build

Build output:

dist/
├── assets/
│   ├── index-[hash].js
│   └── index-[hash].css
├── index.html
├── manifest.json
└── icon.png

SDK Integration

After building, use the SDK from @talex-touch/utils:

// src/main.ts
import { useBox, useClipboard, usePluginStorage } from '@talex-touch/utils/plugin/sdk'

const box = useBox()
const clipboard = useClipboard()
const storage = usePluginStorage()

// Plugin logic...

FAQ

Q: Plugin won't load after build

Check if manifest.json id field follows format com.xxx.xxx
Ensure main field points to correct entry file
Check main process logs for detailed error messages

Q: Styles not working in dev mode

Ensure CSS preprocessor is configured correctly in vite.config.ts:

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        // SCSS config
      }
    }
  }
})

Q: Resource path errors

Use relative paths or @/ alias:

// vite.config.ts
import { resolve } from 'path'

export default defineConfig({
  resolve: {
    alias: {
      '@': resolve(__dirname, 'src')
    }
  }
})

Example Projects

Check official example plugins:

touch-image - Image processing plugin
touch-translation - Translation plugin
touch-music - Music player plugin