mothwing 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AlexFlipnote
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,160 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# mothwing
+A small static site builder for pages as light as a moth's wing. Plain HTML in, plain HTML out, with hashed asset links and modulepreloads for code split JS. The rest is there when you ask for it: SEO tags, a Content-Security-Policy that allows only your own inline scripts, sitemaps dated from git, robots.txt and minified HTML.
+
+It was born as the build script of [ffxiv.watch](https://ffxiv.watch), and got tweaked over time until I was a little too proud of it to keep it there. So it branched out into its own thing, for any site that wants the same.
+
+## What it isn't
+mothwing isn't a framework. There are no components, and nothing runs in the browser that you didn't write. If you want those, Astro and SvelteKit are great.
+
+I did try them, and others, before making my own. They're good at what they do, but I wanted full control of the output: every byte of HTML exactly as I wrote it, and as few dependencies as possible between my files and the finished pages. mothwing is for when you want the same.
+
+## Getting started
+```sh
+npm install --save-dev mothwing
+npx mothwing dev     # serves on http://localhost:8080, a change renders just the pages it's in
+npx mothwing build   # production build into dist/
+```
+
+A site is a `mothwing.config.js` and a `src/` folder. The build mirrors `src/`, so `src/images/logo.png` is `/images/logo.png`:
+
+```
+mothwing.config.js
+src/
+  pages/           every page, the folders are the URLs: about.html -> /about/
+  partials/        bits of HTML the pages share
+  data/            JSON and JS the pages are filled from
+  js/              bundled by esbuild
+  ...              everything else is copied as it is
+```
+
+```js
+import { defineConfig } from "mothwing"
+
+export default defineConfig({
+  domain: "example.com",
+  js: { scripts: ["js/index.js"] },
+  exclude: ["js"]
+})
+```
+
+`defineConfig` does nothing but give your editor the config's types, so every option autocompletes and a typo is underlined. Without the import, a JSDoc comment does the same:
+
+```js
+/** @type {import("mothwing").Config} */
+export default { ... }
+```
+
+An option mothwing doesn't know fails the build either way.
+
+## Data
+Every file in `src/data/` is in every page by its name. `projects.json` is `{{ projects }}`, a folder is an object of its files. A `.js` file's default export is its value, called first when it's a function, for data worked out at build time:
+
+```js
+// src/data/site.js
+export default () => ({ year: new Date().getFullYear() })
+```
+
+```html
+<h1>{{ title }}</h1>              <!-- as text, escaped -->
+{{{ intro }}}                     <!-- as HTML, every line indented like the placeholder -->
+<footer>{{ site.year }}</footer>  <!-- into objects with dots -->
+```
+
+## Loops
+```html
+<ul>
+  <x-each items="projects" as="project">
+    <li>
+      <x-if value="project.url"><a href="{{ project.url }}">{{ project.name }}</a></x-if>
+      <x-if not="project.url">{{ project.name }}</x-if>
+    </li>
+  </x-each>
+</ul>
+```
+
+`<x-each>` repeats its content per item, `index="i"` names the item's position. `<x-if value="...">` shows its content when the value is there and not empty, `not="..."` when it isn't. On lines of their own, they leave no empty lines behind and their content keeps the indent it would have by hand.
+
+`items`, `value` and `not` take a name as it is, `items="projects"`, not a placeholder. The rest of the tags' attributes can have placeholders, `<x-seo title="{{ page.name }}"/>`.
+
+Every tag is ordinary HTML to an editor or formatter. Templates formatted by Prettier build to the same pages.
+
+## Pages
+`src/pages/about.html` is `/about/`, `src/pages/blog/index.html` is `/blog/`.
+
+`[projects.id].html` makes a page per item of `projects` in the data folder, with its `id` as the URL: `src/pages/projects/[projects.id].html` is `/projects/hexclock/` for `{ "id": "hexclock" }`. The item is `{{ page }}`, and the list links to the pages by the same field, `/projects/{{ project.id }}/`.
+
+### .data.js
+For values that take more than the data folder, a page can have a `.data.js` next to it, whose default export returns them. Its values come before the data folder's:
+
+```js
+// src/pages/index.data.js
+export default () => ({ updated: new Date().toISOString() })
+```
+
+`[name].html` with a `.data.js` makes a page per item that returns, each with a `slug`. `posts/[post].html` with a slug of `first` becomes `/posts/first/`. Besides its values, an item can have:
+
+| Key | |
+| --- | --- |
+| `slug` | The page's URL part |
+| `sources` | The files its content comes from, relative to `src/`, which the sitemap dates the page by |
+| `files` | More files to write, by their path in the build: `{ "rows/list.html": "..." }` |
+
+For building HTML in a `.data.js`, `mothwing/html` has an `html` tagged template, which escapes what goes into it unless it's HTML already, and `slug()`.
+
+## Tags
+Paths in tags start at `src/`, the same as the URLs in the build.
+
+| Tag | Does |
+| --- | ---- |
+| `<x-html src="partials/nav.html"/>` | Pastes in a partial, indented like the tag |
+| `<x-js src="/js/index.js"/>` | `<script>` with a `?v=hash` |
+| `<x-js src="/js/app.js" module/>` | One of your `modules`, with a modulepreload for each chunk it imports. `preload="/js/data/x.js"` adds one for a file it `import()`s later |
+| `<x-css src="/css/index.css"/>` | Stylesheet `<link>` with a `?v=hash` |
+| `<x-seo title="..." description="..."/>` | Title, description, canonical URL, link preview tags. `image`, `image-alt` and `image-size="WxH"` for its own preview, `section` and `name` for breadcrumbs in search results |
+
+A tag mothwing doesn't know, or one missing what it needs, fails the build with the page it's on.
+
+## Config
+Only `domain` is needed. Folders are relative to `src/`.
+
+| Option | Default | |
+| --- | --- | --- |
+| `src`, `out` | `"src"`, `"dist"` | Relative to the config |
+| `pages` | `"pages"` | |
+| `data` | `"data"` | Its files are in every page, it isn't copied to the build |
+| `notFound` | `"404.html"` | Kept in the build's root, out of the sitemap |
+| `js` | | `scripts` are bundled on their own, `modules` together, sharing their common code in chunks. `chunks` sets the chunks' folder, next to the modules by default |
+| `sass` | `{}` | Sass to compile, `{ "scss/index.scss": "css/index.css" }`, needs `sass` installed |
+| `exclude` | `[]` | Folders left out of the build, like the JS sources: `["js"]`. Pages and partials always are |
+| `rerender` | `[]` | Folders your `.data.js` reads with `fs`, whose changes render every page in dev. What pages import, include or use from the data folder is followed on its own |
+| `seo` | | For `<x-seo>`: `siteName`, `locale`, `image` (the default preview), `maxTitle`, `maxDescription` |
+| `esbuild` | `{}` | esbuild options for every bundle |
+
+### Extras
+Off until you turn them on. `true` turns one on as it comes, an object changes how it works.
+
+| Option | Turned on | Object |
+| --- | --- | --- |
+| `minify` | Minifies the HTML of production builds | html-minifier-terser options |
+| `csp` | A `<meta>` Content-Security-Policy: only your own files, and your inline scripts by their hash | Directives over the defaults, `{ "style-src": "'self' 'unsafe-inline'" }` |
+| `sitemap` | `sitemap.xml`, each page dated by the last commit to its files | `sections` that get a sitemap each, `dates: false` to leave git out |
+| `robots` | `robots.txt` that allows everything, pointing at the sitemap | `block` crawlers by name, `disallow` paths |
+| `cname` | `CNAME` with the domain, for GitHub Pages | |
+| `activeLinks` | `aria-current="page"` on links to the page they're on, `"true"` on links to its section | A function `(href, route)` returning `"page"`, `"section"` or `false`, `undefined` keeps the default |
+
+## Making it yours
+For what's only your site's:
+
+```js
+export default defineConfig({
+  domain: "example.com",
+  // <x-emoji name="coffee"/>
+  tags: {
+    "x-emoji": ({ attrs }) => `<img src="/emoji/${attrs.name}.png" alt="">`
+  },
+  // Every page, after its placeholders are filled
+  transforms: [(html, route) => html.replace("<body>", `<body data-page="${route.url}">`)],
+  // Once the pages are written, `dev` is true on dev renders
+  after: [async ({ site, routes, dev }) => { /* draw preview images, ... */ }]
+})
+```

package/bin/mothwing.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { build, clean, dev, loadConfig, renderSite } from "../src/index.js"
+
+const USAGE = `Usage: mothwing <command> [--root <dir>]
+
+Commands:
+  build    Build the site for production
+  dev      Serve it and rebuild on changes, takes --host and --port
+  clean    Remove the build folder
+  html     Render only the pages, into an existing build, --pages a.html,b.html for just those`
+
+/**
+ * @param {string} name
+ * @returns {string | undefined}
+ */
+const flag = (name) => {
+  const i = process.argv.indexOf(`--${name}`)
+  return i > -1 ? process.argv[i + 1] : undefined
+}
+
+/** @type {Record<string, (site: import("../src/index.js").Site) => Promise<void>>} */
+const commands = {
+  build: (site) => build(site),
+  dev: (site) => dev(site, { host: flag("host"), port: Number(flag("port")) || undefined }),
+  clean: (site) => clean(site),
+  html: async (site) => {
+    const pages = flag("pages")
+    const deps = await renderSite(site, { only: pages ? new Set(pages.split(",")) : undefined })
+    // Run by dev, which keeps track of what the pages are made from
+    process.send?.({ deps })
+  }
+}
+const command = commands[process.argv[2]]
+
+if (!command) {
+  console.log(USAGE)
+  process.exit(process.argv[2] ? 1 : 0)
+}
+
+try {
+  await command(await loadConfig(flag("root")))
+} catch (err) {
+  console.error(`mothwing: ${/** @type {Error} */ (err).message}`)
+  process.exit(1)
+}

package/package.json

@@ -1,6 +1,73 @@
-{
-  "name": "mothwing",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "mothwing",
+  "version": "0.0.2",
+  "description": "A small static site builder for pages as light as a moth's wing",
+  "keywords": [
+    "static-site-generator",
+    "ssg",
+    "html",
+    "esbuild",
+    "csp",
+    "sitemap"
+  ],
+  "author": "AlexFlipnote",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AlexFlipnote/mothwing.git"
+  },
+  "homepage": "https://github.com/AlexFlipnote/mothwing#readme",
+  "bugs": {
+    "url": "https://github.com/AlexFlipnote/mothwing/issues"
+  },
+  "type": "module",
+  "bin": {
+    "mothwing": "bin/mothwing.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./html": {
+      "types": "./types/html.d.ts",
+      "default": "./src/html.js"
+    }
+  },
+  "files": [
+    "bin",
+    "src",
+    "types"
+  ],
+  "engines": {
+    "node": ">=20.11"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "lint": "eslint .",
+    "types": "tsc src/index.js src/html.js --allowJs --declaration --emitDeclarationOnly --module nodenext --moduleResolution nodenext --target es2022 --strict --types node --skipLibCheck --outDir types",
+    "prepack": "npm run types",
+    "typecheck": "tsc -p jsconfig.json"
+  },
+  "dependencies": {
+    "@types/html-minifier-terser": "^7.0.2",
+    "esbuild": "0.28.1",
+    "html-minifier-terser": "7.2.0"
+  },
+  "peerDependencies": {
+    "sass": "^1.93.3"
+  },
+  "peerDependenciesMeta": {
+    "sass": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "@types/node": "^22.20.5",
+    "eslint": "^9.39.5",
+    "globals": "^16.5.0",
+    "sass": "^1.105.2",
+    "typescript": "^6.0.3"
+  }
+}

