npm - coralite-scripts - Versions diffs - 0.0.1 - Mend

coralite-scripts 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,124 @@
+# Coralite Development Environment Guide
+Welcome to **Coralite starter script**, a lightweight Static Site Generator (SSG) built for rapid development and clean output. This guide walks you through setting up your local development environment using the provided `coralite-scripts` package and configuration files.
+---
+## Prerequisites
+Ensure you have:
+- Node.js ≥ 20.x
+- npm or pnpm installed
+> Coralite uses experimental ES modules (`--experimental-vm-modules`) — make sure your Node version supports it.
+---
+## Project Structure
+Coralite expects a standard folder layout:
+```
+my-coralite-site/
+├── src/
+│   ├── pages/        # Your page templates (e.g., `about.html`, `index.html`)
+│   ├── scss/         # SCSS/Sass styles
+│   └── templates/    # Reusable template files
+├── public/           # Static assets (CSS, JS, images)
+├── dist/             # Output directory for built site (auto-generated)
+├── coralite.config.js # Configuration file
+└── package.json      # Scripts & dependencies
+```
+---
+## Step 1: Configure `coralite.config.js`
+Create or update your config file with the following:
+```js
+import { defineConfig } from 'coralite-scripts'
+export default defineConfig({
+  output: 'dist',
+  public: 'public',
+  pages: 'src/pages',
+  templates: 'src/templates',
+  sass: {
+    input: 'src/scss'
+  }
+})
+```
+> This tells Coralite where to find your source files, compile CSS from SCSS, and serve static assets.
+---
+## Step 2: Start the Development Server
+Update your `package.json` scripts to include:
+```json package.json
+{
+  "scripts": {
+    "start": "coralite-script"
+  }
+}
+```
+Then start the dev server:
+```bash
+npm run start
+```
+> ✅ The server runs on `http://localhost:3000` by default.
+---
+## Live Development Features
+Coralite provides real-time development workflows out of the box:
+| Feature | How It Works |
+|-------|-------------|
+| **Live Reload** | Automatically reloads browser when any `.html`, `.scss`, or `.sass` file changes. |
+| **Hot CSS Updates** | Sass/SCSS files are compiled instantly and injected into your page via Server-Sent Events (SSE). |
+| **File Watching** | Monitors `src/pages`, `src/scss`, `public`, and `src/templates`. |
+| **Dev Logs** | Shows real-time build times, file changes, and status codes in terminal. |
+---
+## How it works under the hood
+- **Routing**: `/` → `index.html`, `/about` → `about.html`
+- **HTML Compilation**: Pages are compiled with embedded live reload scripts.
+- **Sass Support**: `.scss`/`.sass` files are auto-compiled to CSS in `dist/css`.
+- **Server-Sent Events (SSE)**: Used for real-time updates without full page refresh.
+> No extra tooling needed — everything is built-in!
+---
+## Example usage
+1. Create a new file at `src/pages/about.html`:
+   ```html
+   <!DOCTYPE html>
+   <html lang="en">
+     <head><title>About</title></head>
+     <body><h1>Welcome to Coralite!</h1></body>
+   </html>
+   ```
+2. Visit `http://localhost:3000/about` in your browser — it loads instantly.
+3. Edit the file → see auto-reload!
+4. Add a new SCSS file at `src/scss/style.scss`, and import it into an HTML page via `<link rel="stylesheet" href="/css/style.css">`.
+---
+> **Feedback?** Found a bug or want a feature? Open an issue!
+Happy building with Coralite!

package/bin/coralite-scripts.js ADDED Viewed

