The use of file processing hooks

Usage of File Processing Hooks

Vite.js provides a rich set of hook functions, among which file processing hooks allow developers to intercept and modify file content during the build process. These hooks are particularly useful for handling special file formats, implementing custom transformation logic, or injecting code.

Basic Usage of the transform Hook

The transform hook is the most commonly used file processing hook. It takes the file content and file path as parameters and returns the modified content:

// vite.config.js  
export default {  
  plugins: [  
    {  
      name: 'my-transform-plugin',  
      transform(code, id) {  
        if (id.endsWith('.custom')) {  
          return `// Injected header comment\n${code}`  
        }  
      }  
    }  
  ]  
}  

This example demonstrates how to add a comment to files with the .custom extension. The id parameter contains the full file path, and code is the original file content.

Handling Specific File Types

Combining file extension filtering allows precise control over the hook's scope:

export default {  
  plugins: [  
    {  
      name: 'svg-transform',  
      transform(code, id) {  
        if (id.endsWith('.svg')) {  
          // Convert SVG to a component  
          return `export default \`${code}\``  
        }  
      }  
    }  
  ]  
}  

Asynchronous File Processing

When asynchronous operations are needed (e.g., calling an API or reading a file), transform can return a Promise:

export default {  
  plugins: [  
    {  
      name: 'async-transform',  
      async transform(code, id) {  
        if (id.includes('config.json')) {  
          const remoteData = await fetch('https://api.example.com/config')  
          return JSON.stringify({  
            ...JSON.parse(code),  
            ...await remoteData.json()  
          })  
        }  
      }  
    }  
  ]  
}  

Source Map Handling

Maintaining correct source maps during file processing is crucial for debugging:

export default {  
  plugins: [  
    {  
      name: 'transform-with-sourcemap',  
      transform(code, id) {  
        if (id.endsWith('.ts')) {  
          return {  
            code: code.replace(/console\.log\(.*\);/g, ''),  
            map: null // Preserve the original sourcemap  
          }  
        }  
      }  
    }  
  ]  
}  

Usage of the load Hook

The load hook is triggered when a file is read and can be used for virtual files or custom file loading:

export default {  
  plugins: [  
    {  
      name: 'virtual-module',  
      load(id) {  
        if (id === 'virtual:config') {  
          return `export const config = ${JSON.stringify({  
            version: '1.0.0',  
            env: process.env.NODE_ENV  
          })}`  
        }  
      }  
    }  
  ]  
}  

Modifying Existing File Content

Combining transform and load enables complex content modifications:

export default {  
  plugins: [  
    {  
      name: 'content-modifier',  
      transform(code, id) {  
        if (id.endsWith('.vue')) {  
          // Inject a mixin into Vue files  
          return code.replace(  
            '<script>',  
            '<script>\nimport validationMixin from "@/mixins/validation"'  
          )  
        }  
      }  
    }  
  ]  
}  

Handling CSS Files

Vite allows custom CSS processing through hooks:

export default {  
  plugins: [  
    {  
      name: 'css-modifier',  
      transform(code, id) {  
        if (id.endsWith('.css')) {  
          // Add a prefix to all CSS rules  
          return code.replace(  
            /([^{]+\{)/g,  
            '[data-theme="dark"] $1'  
          )  
        }  
      }  
    }  
  ]  
}  

Build Phase Hooks

In addition to transforming content, build phase hooks can be used to handle files:

export default {  
  plugins: [  
    {  
      name: 'build-optimizer',  
      buildStart() {  
        console.log('Build started')  
      },  
      buildEnd() {  
        console.log('Build completed')  
      },  
      generateBundle(options, bundle) {  
        // Modify the final generated bundle  
        for (const fileName in bundle) {  
          if (fileName.endsWith('.js')) {  
            const chunk = bundle[fileName]  
            chunk.code = `/* Build time: ${new Date().toISOString()} */\n${chunk.code}`  
          }  
        }  
      }  
    }  
  ]  
}  

Practical Application Example

Implementing a plugin for automatic internationalization injection:

export default {  
  plugins: [  
    {  
      name: 'i18n-injector',  
      async transform(code, id) {  
        if (id.endsWith('.vue') || id.endsWith('.jsx')) {  
          const i18nKeys = extractText(code) // Extract text requiring internationalization  
          const translations = await loadTranslations(i18nKeys)  
          
          return code.replace(  
            /(['"`])(.*?)\1/g,  
            (match, quote, text) => {  
              return translations[text]  
                ? `$t('${translations[text]}')`  
                : match  
            }  
          )  
        }  
      }  
    }  
  ]  
}  

function extractText(code) {  
  // Implement text extraction logic  
  return [...new Set(code.match(/['"`](.*?)['"`]/g).map(m => m.slice(1, -1))]  
}  

async function loadTranslations(keys) {  
  // Implement translation loading logic  
  const res = await fetch('/api/translate', {  
    method: 'POST',  
    body: JSON.stringify(keys)  
  })  
  return res.json()  
}  

Performance Optimization Considerations

Frequent file processing can impact build speed, so caching can be used for optimization:

const cache = new Map()  

export default {  
  plugins: [  
    {  
      name: 'cached-transform',  
      transform(code, id) {  
        if (!id.endsWith('.md')) return  
        
        const cacheKey = createHash(code)  
        if (cache.has(cacheKey)) {  
          return cache.get(cacheKey)  
        }  
        
        const result = markdownToHtml(code)  
        cache.set(cacheKey, result)  
        return result  
      }  
    }  
  ]  
}  

Error Handling Mechanism

Robust file processing plugins should include error handling:

export default {  
  plugins: [  
    {  
      name: 'error-handling-transform',  
      transform(code, id) {  
        try {  
          if (id.endsWith('.critical')) {  
            return processCritical(code)  
          }  
        } catch (err) {  
          this.error(`Error processing file ${id}: ${err.message}`)  
          // Alternatively, return the original content to ensure the build continues  
          return code  
        }  
      }  
    }  
  ]  
}  

Interacting with Other Plugins

The this context provides access to methods of other plugins:

export default {  
  plugins: [  
    {  
      name: 'plugin-communicator',  
      async buildStart() {  
        // Wait for another plugin to initialize  
        await this.resolve('vite:vue')  
      },  
      transform(code, id) {  
        // Check if the file has been processed by another plugin  
        const meta = this.getModuleInfo(id)  
        if (meta?.importers) {  
          // Adjust content based on import relationships  
        }  
      }  
    }  
  ]  
}  

Advanced File Processing Patterns

For complex scenarios requiring multi-step processing, multiple hooks can be combined:

export default {  
  plugins: [  
    {  
      name: 'multi-stage-processor',  
      // Phase 1: Mark files requiring processing  
      transform(code, id) {  
        if (shouldProcess(id)) {  
          return `// PROCESS-MARKER\n${code}`  
        }  
      },  
      // Phase 2: Process marked files  
      transform(code, id) {  
        if (code.includes('// PROCESS-MARKER')) {  
          return processMarkedFiles(code.replace('// PROCESS-MARKER\n', ''))  
        }  
      }  
    }  
  ]  
}