package/src/assets.js

@@ -0,0 +1,122 @@
+import esbuild from "esbuild"
+import fs from "fs"
+import path from "path"
+import { log, posix } from "./log.js"
+
+/**
+ * @param {import("./config.js").Site} site
+ * @param {string} file Absolute path
+ * @returns {boolean} In one of the config's exclude folders
+ */
+export const isExcluded = (site, file) => {
+  const relative = posix(path.relative(site.src, file))
+  return site.exclude.some(dir => relative === dir || relative.startsWith(`${dir}/`))
+}
+
+/** @param {import("./config.js").Site} site */
+export async function clean(site) {
+  log("CLEAN", "Removing build folder...")
+  // Retries, as the dev server can be writing a file into it right then
+  await fs.promises.rm(site.out, { recursive: true, force: true, maxRetries: 5 })
+  log("CLEAN", "Done")
+}
+
+/**
+ * Copies src as it is into the build, leaving out the excluded folders, pages and Sass.
+ * @param {import("./config.js").Site} site
+ */
+export async function copyAssets(site) {
+  log("ASSET", "Copying assets...")
+  fs.cpSync(site.src, site.out, {
+    recursive: true,
+    filter: (file) => !isExcluded(site, file) && !/\.(html|scss|sass)$/.test(file)
+  })
+  log("ASSET", "Done copying assets")
+}
+
+/**
+ * @param {string[]} files "js/a.js", "js/pages/b.js"
+ * @returns {string} The folder they're all in, "js"
+ */
+function commonFolder(files) {
+  const [first = [], ...rest] = files.map(file => path.posix.dirname(file).split("/"))
+  let depth = first.length
+  for (const parts of rest) {
+    while (depth && parts.slice(0, depth).join("/") !== first.slice(0, depth).join("/")) depth--
+  }
+  return first.slice(0, depth).join("/").replace(/^\.$/, "")
+}
+
+/**
+ * The esbuild builds for the config's js: one per script, and one for all the modules, so they can share chunks.
+ * @param {import("./config.js").Site} site
+ * @param {import("esbuild").BuildOptions} [overrides]
+ * @returns {import("esbuild").BuildOptions[]}
+ */
+export function jsBuilds(site, overrides = {}) {
+  /** @param {import("esbuild").BuildOptions} build */
+  const options = (build) => ({
+    bundle: true,
+    minify: true,
+    sourcemap: false,
+    target: ["es2020"],
+    ...site.esbuild,
+    ...build,
+    ...overrides
+  })
+  const { scripts, modules, chunks } = site.js
+  // From the modules' own folder, as esbuild's chunk hashes depend on the paths the build is laid out with
+  const base = commonFolder(modules)
+
+  return [
+    ...scripts.map(file => options({ entryPoints: [path.join(site.src, file)], outfile: path.join(site.out, file), format: "iife" })),
+    ...modules.length
+      ? [options({
+        entryPoints: modules.map(file => path.join(site.src, file)),
+        outbase: path.join(site.src, base),
+        outdir: path.join(site.out, base),
+        format: "esm",
+        splitting: true,
+        chunkNames: `${path.posix.relative(base, chunks) || "."}/[name]-[hash]`
+      })]
+      : []
+  ]
+}
+
+/**
+ * Bundles the JS, and notes which chunks each file imports, for the modulepreload links.
+ * @param {import("./config.js").Site} site
+ * @param {import("./render.js").BuildState} state
+ */
+export async function buildJS(site, state) {
+  const builds = jsBuilds(site, { metafile: true })
+  if (!builds.length) return
+  log("JS", "Building JS...")
+  const results = await Promise.all(builds.map(build => esbuild.build(build)))
+
+  /** @param {string} file */
+  const url = (file) => "/" + posix(path.relative(site.out, path.resolve(file)))
+  for (const [file, output] of results.flatMap(r => Object.entries(r.metafile?.outputs ?? {}))) {
+    const imports = output.imports.filter(i => i.kind === "import-statement").map(i => url(i.path))
+    if (imports.length) state.chunkImports.set(url(file), imports)
+    if (output.entryPoint) state.entryChunks.set("/" + posix(path.relative(site.src, output.entryPoint)), url(file))
+  }
+  log("JS", "Done building the JS")
+}
+
+/** @param {import("./config.js").Site} site */
+export async function buildSass(site) {
+  const files = Object.entries(site.sass)
+  if (!files.length) return
+  log("CSS", "Converting SCSS to CSS")
+  const sass = await import("sass").catch(() => {
+    throw new Error("The config has sass to compile, which needs it installed: npm install sass")
+  })
+  for (const [from, to] of files) {
+    const result = sass.compile(path.join(site.src, from), { style: "compressed" })
+    const outputFile = path.join(site.out, to)
+    fs.mkdirSync(path.dirname(outputFile), { recursive: true })
+    fs.writeFileSync(outputFile, result.css)
+  }
+  log("CSS", "Done building the CSS")
+}