@@ -0,0 +1,185 @@
+#!/usr/bin/env -S node --experimental-vm-modules --experimental-import-meta-resolve
+import express from 'express'
+import colours from 'kleur'
+import localAccess from 'local-access'
+import chokidar from 'chokidar'
+import loadConfig from '../src/load-config.js'
+import html from '../src/build-html.js'
+import buildSass from '../src/build-sass.js'
+import { toCode, toMS, toTime } from '../src/build-utils.js'
+import { extname, join } from 'path'
+import { readFile, access, constants } from 'fs/promises'
+const config = await loadConfig()
+const app = express()
+const port = config.server?.port || 3000
+// track active connections.
+const clients = new Set()
+const buildHTML = await html(config)
+const watchPath = [
+  config.public,
+  config.pages,
+  config.templates
+]
+// middleware to log request information including response time and status code
+app.use(function (req, res, next){
+  const start = process.hrtime()
+  // when the response is finished, calculate duration and log details
+  res.on('finish', function (){
+    const dash = colours.gray(' ─ ')
+    const duration = process.hrtime(start)
+    const uri = req.originalUrl || req.url
+    // log the response time and status code
+    process.stdout.write(toTime() + toCode(res.statusCode) + dash + toMS(duration) + dash + uri + '\n')
+  })
+  next()
+})
+// check if Sass is configured and add its input directory to watchPath for file changes.
+if (config.sass && config.sass.input) {
+  watchPath.push(config.sass.input)
+  app.use('/css', express.static(join(config.output, 'css'), {
+    cacheControl: false
+  }))
+}
+app
+  .use(express.static(config.public, {
+    cacheControl: false
+  }))
+  .get('/_/rebuild', (req, res) => {
+    // set headers for SSE
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive'
+    })
+    // add client to tracking set
+    clients.add(res)
+    // send initial connection message
+    res.write('data: connected\n\n')
+    // clean up on client disconnect
+    req.on('close', () => {
+      clients.delete(res)
+      res.end()
+    })
+  })
+  .get(/(.*)/, async (req, res) => {
+    // extract the requested path and its extension.
+    let path = req.path
+    const extension = extname(path)
+    // if no extension is present, assume it's a HTML file and append '.html'.
+    if (!extension) {
+      if ('/' === path) {
+        path = 'index.html'
+      } else if (path.endsWith('/')) {
+        path = path.slice(0, path.length -1) + '.html'
+      } else {
+        path += '.html'
+      }
+    }
+    try {
+      // first attempt to read the file directly.
+      await access(path)
+      const data = await readFile(path, 'utf8')
+      res.send(data)
+    } catch {
+      try {
+        // if that fails, try reading from pages directory.
+        const filePath = join(config.pages, path)
+        // check if page source file exists and is readable
+        await access(filePath, constants.R_OK)
+        const start = process.hrtime()
+        let duration, dash = colours.gray(' ─ ')
+        // build the HTML for this page using the built-in compiler.
+        await buildHTML.compile(filePath)
+        const data = await readFile(filePath, 'utf8')
+        // inject a script to enable live reload via Server-Sent Events
+        const injectedHtml = data.replace(/<\/body>/i, `
+<script>
+  const eventSource = new EventSource('/_/rebuild');
+  eventSource.onmessage = function(event) {
+    if (event.data === 'connected') return;
+    // Reload page when file changes
+    location.reload()
+  }
+</script>
+</body>`)
+        // prints time and path to the file that has been changed or added.
+        duration = process.hrtime(start)
+        process.stdout.write(toTime() + colours.bgGreen('Compiled HTML') + dash + toMS(duration) + dash + path + '\n')
+        res.send(injectedHtml)
+      } catch(error) {
+        // if all attempts fail, respond with a 404.
+        res.sendStatus(404)
+      }
+    }
+  })
+// watch for file changes
+const watcher = chokidar.watch(watchPath, {
+  persistent: true
+})
+watcher
+  .on('change', async (path) => {
+    if (path.endsWith('.scss') || path.endsWith('.sass')) {
+      const start = process.hrtime()
+      let duration, dash = colours.gray(' ─ ')
+      // rebuild CSS and send notification
+      await buildSass({
+        ...config.sass,
+        output: join(config.output, 'css')
+      })
+      // prints time and path to the file that has been changed or added.
+      duration = process.hrtime(start)
+      process.stdout.write(toTime() + colours.bgGreen('Compiled SASS') + dash + toMS(duration) + dash + path + '\n')
+    }
+    clients.forEach(client => {
+      client.write(`data: reload\n\n`)
+    })
+  })
+  .on('add', async (path) => {
+    if (path.endsWith('.scss') || path.endsWith('.sass')) {
+      const start = process.hrtime()
+      let duration, dash = colours.gray(' ─ ')
+      // rebuild CSS and send notification
+      await buildSass({
+        ...config.sass,
+        output: join(config.output, 'css')
+      })
+      // prints time and path to the file that has been changed or added.
+      duration = process.hrtime(start)
+      process.stdout.write(toTime() + colours.bgGreen('Compiled SASS') + dash + toMS(duration) + dash + path + '\n')
+    }
+  })
+app.listen(port, () => {
+  // @ts-ignore
+  const { local } = localAccess({ port })
+  const PAD = '  '
+  const border = '─'.repeat(Math.min(process.stdout.columns, 36) / 2)
+  // print server status
+  process.stdout.write('\n' + PAD + colours.green('Coralite is ready! 🚀\n\n'))
+  process.stdout.write(PAD + `${colours.bold('- Local:')}      ${local}\n\n`)
+  process.stdout.write(border + colours.inverse(' LOGS ') + border + '\n\n')
+})

package/package.json ADDED Viewed

