feat: AST-based compiler macro system for extendComponentMeta

[hendrikheil]

Summary

• Replaces the fragile regex+eval hack for extendComponentMeta with proper AST-based parsing via oxc-parser + oxc-walker
• Adds extendMetaFunctions module option to register named compiler macros, each with an optional transform hook
• Macro calls are stripped from browser output by the Vite plugin (true zero-runtime compiler macros)
• Custom macro names get auto-generated declare function type declarations

New API

// nuxt.config.ts
componentMeta: {
  extendMetaFunctions: [
    { name: 'extendComponentMeta' },
    { name: 'extendProps', transform: (extracted) => ({ _studio: extracted }) }
  ]
}

<!-- In a component -->
<script setup>
extendProps({ filePath: 'file-picker' })
</script>

Produces component.meta._studio = { filePath: 'file-picker' } — with no runtime cost.

Changes

• src/parser/macro-extractor.ts — new file: extractMacroMeta() and stripMacroCalls() using oxc AST
• src/types/module.ts — new ExtendMetaFunction interface, extendMetaFunctions option
• src/parser/meta-parser.ts — replaces regex+eval with extractMacroMeta
• src/utils/unplugin.ts — adds Vite transform hook to strip macro calls
• src/module.ts — wires defaults, generates type declarations for custom macro names
• src/parser/index.ts — adds extendMetaFunctions support to standalone parser

Test plan

• Existing extendComponentMeta test passes (backward compatible)
• New extendProps with transform test passes (meta._studio.filePath === 'file-picker')
• Verify macro calls are absent from browser bundle output

🤖 Generated with Claude Code

[pkg-pr-new]

npm i https://pkg.pr.new/nuxt-component-meta@116

commit: 05f350d

[farnabaz]

When I test the code in playground I got this error:

Cannot find package 'velocityjs' imported from /Users/.../projects/nuxt/nuxt-component-meta/playground/.nuxt/dev/index.mjs

Which comes from '@vue/compiler-sfc'. Since we are using scf compiler just to get the <script> tag content here, I believe using regex will be safe and faster and reduce dependencies.

I'll give it a try

[farnabaz]

Tried it — regex extraction works and drops @vue/compiler-sfc entirely. Benchmarks:

	before (sfc)	after (regex)	speedup
script extraction	~0.0009 ms	~0.0001 ms	8.7×
full pipeline (literal arg)	0.636 ms	0.556 ms	1.14×

End-to-end gain is modest (pipeline is dominated by jiti.evalModule), but the crash is gone and we shed a dependency. Only caveat: the regex won't handle a </script> inside a string/comment like the full parser would — a non-issue for top-level macro statements.

Benchmarks added under test/*.bench.ts (pnpm test:bench).

[hendrikheil]

I originally went with compiler-sfc to stay within ecosystem tooling to ensure we're as compatible as possible.

I think since the performance improvement is modest, we should maybe try to fix the issue you encountered in the playground instead of switching to the regex?

[hendrikheil]

@farnabaz I looked into your issue and I think we could easily just solve this by adding @vue/compiler-sfc to externals.
This will emit some warnings still, but not cause any errors now.

These warnings are unlikely to be avoidable unless we explicitly suppress them as the playground imports our usually build-time only code at runtime (

nuxt-component-meta/playground/server/api/validate.post.ts

Line 3 in 3c684bd

import { getComponentMeta } from "../../../src/parser"

).

I'd argue that switching back and accepting the warnings is a better approach?

[farnabaz]

@hendrikheil Sorry for the late response
I understand your argument, but we only need the text inside <script> tag, using whole SFC parser to get string content is not ideal IMO.

Have you tested the current state of PR, is there some issues in the behavior?