package/src/build.js

@@ -0,0 +1,104 @@
+import fs from "fs"
+import { minify } from "html-minifier-terser"
+import path from "path"
+import { buildJS, buildSass, clean, copyAssets } from "./assets.js"
+import { withCsp } from "./csp.js"
+import { loadData } from "./data.js"
+import { dependencies } from "./deps.js"
+import { log } from "./log.js"
+import { buildState, renderPage } from "./render.js"
+import { listRoutes } from "./routes.js"
+import { writeSiteFiles } from "./site.js"
+
+/**
+ * Writes a file unless it already has this content. Writing is much slower than reading on Windows, and a dev render
+ * of a whole site mostly writes what's already there.
+ * @param {string} file
+ * @param {string} content
+ * @returns {boolean} Whether it was written
+ */
+export function writeIfChanged(file, content) {
+  try {
+    if (fs.readFileSync(file, "utf8") === content) return false
+  } catch {
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+  }
+  fs.writeFileSync(file, content)
+  return true
+}
+
+/**
+ * @param {import("./config.js").Site} site
+ * @param {import("./render.js").BuildState} state
+ * @param {{ hashed?: boolean, only?: Set<string> }} [options] `hashed` for production: hashed asset links and minified
+ *   HTML. `only` renders just these pages, relative to the pages folder
+ * @returns {Promise<import("./routes.js").Route[]>} The pages rendered
+ */
+export async function buildHTML(site, state, { hashed = true, only } = {}) {
+  log("HTML", only ? `Rendering ${[...only].join(", ")}...` : "Rendering pages...")
+  state.assetUrls.clear()
+  state.templates.clear()
+  state.used.clear()
+  state.data = await loadData(site)
+
+  const routes = await listRoutes(site, state.data, only)
+  let written = 0
+  for (const route of routes) {
+    const html = renderPage(site, state, route, hashed)
+    const finished = hashed && site.minify ? await minify(html, site.minify) : html
+    if (writeIfChanged(path.join(site.out, route.output), site.csp ? withCsp(site.csp, finished) : finished)) written++
+
+    for (const [file, content] of Object.entries(route.props.files ?? {})) writeIfChanged(path.join(site.out, file), content)
+  }
+
+  // A page that used the data folder is dated by it too
+  for (const route of routes) {
+    if (route.props.page) continue
+    for (const name of state.used.get(route.source) ?? []) {
+      const file = state.data.files[name]
+      if (file && !(name in route.props) && !route.sources.includes(file)) route.sources.push(file)
+    }
+  }
+  log("HTML", `Done rendering ${routes.length} pages${written < routes.length ? `, ${written} changed` : ""}`)
+  return routes
+}
+
+/**
+ * @param {import("./config.js").Site} site
+ * @param {import("./routes.js").Route[]} routes
+ * @param {boolean} dev
+ */
+async function runAfter(site, routes, dev) {
+  for (const hook of site.after) await hook({ site, routes, dev })
+}
+
+/**
+ * Renders the pages into an existing build, as dev does after a change. With `only`, just those pages, and the
+ * sitemaps are left as they are.
+ * @param {import("./config.js").Site} site
+ * @param {{ only?: Set<string> }} [options]
+ * @returns {Promise<Record<string, string[]>>} What each page rendered is made from, see deps.js
+ */
+export async function renderSite(site, { only } = {}) {
+  const state = buildState()
+  const routes = await buildHTML(site, state, { hashed: false, only })
+  if (!only) await writeSiteFiles(site, routes, false)
+  await runAfter(site, routes, true)
+  return dependencies(site, state, routes)
+}
+
+/**
+ * The production build, from an empty build folder.
+ * @param {import("./config.js").Site} site
+ */
+export async function build(site) {
+  const state = buildState()
+  await clean(site)
+  await copyAssets(site)
+  await buildJS(site, state)
+  await buildSass(site)
+  // After JS and CSS, since the ?v=hash is made from the built files
+  const routes = await buildHTML(site, state)
+  await writeSiteFiles(site, routes)
+  await runAfter(site, routes, false)
+}