The processing mechanism of custom blocks

The Concept and Role of Custom Blocks

In Vue 3, custom blocks are sections in Single File Components (SFCs) other than <template>, <script>, and <style>. They allow developers to extend SFC functionality by adding project-specific metadata or configurations. For example:

<template>
  <div>...</div>
</template>

<script>
export default {...}
</script>

<custom-block>
  {
    "featureFlags": ["new-checkout-flow"],
    "analyticsId": "UA-123456"
  }
</custom-block>

Custom blocks do not directly affect component behavior but can be processed by build tools or plugins. Common use cases include:

• Documentation generation (<docs>)
• Test cases (<test>)
• Internationalization configurations (<i18n>)
• Server-side rendering directives (<server>)

Processing During the Parsing Stage

The Vue 3 compiler processes custom blocks during SFC parsing via the parse method in the @vue/compiler-sfc package. The parser collects all non-standard blocks into the descriptor.customBlocks array:

interface SFCDescriptor {
  customBlocks: Array<{
    type: string
    content: string
    attrs: Record<string, string>
    loc: SourceLocation
  }>
}

Example parsing result:

{
  customBlocks: [
    {
      type: 'custom-block',
      content: '{\n  "featureFlags": ["new-checkout-flow"]\n}',
      attrs: {},
      loc: {...}
    }
  ]
}

Compilation-Time Processing Mechanism

Custom blocks are primarily processed during the transform phase of compiler-sfc. The core workflow includes:

1. Block Type Identification: Matching block names (e.g., <docs>) with corresponding processors.
2. Content Transformation: Converting raw content into a consumable format.
3. Metadata Injection: Attaching processed results to component options.

A typical processor structure:

function customBlockTransformer(block, ctx) {
  // Parse block content
  const parsed = JSON.parse(block.content)
  
  // Return transformation result
  return {
    code: `export default ${JSON.stringify(parsed)}`,
    map: null
  }
}

Build Tool Integration

Handling in Vite

In Vite, custom blocks are processed via plugins. Example configuration:

// vite.config.js
export default {
  plugins: [
    {
      name: 'custom-block-plugin',
      transform(code, id) {
        if (!id.endsWith('.vue')) return
        
        const blocks = parseVue(code).customBlocks
        blocks.forEach(block => {
          if (block.type === 'feature-flags') {
            // Processing logic
          }
        })
      }
    }
  ]
}

Handling in Webpack

Using the customBlocks option in vue-loader:

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.vue$/,
        loader: 'vue-loader',
        options: {
          customBlocks: {
            'custom-block'(block) {
              // Return processing result
              return {
                code: `export default ${block.content}`,
                map: null
              }
            }
          }
        }
      }
    ]
  }
}

Runtime Access Mechanism

Processed custom block content can be accessed via the component instance. Assuming a <feature-flags> block is processed:

// Processor output
export default {
  flags: ['new-checkout-flow']
}

// Usage in component
import featureFlags from './component.vue?vue&type=feature-flags&index=0'

export default {
  created() {
    console.log(featureFlags.flags) // ['new-checkout-flow']
  }
}

Advanced Application Scenarios

Multi-Block Merging

When multiple blocks of the same type exist, they can be merged:

<feature-flag name="checkout-v2"/>
<feature-flag name="new-dashboard"/>

Processor implementation:

function featureFlagTransformer(blocks, ctx) {
  const flags = blocks.map(block => block.attrs.name)
  return {
    code: `export default ${JSON.stringify({ flags })}`,
    map: null
  }
}

Inter-Block Dependencies

Custom blocks can reference content from other blocks:

<config>
export const API_URL = 'https://api.example.com'
</config>

<feature-flags>
import { API_URL } from './config'
export default {
  fetchFlags() {
    return fetch(`${API_URL}/flags`)
  }
}
</feature-flags>

Performance Optimization Strategies

1. Caching Results: Hash caching for blocks with identical content.
2. Lazy Processing: Process documentation blocks only in development.
3. Parallel Processing: Use worker threads for CPU-intensive transformations.

Example caching implementation:

const blockCache = new Map()

function processBlock(block) {
  const cacheKey = `${block.type}-${hash(block.content)}`
  if (blockCache.has(cacheKey)) {
    return blockCache.get(cacheKey)
  }
  
  const result = transform(block)
  blockCache.set(cacheKey, result)
  return result
}

Error Handling and Validation

Custom blocks should include robust error handling:

function validateJsonBlock(block) {
  try {
    JSON.parse(block.content)
  } catch (e) {
    throw new Error(
      `Invalid JSON in ${block.type} block at ${block.loc.start.line}:${block.loc.start.column}`
    )
  }
}

Custom Blocks and TypeScript

Providing type support for custom block content:

// types/custom-blocks.d.ts
declare module '*.vue' {
  import { DefineComponent } from 'vue'
  const component: DefineComponent & {
    __featureFlags?: { flags: string[] }
  }
  export default component
}

Processors should generate type declarations:

function generateTypes(block) {
  return `
    declare module '${block.src}' {
      export const flags: ${JSON.stringify(block.content.flags)}
    }
  `
}

Plugin System Extension

Basic structure for developing custom block plugins:

interface CustomBlockPlugin {
  name: string
  blockType: string | RegExp
  transform: (block: SFCBlock, ctx: TransformContext) => TransformResult
  handleHotUpdate?: (ctx: HmrContext) => void
}

export function createCustomBlockPlugin(options: CustomBlockPlugin): Plugin {
  return {
    name: options.name,
    transform(code, id) {
      // Implement transformation logic
    }
  }
}

Integration with Composition API

Consuming custom block data in the Composition API:

<script setup>
import featureFlags from './component.vue?feature-flags'

useFeatureFlags(featureFlags)
</script>

The corresponding processor should generate ES modules:

function compositionAwareTransformer(block) {
  return {
    code: `export default ${JSON.stringify(block.content)}`,
    map: null
  }
}

Special Handling for Server-Side Rendering

For SSR, distinguish between client and server blocks:

<server-only>
// Database query logic
export const fetchData = () => db.query(...)
</server-only>

<client-only>
// Browser API access
export const track = () => window.analytics.track(...)
</client-only>

Build configuration must differentiate environments:

if (process.env.SSR) {
  config.plugins.push(serverBlockPlugin)
} else {
  config.plugins.push(clientBlockPlugin)
}

Testing Strategies

Key points for writing tests for custom block processors:

import { parse, transform } from '@vue/compiler-sfc'

test('feature flag block transformation', () => {
  const { descriptor } = parse(`
    <feature-flags>["new-ui"]</feature-flags>
  `)
  
  const result = transform(descriptor.customBlocks[0], {
    // Context configuration
  })
  
  expect(result.code).toMatch('export default ["new-ui"]')
})

Debugging Techniques

Debugging custom block processing during development:

1. Launch the build tool with the --inspect-brk parameter.
2. Add debug logs in processors:

function debugTransformer(block) {
  console.log({
    type: block.type,
    content: block.content,
    attrs: block.attrs
  })
  // ...Normal processing logic
}

3. Generate sourcemaps for accurate mapping:

return {
  code: transformedCode,
  map: generateSourceMap(original, transformed)
}