nexa-compiler

The compiler transforms .nexa Single-File Components into executable JavaScript. It parses the source, transforms the template AST, and generates render functions.

parseSFC

Parses a .nexa file source into an SFC descriptor.

import { parseSFC } from 'nexa-compiler'

interface SFCDescriptor {
  template: {
    content: string
    ast: TemplateAST | null
  } | null
  script: {
    content: string
    lang: string
    setup: boolean
  } | null
  styles: {
    content: string
    scoped: boolean
    lang: string
  }[]
}

function parseSFC(source: string): SFCDescriptor

Note: The styles field is an array (not singular style). Access the first style block with sfc.styles[0].

Example:

const descriptor = parseSFC(source)

if (descriptor.template) {
  console.log(descriptor.template.content)
}
if (descriptor.styles.length > 0) {
  console.log(descriptor.styles[0].content)
}

parseTemplate

Parses an HTML template string into a structured AST.

import { parseTemplate } from 'nexa-compiler'

type TemplateAST = {
  tag: string
  attrs: Record<string, string>
  children: TemplateAST[]
  directives: Directive[]
}

function parseTemplate(template: string): TemplateAST

AST Property	Description
tag	HTML tag name
attrs	Attribute key-value pairs
children	Nested child AST nodes
directives	Parsed directives (v-if, v-for, v-model, etc.)

generateComponentCode

Generates JavaScript source code from SFC sections.

import { generateComponentCode } from 'nexa-compiler'

function generateComponentCode(sfc: {
  template: string | null
  script: string | null
  style: string | null
  setup?: boolean
  scoped: boolean
  hmrId?: string
}): string

Returns the generated JavaScript as a string (not an object with code and map). For source map support, use generateComponentCodeWithSourceMap.

generateComponentCodeWithSourceMap

Generates component code with optional source map support:

import { generateComponentCodeWithSourceMap } from 'nexa-compiler'

function generateComponentCodeWithSourceMap(
  sfc: {
    template: string | null
    script: string | null
    style: string | null
    scoped: boolean
    hmrId?: string
  },
  options?: {
    filename?: string
    sourceMap?: boolean
    source?: string
  }
): { code: string; map: string | null }

transformStyle

Processes style content — scopes CSS rules with a scope ID when scoped: true.

import { transformStyle } from 'nexa-compiler'

Returns an object with scopeId and styleCode.

Security Considerations

The compiler generates JavaScript from template expressions. Expressions in v-if, v-for, interpolations, and :bind attributes are inserted directly into the generated code.

CAUTION

.nexa files must be treated as source code, not user-generated content. Never compile templates from untrusted sources (user input, database content, etc.) as this would allow arbitrary code execution.

Compilation Pipeline Example

import { parseSFC, generateComponentCode } from 'nexa-compiler'

const source = `
<template>
  <div class="app">{{ msg }}</div>
</template>

<script setup>
import { signal } from 'nexa-framework'
const msg = signal('Hello')
</script>

<style scoped>
.app { color: blue; }
</style>
`

// 1. Parse
const descriptor = parseSFC(source)

// 2. Generate code
const code = generateComponentCode({
  template: descriptor.template?.content ?? null,
  script: descriptor.script?.content ?? null,
  style: descriptor.styles[0]?.content ?? null,
  setup: descriptor.script?.setup ?? false,
  scoped: descriptor.styles[0]?.scoped ?? false,
})