Coralite Scripts

coralite-scripts is the official development and build tool for Coralite projects. It provides a complete development environment with live reloading, hot CSS updates, and a production build system optimized for static site generation.

Table of Contents #

• Overview
• Installation & Setup
• Configuration Reference
• CLI Commands
• Development Server Features
• Build Process
• API Reference
• Examples
• Troubleshooting

Overview #

coralite-scripts provides two main modes of operation:

Key Features #

• Live Reload - Automatic browser refresh on HTML, template, and asset changes
• Hot CSS Updates - Instant CSS injection without page refresh via Server-Sent Events
• Sass/SCSS Support - Compile Sass files with source maps and auto-prefixing
• File Watching - Monitors all source directories for changes
• Production Optimization - Clean builds with optimized output
• Plugin Integration - Full support for Coralite plugins

Installation & Setup #

Install coralite-scripts as a dev dependency in your Coralite project:

  npm install --save-dev coralite-scripts

Project Structure #

Ensure your project follows the standard Coralite structure:

  my-coralite-site/
  ├── src/
  │   ├── pages/        # Page templates (.html)
  │   ├── templates/    # Reusable components
  │   └── scss/         # Sass/SCSS files
  ├── public/           # Static assets
  ├── coralite.config.js # Configuration file
  └── package.json      # Scripts & dependencies

package.json Scripts #

Add the following scripts to your package.json:

  {
    "scripts": {
      "dev": "coralite-scripts dev",
      "build": "coralite-scripts build",
      "start": "coralite-scripts dev"
    }
  }

Configuration File #

Create coralite.config.js in your project root:

  import { defineConfig } from 'coralite-scripts'
  
  export default defineConfig({
    output: './dist',
    public: './public',
    pages: './src/pages',
    templates: './src/templates',
    styles: {
      type: 'scss',
      input: './src/scss'
    },
    server: {
      port: 3000
    }
  })

Configuration Reference #

The defineConfig() function validates and returns your configuration object. All properties are required unless marked as optional.

Required Properties #

Optional Properties #

Configuration Validation #

The defineConfig() function performs validation and will throw errors for:

• Missing required properties
• Invalid property types
• Invalid style types (must be 'css', 'sass', or 'scss')
• Invalid server port numbers

CLI Commands #

coralite-scripts provides two main commands for development and production builds.

Development Server #

Start the development server with live reload and hot CSS updates:

  npm run dev
  # or
  coralite-scripts dev

Options

• -v, --verbose - Enable verbose logging output

What It Does

1. Initializes Coralite with your configuration
2. Compiles Sass/SCSS if configured
3. Starts Express server on configured port
4. Watches for file changes in pages, templates, and styles directories
5. Injects live reload scripts into HTML pages
6. Serves static assets from public directory

Production Build #

Build your site for production deployment:

  npm run build
  # or
  coralite-scripts build

What It Does

1. Cleans the output directory
2. Compiles all pages with Coralite
3. Saves rendered HTML to output directory
4. Copies static assets from public directory
5. Compiles Sass/SCSS to CSS with source maps
6. Optimizes output for production

Development Server Features #

Live Reload #

Automatic browser refresh when files change:

• HTML Pages - Changes to .html files in pages directory
• Templates - Changes to template components
• Static Assets - Changes in public directory

Hot CSS Updates #

Instant CSS injection without page refresh:

• Sass/SCSS files are compiled automatically
• CSS is injected via Server-Sent Events (SSE)
• Page maintains current scroll position and state
• Works with multiple browser tabs simultaneously

File Watching #

Monitors the following directories for changes:

• config.pages - Page templates
• config.templates - Reusable components
• config.public - Static assets
• config.styles.input - Sass/SCSS files

Request Logging #

Real-time terminal output showing:

• Request method and path
• HTTP status code
• Response time in milliseconds
• Compilation time for dynamic pages

Server-Sent Events (SSE) #

The development server provides a /_/rebuild endpoint that clients can connect to for real-time updates. The server sends two types of messages:

• data: connected - Initial connection confirmation
• data: reload - Trigger page reload

Build Process #

The production build process is optimized for performance and clean output.

Build Steps #

