Authoring Pattern

Coralite enforces a single, predictable authoring pattern across every layer of the application. Components and pages are authored with flat named exports, while plugins use the definePlugin default export imported from coralite.

Components and pages share the same flat named-export vocabulary; plugins use definePlugin. All three layers share the same blocks and static validation model. defineComponent and definePage wrappers remain supported for legacy code.

  import { definePlugin } from 'coralite'
  
  // Component or page: flat named exports
  export function server (context) { /* ... */ }
  export const getters = { /* ... */ }
  export function client (context) { /* ... */ }
  
  // Plugin: default export
  export default definePlugin({ /* plugin blocks */ })

Each block serves a clear, specific role during build-time rendering, runtime reactivity, or lifecycle execution.

The component attributes block describes inputs supplied by a host element. Pages have no host element, so their equivalent surface is meta: arbitrary key/value page information using the same schema syntax (type, default, values, validate). meta defaults seed page state, and missing keys fall back into page.meta after literal <title>/<meta> tags are extracted. required is rejected on pages because there is no external input.

Meta keys are used verbatim in state and page.meta; only identifier-safe keys are directly usable in templates, so use a getter for names such as og:title. page and route defaults remain available in page.meta but do not override the page object or active route. server() return values update state only; mutate page.meta directly to change document metadata.

Block functions receive a single destructured context object containing framework utilities, state references, and route metadata.

Coralite templates use flat interpolations exclusively. To keep templates fast, deterministic, and statically indexable, templates forbid expressions, function calls, inline event handlers (such as onclick="..."), conditionals, and loops. All derivation logic must live inside getters.

  <h2></h2>
  <button ref="submitBtn">Submit</button>
  
  &lt;script type="module">
    import { defineComponent } from 'coralite'
  
    export default defineComponent({
      getters: {
        fullName: ({ state }) => `${state.firstName} ${state.lastName}`
      },
      client ({ refs, signal, state }) {
        refs('submitBtn').addEventListener('click', () => {
          state.submitted = true
        }, { signal })
      }
    })
  &lt;/script&gt;

  <h2>{{ user.firstName + &apos; &apos; + user.lastName }}</h2>
  <button onclick="handleSubmit()">Submit</button>

Top-level imports are reserved for definePlugin, page configuration modules, and ESM modules used by isomorphic blocks (such as getters, style, or slots). Node-only dependencies used strictly in server() or paths(), and browser-only dependencies used in client(), must be imported dynamically using await import(...) inside the respective block.

  export async function server () {
    // Correct: Node module loaded inside server()
    const fs = await import('node:fs/promises')
    const data = await fs.readFile('data.json', 'utf8')
    return { content: JSON.parse(data) }
  }
  
  export async function client () {
    // Correct: Browser module loaded inside client()
    const { animate } = await import('https://esm.sh/motion')
    animate('.card', { opacity: 1 })
  }

  // Bad: Importing Node/Browser modules at top-level pollutes bundle scope
  import fs from 'node:fs/promises'
  import { animate } from 'motion'

Coralite draws a strict boundary between build-time server execution and browser client runtime execution. The server() function runs in Node.js during build/SSG and its return value is serialized to JSON. The client() function runs in the browser and cannot close over outer module scope variables populated during server() execution.

  import { defineComponent } from 'coralite'
  
  export default defineComponent({
    // 1. Runs at build-time in Node.js
    server () {
      return {
        serverTime: new Date().toISOString()
      }
    },
    // 2. Runs in the browser runtime; receives serialized state
    client ({ state }) {
      console.log('Server rendered at:', state.serverTime)
    }
  })

Coralite guarantees that all context parameters destructured in block function signatures exist. Authors must not write defensive guards (such as if (!lists) return or if (state == null) return) against destructured context keys or guaranteed framework properties.

  import { defineComponent } from 'coralite'
  
  export default defineComponent({
    // Correct: Destructure directly without defensive checks
    client ({ state, refs, signal }) {
      const btn = refs('button')
      btn.addEventListener('click', () => {
        state.count++
      }, { signal })
    }
  })

Next: Explore Getting Started to build your first Coralite component and page.