@@ -0,0 +1,51 @@
+{
+  "name": "coralite-scripts",
+  "version": "0.0.1",
+  "description": "Configuration and scripts for Create Coralite.",
+  "type": "module",
+  "bin": {
+    "coralite-run": "./bin/coralite-scripts.js"
+  },
+  "keywords": [
+    "coralite",
+    "static-site-generator",
+    "ssg",
+    "configuration",
+    "scripts"
+  ],
+  "homepage": "https://coralite.io/docs/create-scripts",
+  "author": {
+    "name": "Thomas David",
+    "url": "https://thomasjackdavid.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/tjdavid/coralite.git",
+    "directory": "packages/coralite-scripts"
+  },
+  "bugs": {
+    "url": "https://codeberg.org/tjdavid/coralite/issues"
+  },
+  "imports": {
+    "#types": "./types/index.js"
+  },
+  "exports": {
+    ".": {
+      "default": "./src/index.js",
+      "types": "./types/index.js"
+    },
+    "./types": {
+      "default": "./types/index.js"
+    }
+  },
+  "license": "AGPL-3.0-only",
+  "devDependencies": {
+    "chokidar": "^4.0.3",
+    "express": "^5.1.0",
+    "html-validate": "^10.0.0",
+    "kleur": "^4.1.5",
+    "local-access": "^1.1.0",
+    "sass": "^1.91.0",
+    "coralite": "0.14.2"
+  }
+}

package/src/build-html.js ADDED Viewed

@@ -0,0 +1,60 @@
+import Coralite from 'coralite'
+/**
+ * @import { CoralitePluginInstance } from 'coralite/types'
+ */
+/**
+ * Builds HTML files from Coralite templates and pages.
+ *
+ * @param {Object} options
+ * @param {string} options.pages - Path to pages directory
+ * @param {string} options.templates - Path to templates directory
+ * @param {string} options.output - Output path for HTML files
+ * @param {string} options.output - Output path for HTML files
+ * @param {CoralitePluginInstance[]} [options.plugins=[]] - List of Coralite plugins.
+ */
+export default async function html ({
+  pages,
+  templates,
+  output,
+  plugins
+}) {
+  const coralite = new Coralite({
+    templates,
+    pages,
+    plugins
+  })
+  await coralite.initialise()
+  return {
+    /**
+     * Compiles the specified HTML pages using coralite and saves the output to the configured output path.
+     * @param {string | string[]} [paths] - Path to a single page or array of page paths relative to the pages directory. If omitted, compiles all pages.
+     */
+    async compile (paths) {
+      let relativePathPages
+      if (Array.isArray(paths)) {
+        relativePathPages = []
+        for (let i = 0; i < paths.length; i++) {
+          const path = paths[i]
+          relativePathPages.push(path.replace(pages + '/', ''))
+        }
+      } else if (paths) {
+        relativePathPages = paths.replace(pages + '/', '')
+      }
+      if (relativePathPages && relativePathPages[0] === '/') {
+        relativePathPages = relativePathPages.slice(1)
+      }
+      const document = await coralite.compile(relativePathPages)
+      await coralite.save(document, output)
+    }
+  }
+}

package/src/build-sass.js ADDED Viewed

@@ -0,0 +1,56 @@
+import * as sass from 'sass'
+import fs from 'fs/promises'
+import path from 'path'
+/**
+ * @import {Options} from 'sass'
+ */
+/**
+ * Compiles SCSS files to CSS with source maps
+ * @param {Object} options
+ * @param {string} options.input - The directory containing SCSS files to compile
+ * @param {string} options.output - The output directory for compiled CSS files
+ * @param {Options<'async'>} [options.options] - Sass compile options
+ * @returns {Promise<void>} Resolves when all files are compiled
+ */
+export default async function buildSass ({
+  input,
+  output,
+  options = {
+    sourceMap: true,
+    loadPaths: ['node_modules'],
+    silenceDeprecations: [
+      'color-functions',
+      'import',
+      'global-builtin'
+    ]
+  }
+}) {
+  try {
+    // ensure output directory exists
+    await fs.mkdir(output, { recursive: true })
+    // read all files from src/scss directory
+    const scssFiles = await fs.readdir(input)
+    const filteredScssFiles = scssFiles.filter(file => file.endsWith('.scss') && file[0] !== '_')
+    for (const file of filteredScssFiles) {
+      const filePath = path.join(input, file)
+      const outputFile = path.join(output, file.replace('.scss', '.css'))
+      const result = await sass.compileAsync(filePath, options)
+      // write the compiled CSS
+      await fs.writeFile(outputFile, result.css)
+      // write source map if enabled
+      if (result.sourceMap) {
+        const sourceMapPath = outputFile + '.map'
+        await fs.writeFile(sourceMapPath, JSON.stringify(result.sourceMap))
+      }
+    }
+  } catch (error) {
+    throw error
+  }
+}

package/src/build-utils.js ADDED Viewed