1. Clean Output - Deletes existing output directory
2. Compile HTML - Processes all pages with Coralite
3. Save Documents - Writes rendered HTML to disk
4. Copy Assets - Copies static files from public directory
5. Compile Styles - Processes Sass/SCSS or CSS
6. Generate Source Maps - Creates .map files for debugging

Sass Compilation #

When styles.type is set to 'sass' or 'scss':

• Compiles all .scss files (excluding partials starting with _)
• Outputs to output/css/ directory
• Generates source maps by default
• Includes node_modules in Sass load paths
• Suppresses common deprecation warnings

CSS Processing #

When styles.type is set to 'css':

• Processes CSS files through PostCSS
• Supports custom PostCSS plugins via cssPlugins
• Outputs to output/css/ directory

API Reference #

defineConfig(options) #

Defines and validates the Coralite configuration for your project.

  import { defineConfig } from 'coralite-scripts'
  
  const config = defineConfig({
    output: './dist',
    public: './public',
    pages: './src/pages',
    templates: './src/templates',
    styles: {
      type: 'scss',
      input: './src/scss'
    },
    server: {
      port: 3000
    },
    // Coralite plugins
    plugins: [
      // Your plugin instances
    ],
    // Sass options
    sassOptions: {
      // Custom Sass compiler options
    },
    // PostCSS plugins
    cssPlugins: [
      // Your PostCSS plugins
    ]
  })

Parameters

Returns

CoraliteScriptConfig - The validated configuration object

Throws

• Error - If configuration is not a valid object
• Error - If required properties are missing or invalid
• Error - If optional properties have invalid types or values

Validation Rules #

Examples #

Basic Setup #

Minimal configuration for a standard Coralite site:

  import { defineConfig } from 'coralite-scripts'
  
  export default defineConfig({
    output: './dist',
    public: './public',
    pages: './src/pages',
    templates: './src/templates'
  })

Sass/SCSS Support #

Configure Sass compilation with custom options:

  import { defineConfig } from 'coralite-scripts'
  
  export default defineConfig({
    output: './dist',
    public: './public',
    pages: './src/pages',
    templates: './src/templates',
    styles: {
      type: 'scss',
      input: './src/scss'
    },
    sassOptions: {
      sourceMap: true,
      loadPaths: ['node_modules', 'src/scss'],
      silenceDeprecations: ['color-functions', 'import']
    }
  })

With Coralite Plugins #

Integrate Coralite plugins with coralite-scripts:

  import { defineConfig } from 'coralite-scripts'
  import { defineComponent } from 'coralite/plugins'
  
  export default defineConfig({
    output: './dist',
    public: './public',
    pages: './src/pages',
    templates: './src/templates',
    styles: {
      type: 'scss',
      input: './src/scss'
    },
    plugins: [
      defineComponent({
        // Your component definition
      })
    ]
  })

PostCSS Integration #

Use PostCSS plugins for CSS processing:

  import { defineConfig } from 'coralite-scripts'
  import autoprefixer from 'autoprefixer'
  import cssnano from 'cssnano'
  
  export default defineConfig({
    output: './dist',
    public: './public',
    pages: './src/pages',
    templates: './src/templates',
    styles: {
      type: 'css',
      input: './src/css'
    },
    cssPlugins: [
      autoprefixer(),
      cssnano()
    ]
  })

Custom Development Port #

Configure a custom port for the development server:

  import { defineConfig } from 'coralite-scripts'
  
  export default defineConfig({
    output: './dist',
    public: './public',
    pages: './src/pages',
    templates: './src/templates',
    server: {
      port: 8080
    }
  })

Complete Configuration #

Full-featured configuration with all options:

  import { defineConfig } from 'coralite-scripts'
  import { defineComponent, defineCollection } from 'coralite/plugins'
  import autoprefixer from 'autoprefixer'
  
  export default defineConfig({
    // Required paths
    output: './dist',
    public: './public',
    pages: './src/pages',
    templates: './src/templates',
    
    // Style processing
    styles: {
      type: 'scss',
      input: './src/scss'
    },
    
    // Sass options
    sassOptions: {
      sourceMap: true,
      loadPaths: ['node_modules'],
      silenceDeprecations: ['import']
    },
    
    // PostCSS plugins
    cssPlugins: [
      autoprefixer()
    ],
    
    // Development server
    server: {
      port: 3000
    },
    
    // Coralite plugins
    plugins: [
      defineComponent({
        // Component definitions
      }),
      defineCollection({
        // Collection definitions
      })
    ]
  })

