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.22.0 Released: Scoped Styles & Concurrent Rendering - 18 Feb 26
Coralite v0.20 Released: Major Performance Boost & New APIs - 9 Feb 26
Coralite v0.19.0 Released: Script System Refactor - 1 Jan 26