@@ -0,0 +1,39 @@
+import colours from 'kleur'
+/**
+ * Creates current time in format [HH:MM:SS].mmm (milliseconds), colored with ANSI colors, and formatted as bold white string for better readability of logs or console output
+ * @returns {string} - Formatted timestamp to be used within a log message.
+ */
+export function toTime () {
+  const now = new Date()
+  const hours = now.getHours().toString().padStart(2, '0')
+  const minutes = now.getMinutes().toString().padStart(2, '0')
+  const seconds = now.getSeconds().toString().padStart(2, '0')
+  const milliseconds = now.getMilliseconds().toString().padStart(3, '0')
+  return '[' + colours.magenta(`${hours}:${minutes}:${seconds}.${milliseconds}`) + '] '
+}
+/**
+ * Creates a formatted timestamp in milliseconds with ANSI colors and bold white string for better readability of logs or console output.
+ * @param {[number, number]} hrtime - High Resolution Time in microseconds since epoch, used to calculate time difference between two points of execution or the start/stopwatch function call respectively.
+ */
+export function toMS (hrtime) {
+  return colours.white().bold(`${(hrtime[1] / 1e6).toFixed(2)}ms`)
+}
+/**
+ * Converts HTTP status code into a colourised text.
+ * @param {number} code - HTTP status code to convert into a colourised text.
+ */
+export function toCode (code) {
+  let fn = 'green'
+  if (code >= 400) {
+    fn = 'red'
+  } else if (code > 300) {
+    fn = 'yellow'
+  }
+  return colours[fn](code)
+}

package/src/config.js ADDED Viewed

@@ -0,0 +1,50 @@
+/**
+ * @import {CoraliteScriptConfig} from '#types'
+ */
+/**
+ * @param {CoraliteScriptConfig} options
+ */
+export function defineConfig (options) {
+  // Validate required properties for CoraliteConfig
+  if (!options || typeof options !== 'object') {
+    throw new Error('Configuration must be a valid object')
+  }
+  if (!options.output || typeof options.output !== 'string') {
+    throw new Error('Configuration must contain a valid "output" property')
+  }
+  if (!options.templates || typeof options.templates !== 'string') {
+    throw new Error('Configuration must contain a valid "templates" property')
+  }
+  if (!options.pages || typeof options.pages !== 'string') {
+    throw new Error('Configuration must contain a valid "pages" property')
+  }
+  // Validate optional server configuration
+  if (options.server && typeof options.server !== 'object') {
+    throw new Error('Configuration "server" must be an object')
+  }
+  if (options.server?.port && (typeof options.server.port !== 'number' || options.server.port <= 0)) {
+    throw new Error('Configuration "server.port" must be a positive number')
+  }
+  // Validate sass configuration
+  if (options.sass && typeof options.sass !== 'object') {
+    throw new Error('Configuration "sass" must be an object')
+  }
+  if (options.sass?.input && typeof options.sass.input !== 'string') {
+    throw new Error('Configuration "sass.input" must be a string')
+  }
+  // Validate assets path
+  if (!options.public || typeof options.public !== 'string') {
+    throw new Error('Configuration must contain a valid "public" property')
+  }
+  return options
+}

package/src/index.js ADDED Viewed

	@@ -0,0 +1 @@
1	+ export * from './config.js'

package/src/load-config.js ADDED Viewed

@@ -0,0 +1,27 @@
+import { resolve } from 'path'
+/**
+ * @import {CoraliteScriptConfig} from '#types'
+ */
+/**
+ * Loads the configuration for the Coralite project.
+ *
+ * @returns {Promise<CoraliteScriptConfig>} The configuration object containing path settings or an empty promise if no config found
+ *
+ * @example
+ * ```js
+ * import loadConfig from './loadConfig.js'
+ *
+ * const config = await loadConfig()
+ * ```
+ */
+export default async function loadConfig () {
+  try {
+    const config = await import(resolve('coralite.config.js'))
+    return config.default
+  } catch(error) {
+    throw error
+  }
+}

package/types/index.js ADDED Viewed

@@ -0,0 +1,18 @@
+/**
+ * @import {CoraliteConfig} from 'coralite/types'
+ * @import {Options} from 'sass'
+ */
+/**
+ * @typedef {Object} CoraliteScriptBaseConfig
+ * @property {string} public - The path to the directory containing static assets.
+ * @property {Object} [server] - Server configuration options.
+ * @property {number} server.port - The port number on which the development server will run.
+ * @property {Object} [sass] - Sass compilation configuration.
+ * @property {string} sass.input - The path to the input Sass file or directory.
+ * @property {Options<'async'>} [sass.options] - Additional options passed to the Sass compiler.
+ */
+/**
+ * @typedef {CoraliteScriptBaseConfig & CoraliteConfig} CoraliteScriptConfig
+ */