Coralite v0.19.0

I am excited to announce Coralite v0.19.0, a major release focused on improving the script system architecture and developer experience. This update includes 157 commits and 24 pull requests, bringing significant enhancements to type safety, validation, and workflow efficiency.

Breaking Change: Script Function Signature #

The most significant change in v0.19.0 is the refactored script function signature. This is a breaking change that requires updating existing template scripts.

Migration Guide #

Before v0.19.0:


import { defineComponent } from 'coralite'

export default defineComponent({
  tokens: {
    greeting: ({ name }) => `Hello, ${name}!`
  },
  script: function(context) {
    // refs was part of the context object
    const refs = context.refs
    const button = refs('actionBtn')
    
    button.addEventListener('click', () => {
      console.log('Clicked!')
    })
  }
})

After v0.19.0:


import { defineComponent } from 'coralite'

export default defineComponent({
  tokens: {
    greeting: ({ name }) => `Hello, ${name}!`
  },
  script: function(context, helpers) {
    // refs is now in the helpers parameter
    const refs = helpers.refs
    const button = refs('actionBtn')
    
    button.addEventListener('click', () => {
      console.log('Clicked!')
    })
  }
})

What Changed #

context parameter now only contains instance data (values, etc.)
helpers parameter contains helper functions like refs()
This separation improves code organization and extensibility

New Type Guard Utilities #

v0.19.0 introduces comprehensive type guard functions for validating Coralite nodes and elements. These utilities enhance type safety and make error handling more robust.


import { 
  isCoraliteNode,
  isCoraliteElement,
  isCoraliteTextNode,
  isCoraliteComment,
  isCoraliteCollectionItem,
  isCoraliteDocumentRoot,
  isCoraliteSlotElement
} from 'coralite'

// Validate before processing
if (isCoraliteNode(element)) {
  // Safe to work with Coralite node
  console.log('Valid Coralite node')
}

// Check collection items
if (isCoraliteCollectionItem(item)) {
  // Safe to access collection properties
  console.log('Valid collection item')
}

// Validate slot elements
if (isCoraliteSlotElement(slot)) {
  // Safe slot operations
  console.log('Valid slot element')
}

Script Helper System #

Plugins can now provide script helpers using a factory pattern:


const myScriptPlugin = createPlugin({
  name: 'script-enhancer',
  script: {
    setup: (plugin) => {
      console.log('Plugin registered:', plugin.name)
    },
    helpers: {
      formatDate: (context) => {
        // Factory receives context, returns helper function
        return (date) => new Date(date).toLocaleDateString()
      }
    }
  }
})

Additional Features & Fixes #

Script Content Support: Added __script__ property to module values for better script handling
File Exclusion: Improved hidden file and exclusion handling in HTML parsing
Performance: Per-document compilation tracking for better build insights
Collection Validation: Enhanced validation for collection items and deduplication
Config Validation: Added validation to defineConfig function

How to Upgrade #

Update your project with one of the following commands:

npm install coralite@0.19.0

Or if you're using the scaffolding tool:

npm install coralite-scripts@0.19.0

Get the Release #

For detailed information on all changes, refer to the full changelog on Codeberg.

Upgrade today to take advantage of the improved script system, enhanced type safety, and better developer experience in Coralite v0.19.0!

Coralite v0.18.7 Release Notes - 18 Oct 25
Coralite v0.18.6 Release Notes - 24 Sept 25