@nera-static/core 4.10.0 → 4.11.0

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.
package/README.md CHANGED
@@ -40,7 +40,7 @@ npm install @nera-static/core
40
40
  1. **`loadAppData`** — parse `config/app.yaml` into `app`; resolve the presentation folders (and the `theme/` probe) and list `pages/` recursively.
41
41
  2. **`getPagesData`** — render each Markdown file with markdown-it, extract frontmatter, and derive `meta.href`/`dirname`/`filename`/`createdAt`. Returns `[{ content, meta }]`.
42
42
  3. **`getPluginsData`** — load and apply plugins (see the plugin contract below), threading their `app`/`pagesData` results.
43
- 4. **render** — delete `public/`, write the HTML files (layering theme views under the site's), copy assets (theme first, site second), and rewrite root-absolute URLs for `base_path` deploys.
43
+ 4. **render** — delete `public/`, write the HTML files (layering theme views under the site's), copy assets (theme first, site second), rewrite root-absolute URLs for `base_path` deploys, and (opt-in) version asset URLs with content hashes for cache busting.
44
44
 
45
45
  Two things that are easy to miss:
46
46
 
@@ -135,6 +135,22 @@ For **absolute** URLs you build yourself (canonical/OpenGraph tags, a sitemap),
135
135
 
136
136
  ---
137
137
 
138
+ ## 🔄 Cache busting (`asset_hashing`)
139
+
140
+ Browsers cache stylesheets, scripts and fonts, so after a deploy visitors can keep seeing the old CSS/JS until they force a reload. Enable content hashing in `config/app.yaml`:
141
+
142
+ ```yaml
143
+ asset_hashing: true
144
+ ```
145
+
146
+ As the last build step the engine appends `?v=<hash>` — the first 10 hex chars of the file's SHA-256 — to every local asset URL in the output: `<link>`/`<script>`/`<img>` sources, `srcset`, `poster`, `data-search-index`, and `url(…)` inside CSS. The hash is taken from the file that actually landed in `public/`, so site assets, theme-package assets and plugin output are all covered, and templates keep writing plain `/css/main.css`. Each file is versioned on its own: its URL changes exactly when its content does, and stays cacheable otherwise. A stylesheet is hashed after its `url()` references are rewritten, so a changed font busts the CSS as well.
147
+
148
+ Left untouched: links to pages (`.html`, directories), external and protocol-relative URLs, other schemes (`data:`, `mailto:`), fragment-only refs, URLs that already carry a query string, and references that don't resolve to a file in `public/`. It composes with `base_path`. URLs a script builds at runtime (a `fetch('/data.json')` literal in JS) are not rewritten — pass them in through an attribute such as `data-search-index` instead.
149
+
150
+ Opt-in and additive: without the key the build is byte-identical.
151
+
152
+ ---
153
+
138
154
  ## 🛠 Developing this engine
139
155
 
140
156
  This repo ships a bundled demo site used to exercise the pipeline during development — the same pipeline the CLI drives via `run()`:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nera-static/core",
3
- "version": "4.10.0",
3
+ "version": "4.11.0",
4
4
  "description": "The Nera static site generator engine — the build pipeline and the layered theme/view resolver, importable by the Nera CLI, @nera-static/validate and tooling",
5
5
  "main": "./src/index.js",
6
6
  "exports": {
package/src/index.js CHANGED
@@ -5,6 +5,7 @@ import {
5
5
  deleteFolder,
6
6
  createHtmlFiles,
7
7
  rewriteAssetUrls,
8
+ hashAssetUrls,
8
9
  } from './render.js'
9
10
  import { resolveTheme, checkThemeCompatibility } from './theme.js'
10
11
 
@@ -70,6 +71,11 @@ const run = async (settings = defaultSettings) => {
70
71
  // the HTML rewrite can't reach (CSS `url(/…)`, the web app manifest). Runs
71
72
  // after both asset passes; no-op when `base_path` is unset.
72
73
  await rewriteAssetUrls(dist, data.app.basePath)
74
+
75
+ // Cache busting: append `?v=<content hash>` to local asset URLs in the
76
+ // output. Last, so it hashes the final files behind the final URLs. No-op
77
+ // unless `asset_hashing: true` is set in config/app.yaml.
78
+ await hashAssetUrls(dist, data.app.basePath, data.app.asset_hashing === true)
73
79
  }
74
80
 
75
81
  export default run
package/src/render.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import fs from 'fs/promises'
2
2
  import fssync from 'fs'
3
3
  import path from 'path'
4
+ import { createHash } from 'crypto'
4
5
  import cpy from 'cpy'
5
6
  import pug from 'pug'
6
7
  import pretty from 'pretty'
@@ -154,6 +155,164 @@ export const rewriteAssetUrls = async (publicFolder, basePath) => {
154
155
  }
155
156
  // -----------------------------------------------------------------------------
156
157
 
158
+ // --- Asset hashing (config `asset_hashing: true` → cache busting) -------------
159
+ //
160
+ // Appends `?v=<content hash>` to every local asset URL in the built output, so
161
+ // a browser's cached copy is invalidated exactly when that file changes and
162
+ // kept otherwise. Runs as the very last build pass, over the files that actually
163
+ // landed in `public/` — site assets, theme-package assets and plugin output
164
+ // alike — so templates and themes keep writing plain `/css/main.css` and never
165
+ // need to know about it. Opt-in: without the key the output is byte-identical.
166
+ //
167
+ // Order matters: CSS files are rewritten first (their `url()` references —
168
+ // fonts, images — are leaves), and a file's hash is taken from its *final*
169
+ // content, so a font change changes the CSS hash too and busts the stylesheet.
170
+ //
171
+ // Left alone: external and protocol-relative URLs, `data:`/`mailto:` and other
172
+ // schemes, fragment-only refs, URLs that already carry a query string (the
173
+ // author chose one), links to pages (`.html`/`.htm`, directories), and any
174
+ // reference that does not resolve to a file in `public/`.
175
+
176
+ const HASH_LENGTH = 10
177
+ const PAGE_EXTENSIONS = new Set(['.html', '.htm'])
178
+
179
+ // Split `path#fragment` so the query lands before the fragment.
180
+ const splitFragment = (url) => {
181
+ const i = url.indexOf('#')
182
+ return i === -1 ? [url, ''] : [url.slice(0, i), url.slice(i)]
183
+ }
184
+
185
+ const isHashable = (url) =>
186
+ typeof url === 'string' &&
187
+ url !== '' &&
188
+ !url.startsWith('#') &&
189
+ !url.startsWith('//') &&
190
+ !/^[a-z][a-z0-9+.-]*:/i.test(url) &&
191
+ !url.includes('?')
192
+
193
+ // Returns `hashUrl(url, fromFile)`. Hashes are memoised per hasher and read
194
+ // from the file as it is on disk at first use.
195
+ const makeHasher = (publicFolder, basePath) => {
196
+ const cache = new Map()
197
+ const root = path.resolve(publicFolder)
198
+
199
+ // Resolve a URL as written in `fromFile` to a file inside `public/`, or null.
200
+ const resolveTarget = (url, fromFile) => {
201
+ let decoded
202
+ try {
203
+ decoded = decodeURI(url)
204
+ } catch {
205
+ return null
206
+ }
207
+ let target
208
+ if (decoded.startsWith('/')) {
209
+ // Root-absolute: strip a `base_path` prefix the base-path pass added.
210
+ const local =
211
+ basePath && decoded.startsWith(`${basePath}/`)
212
+ ? decoded.slice(basePath.length)
213
+ : decoded
214
+ target = path.join(root, local)
215
+ } else {
216
+ target = path.resolve(path.dirname(fromFile), decoded)
217
+ }
218
+ if (!target.startsWith(`${root}${path.sep}`)) return null
219
+ if (PAGE_EXTENSIONS.has(path.extname(target).toLowerCase())) return null
220
+ try {
221
+ return fssync.statSync(target).isFile() ? target : null
222
+ } catch {
223
+ return null
224
+ }
225
+ }
226
+
227
+ return (url, fromFile) => {
228
+ if (!isHashable(url)) return url
229
+ const [pathPart, fragment] = splitFragment(url)
230
+ if (!pathPart) return url
231
+ const target = resolveTarget(pathPart, fromFile)
232
+ if (!target) return url
233
+
234
+ let hash = cache.get(target)
235
+ if (!hash) {
236
+ hash = createHash('sha256')
237
+ .update(fssync.readFileSync(target))
238
+ .digest('hex')
239
+ .slice(0, HASH_LENGTH)
240
+ cache.set(target, hash)
241
+ }
242
+ return `${pathPart}?v=${hash}${fragment}`
243
+ }
244
+ }
245
+
246
+ // Version the URL-bearing attributes of one HTML document. Mirrors the
247
+ // attribute set of the base-path rewrite, but also accepts relative values.
248
+ export const hashHtmlUrls = (html, htmlFile, hashUrl) =>
249
+ html
250
+ .replace(
251
+ /\b(href|src|poster|data-search-index)=("|')([^"']*)\2/gi,
252
+ (m, attr, quote, val) =>
253
+ `${attr}=${quote}${hashUrl(val, htmlFile)}${quote}`
254
+ )
255
+ .replace(/\bsrcset=("|')([^"']*)\1/gi, (m, quote, list) => {
256
+ const rewritten = list
257
+ .split(',')
258
+ .map((part) => {
259
+ const seg = part.trim()
260
+ if (!seg) return part
261
+ const [url, ...descriptor] = seg.split(/\s+/)
262
+ return [hashUrl(url, htmlFile), ...descriptor].join(' ')
263
+ })
264
+ .join(', ')
265
+ return `srcset=${quote}${rewritten}${quote}`
266
+ })
267
+
268
+ // Version the `url()` references of one CSS file (root-absolute or relative).
269
+ export const hashCssUrls = (css, cssFile, hashUrl) =>
270
+ css.replace(
271
+ /url\(\s*(['"]?)([^)'"]*)\1\s*\)/gi,
272
+ (m, quote, val) =>
273
+ `url(${quote}${hashUrl(val.trim(), cssFile)}${quote})`
274
+ )
275
+
276
+ // The pass itself. No-op unless `enabled`; run it after every asset copy and
277
+ // after rewriteAssetUrls, so it sees the final files and final (prefixed) URLs.
278
+ export const hashAssetUrls = async (publicFolder, basePath, enabled) => {
279
+ if (!enabled || !fssync.existsSync(publicFolder)) return
280
+
281
+ const cssFiles = []
282
+ const htmlFiles = []
283
+ const walk = async (dir) => {
284
+ for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
285
+ const full = path.join(dir, entry.name)
286
+ if (entry.isDirectory()) {
287
+ await walk(full)
288
+ continue
289
+ }
290
+ const ext = path.extname(entry.name).toLowerCase()
291
+ if (ext === '.css') cssFiles.push(full)
292
+ else if (PAGE_EXTENSIONS.has(ext)) htmlFiles.push(full)
293
+ }
294
+ }
295
+ await walk(publicFolder)
296
+
297
+ // CSS first, so each stylesheet's hash is taken from its rewritten content.
298
+ // The HTML pass gets a fresh hasher: a stylesheet hashed during the CSS pass
299
+ // (as an `@import` target) may have been rewritten since.
300
+ const hashInCss = makeHasher(publicFolder, basePath)
301
+ for (const file of cssFiles.sort()) {
302
+ const css = await fs.readFile(file, 'utf-8')
303
+ const out = hashCssUrls(css, file, hashInCss)
304
+ if (out !== css) await fs.writeFile(file, out, 'utf-8')
305
+ }
306
+ const hashInHtml = makeHasher(publicFolder, basePath)
307
+ for (const file of htmlFiles) {
308
+ const html = await fs.readFile(file, 'utf-8')
309
+ const out = hashHtmlUrls(html, file, hashInHtml)
310
+ if (out !== html) await fs.writeFile(file, out, 'utf-8')
311
+ }
312
+ console.log(SUCCESS_COLOR, 'Asset URLs hashed')
313
+ }
314
+ // -----------------------------------------------------------------------------
315
+
157
316
  const getIgnoredFiles = (basePath) => {
158
317
  const ignorePath = path.join(basePath, '.neraignore')
159
318