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 with three sections.

import { parseSFC } from 'nexa-compiler'

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

function parseSFC(source: string): SFCDescriptor

Example:

const descriptor = parseSFC(source)

if (descriptor.template) {
  console.log(descriptor.template.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 an SFC descriptor.

import { generateComponentCode } from 'nexa-compiler'

interface GeneratedCode {
  code: string
  map: SourceMap | null
}

function generateComponentCode(
  descriptor: SFCDescriptor,
  options?: CompileOptions
): GeneratedCode

Options:

interface CompileOptions {
  filename?: string
  sourceMap?: boolean
  scopeId?: string
}

transformTemplate

Transforms a template AST — rewrites directives, injects scoped style IDs, and optimizes static nodes.

import { transformTemplate } from 'nexa-compiler'

function transformTemplate(
  ast: TemplateAST,
  options?: { scopeId?: string }
): TemplateAST

transformStyle

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

import { transformStyle } from 'nexa-compiler'

function transformStyle(
  style: { content: string; scoped: boolean },
  scopeId: string
): string

Returns the processed CSS string with scoped selectors when applicable.

Compilation Pipeline Example

import { parseSFC, parseTemplate, transformTemplate, 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. Transform template
if (descriptor.template?.ast) {
  const transformed = transformTemplate(descriptor.template.ast, {
    scopeId: 'data-v-abc123',
  })
  descriptor.template.ast = transformed
}

// 3. Generate code
const { code } = generateComponentCode(descriptor, {
  filename: 'App.nexa',
  scopeId: 'data-v-abc123',
})