Troubleshooting #

Development Server Issues #

Server won't start

Problem: Port already in use

Solution: Change the port in your config or kill the process using the port:

  lsof -i :3000
  kill -9 [PID]

Live reload not working

Problem: Browser not receiving SSE messages

Solutions:

• Check browser console for connection errors
• Verify file watching is working (check terminal logs)
• Ensure no browser extensions are blocking SSE
• Try a hard refresh (Ctrl+Shift+R)

Hot CSS not updating

Problem: CSS changes not reflected without page reload

Solutions:

• Check that Sass compilation is working (look for compilation logs)
• Verify CSS files are being served from /css route
• Check browser network tab for CSS requests
• Ensure styles are imported in HTML with correct path

Build Issues #

Build fails with errors

Problem: Compilation errors during build

Solutions:

• Check that all required directories exist
• Verify template files are valid HTML
• Check for syntax errors in Sass/SCSS files
• Ensure all Coralite plugins are properly configured

Output directory not created

Problem: Build completes but no output

Solutions:

• Check that output path is valid
• Verify write permissions in output directory
• Look for errors in build logs

Configuration Issues #

Config validation errors

Problem: defineConfig() throws validation errors

Solutions:

• Ensure all required properties are present
• Check property types match expected types
• Verify style type is one of: 'css', 'sass', 'scss'
• Ensure server.port is a positive number

Plugins not loading

Problem: Coralite plugins not recognized

Solutions:

• Verify plugins are imported correctly
• Check that plugins are passed to defineConfig()
• Ensure plugins are compatible with your Coralite version

Performance Issues #

Slow compilation times

Problem: Long wait times for changes to reflect

Solutions:

• Reduce number of files being watched
• Optimize Sass compilation with silenceDeprecations
• Use partials (_ prefix) for Sass files not needed in output
• Consider splitting large Sass files

High memory usage

Problem: Development server consuming too much memory

Solutions:

• Restart development server periodically
• Reduce number of files in watched directories
• Check for memory leaks in custom plugins

Common Error Messages #

  Error: Configuration must be a valid object
  → Ensure you're passing an object to defineConfig()
  
  Error: Configuration must contain a valid "output" property
  → Add the required 'output' property to your config
  
  Error: Configuration "server.port" must be a positive number
  → Check that server.port is a number greater than 0
  
  Error: Configuration "styles.type" must be equal to either "css", "sass" or "scss"
  → Use one of the supported style types
  
  Error: Failed to start server
  → Check if port is available and required dependencies are installed

Best Practices #

Development Workflow #

1. Use relative paths - Keep all paths relative to project root
2. Organize Sass - Use partials for reusable styles
3. Monitor logs - Watch terminal for compilation times and errors
4. Test frequently - Use live reload to see changes instantly
5. Keep public clean - Only include static assets in public directory

Production Builds #

1. Clean builds - Always delete output directory before building
2. Version control - Don't commit output directory
3. Test locally - Run build and test output before deploying
4. Optimize assets - Use PostCSS plugins for minification
5. Check permissions - Ensure build output has correct permissions

Configuration Management #

1. Environment variables - Use different configs for dev/prod if needed
2. Version control - Commit coralite.config.js to repository
3. Documentation - Comment complex configurations
4. Validation - Let defineConfig() catch configuration errors early

Integration with Other Tools #

Git #

Add to .gitignore:

  dist/
  node_modules/
  *.log

VS Code #

Recommended extensions:

• Sass/SCSS syntax highlighting
• HTML/CSS IntelliSense
• ESLint for JavaScript

CI/CD #

Example build script:

  npm ci
  npm run build
  # Deploy dist/ directory

Performance Optimization #

Development #

• Exclude unnecessary files from watching
• Use Sass partials to avoid compiling unused styles
• Limit number of active browser tabs during development
• Restart server if memory usage becomes high

Production #

• Use PostCSS plugins for minification
• Enable Sass compression for production
• Remove source maps for production builds
• Optimize images in public directory

Resources #

• Codeberg: Git repo
• Issues: Git iusses