diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7078b57..4ac99d7 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -18,6 +18,7 @@ jobs: node-version: ${{ matrix.node }} - run: npm install - run: npm test + - run: npm run size e2e: runs-on: ubuntu-latest diff --git a/examples/counter/app.js b/examples/counter/app.js index d86d53e..f82d179 100644 --- a/examples/counter/app.js +++ b/examples/counter/app.js @@ -17,6 +17,8 @@ export default function createApp () { } function mainView (state, emit) { + emit(state.events.DOMTITLECHANGE, `count is ${state.count}`) + return html`

count is ${state.count}

diff --git a/examples/counter/style.css b/examples/counter/style.css new file mode 100644 index 0000000..99a8eda --- /dev/null +++ b/examples/counter/style.css @@ -0,0 +1,29 @@ +/* The style.css convention: bankai's client entry imports this file + automatically (CSS is a client concern — server code never sees it), + Vite extracts and hashes it, and the server preloads it via Early + Hints. The v8 answer to sheetify. */ + +body { + font-family: system-ui, sans-serif; + max-width: 36rem; + margin: 4rem auto; + padding: 0 1rem; + line-height: 1.5; +} + +h1 { + font-size: 1.6rem; +} + +button { + font: inherit; + padding: 0.4rem 1.2rem; + border: 2px solid currentColor; + border-radius: 4px; + background: transparent; + cursor: pointer; +} + +button:hover { + background: #ffc0cb55; +} diff --git a/package.json b/package.json index a24ae41..9250f77 100644 --- a/package.json +++ b/package.json @@ -14,7 +14,8 @@ "test": "node --test packages/core/test/ packages/html/test/ packages/component/test/ packages/devtools/test/ packages/migrate/test/ packages/bankai/test/", "test:e2e": "node --test test/e2e/", "bench": "node bench/render.js", - "bench:browser": "node bench/real-browser.js" + "bench:browser": "node bench/real-browser.js", + "size": "node scripts/size.js" }, "repository": "choojs/choo", "license": "MIT", diff --git a/packages/bankai/cli.js b/packages/bankai/cli.js index 0d624b0..560524d 100644 --- a/packages/bankai/cli.js +++ b/packages/bankai/cli.js @@ -9,6 +9,9 @@ // bankai inspect size report for the built output // // options: --port --out --title +// --prerender (build: comma-separated routes) +// --h2 (serve: HTTP/2 + local cert, so +// browsers act on the Early Hints) import { parseArgs } from 'node:util' @@ -17,7 +20,9 @@ const { values, positionals } = parseArgs({ options: { port: { type: 'string' }, out: { type: 'string', default: 'dist' }, - title: { type: 'string', default: 'choo' } + title: { type: 'string', default: 'choo' }, + prerender: { type: 'string' }, + h2: { type: 'boolean', default: false } } }) @@ -33,11 +38,13 @@ try { } else if (command === 'build') { requireEntry(entry) const { default: build } = await import('./lib/build.js') - const { outDir, compressed } = await build({ entry, outDir: values.out, title: values.title }) - console.log(`bankai: built to ${outDir} (${compressed} asset(s) precompressed) — bankai serve to run it`) + const prerender = values.prerender ? values.prerender.split(',').map((r) => r.trim()).filter(Boolean) : [] + const { outDir, compressed, prerendered } = await build({ entry, outDir: values.out, title: values.title, prerender }) + const extra = prerendered.length ? `, ${prerendered.length} route(s) prerendered` : '' + console.log(`bankai: built to ${outDir} (${compressed} asset(s) precompressed${extra}) — bankai serve to run it`) } else if (command === 'serve') { const { default: serve } = await import('./lib/serve.js') - const { origin } = await serve({ outDir: values.out, port }) + const { origin } = await serve({ outDir: values.out, port, h2: values.h2 }) console.log(`bankai: production server on ${origin}`) } else if (command === 'inspect') { const { default: inspect } = await import('./lib/inspect.js') diff --git a/packages/bankai/lib/build.js b/packages/bankai/lib/build.js index c469013..e08ebf7 100644 --- a/packages/bankai/lib/build.js +++ b/packages/bankai/lib/build.js @@ -4,28 +4,33 @@ // dist/assets/* hashed client chunks + css // dist/.vite/manifest.json Vite's build manifest // dist/bankai.json bankai's route/asset metadata for serving +// dist/**/index.html prerendered routes (--prerender) // dist/sw.js service worker (if /sw.js exists), // with the precached asset list defined in // *.br / *.gz precompressed siblings for every text asset -import { readFile, writeFile, readdir, stat, access } from 'node:fs/promises' +import { readFile, writeFile, readdir, stat, access, mkdir } from 'node:fs/promises' import { join, dirname, resolve } from 'node:path' +import { pathToFileURL } from 'node:url' import { brotliCompress, gzip, constants } from 'node:zlib' import { promisify } from 'node:util' -import bankaiPlugin, { CLIENT_ID } from './plugin.js' +import bankaiPlugin, { findCss, CLIENT_ID } from './plugin.js' +import { resolveApp } from './app.js' +import { documentHead, documentTail } from './document.js' const brotli = promisify(brotliCompress) const gzipP = promisify(gzip) -export default async function buildApp ({ entry, outDir = 'dist', title = 'choo' }) { +export default async function buildApp ({ entry, outDir = 'dist', title = 'choo', prerender = [] }) { const { build } = await import('vite') entry = resolve(entry) outDir = resolve(outDir) + const css = await findCss(entry) await build({ appType: 'custom', - plugins: [bankaiPlugin(entry)], + plugins: [bankaiPlugin(entry, { css })], logLevel: 'warn', build: { outDir, @@ -48,11 +53,36 @@ export default async function buildApp ({ entry, outDir = 'dist', title = 'choo' const meta = { title, entry, assets, builtAt: new Date().toISOString() } await writeFile(join(outDir, 'bankai.json'), JSON.stringify(meta, null, 2)) + // static prerender: routes rendered through the same toStream path the + // server uses, written as /index.html + const prerendered = [] + if (prerender.length) { + const mod = await import(pathToFileURL(entry)) + for (const route of prerender) { + const app = resolveApp(mod, entry) + const state = {} + let body = '' + const decoder = new TextDecoder() + for await (const chunk of app.toStream(route, state)) { + body += decoder.decode(chunk, { stream: true }) + } + const page = documentHead({ title: state.title || title, ...assets }) + body + documentTail(state) + const rel = route === '/' ? 'index.html' : join(route.replace(/^\//, '').replace(/\/$/, ''), 'index.html') + const target = join(outDir, rel) + await mkdir(dirname(target), { recursive: true }) + await writeFile(target, page) + prerendered.push(route) + } + } + // service worker: /sw.js, built standalone with the asset // list injected — the choo-service-worker convention, manifest edition const swSource = join(dirname(entry), 'sw.js') if (await exists(swSource)) { - const precache = ['/', ...assets.scripts, ...assets.modulepreload, ...assets.css] + const precache = [ + ...(prerendered.length ? prerendered : ['/']), + ...assets.scripts, ...assets.modulepreload, ...assets.css + ] await build({ appType: 'custom', logLevel: 'warn', @@ -71,7 +101,7 @@ export default async function buildApp ({ entry, outDir = 'dist', title = 'choo' // precompress text assets so the server never compresses at request time const compressed = await precompress(outDir) - return { outDir, meta, compressed } + return { outDir, meta, compressed, prerendered } } function collectCss (manifest, entryChunk) { diff --git a/packages/bankai/lib/dev.js b/packages/bankai/lib/dev.js index 6ea53d4..470366c 100644 --- a/packages/bankai/lib/dev.js +++ b/packages/bankai/lib/dev.js @@ -4,17 +4,18 @@ import { createServer } from 'node:http' -import bankaiPlugin, { CLIENT_URL } from './plugin.js' +import bankaiPlugin, { findCss, CLIENT_URL } from './plugin.js' import { resolveApp } from './app.js' import { documentHead, documentTail } from './document.js' export default async function dev ({ entry, port = 8080, title = 'choo' }) { const { createServer: createViteServer } = await import('vite') + const css = await findCss(entry) // style.css convention; restart to add it const vite = await createViteServer({ appType: 'custom', server: { middlewareMode: true }, - plugins: [bankaiPlugin(entry)], + plugins: [bankaiPlugin(entry, { css })], logLevel: 'warn' }) @@ -26,14 +27,22 @@ export default async function dev ({ entry, port = 8080, title = 'choo' }) { const app = resolveApp(mod, entry) const state = {} + // Read the first chunk before writing the head: by then stores + // have run and the view has rendered up to its first async hole, + // so DOMTitleChange emits have landed in state.title. + const reader = app.toStream(req.url, state).getReader() + const first = await reader.read() + res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' }) res.write(documentHead({ - title, + title: state.title || title, scripts: ['/@vite/client', CLIENT_URL] })) - - for await (const chunk of app.toStream(req.url, state)) { - res.write(chunk) + if (!first.done) res.write(first.value) + for (;;) { + const { done, value } = await reader.read() + if (done) break + res.write(value) } res.end(documentTail(state)) } catch (err) { diff --git a/packages/bankai/lib/plugin.js b/packages/bankai/lib/plugin.js index b7a5bc3..070a55e 100644 --- a/packages/bankai/lib/plugin.js +++ b/packages/bankai/lib/plugin.js @@ -9,7 +9,7 @@ const RESOLVED_CLIENT_ID = '\0' + CLIENT_ID // middleware ('\0' encodes as '__x00__') export const CLIENT_URL = '/@id/__x00__' + CLIENT_ID -export default function bankaiPlugin (entry) { +export default function bankaiPlugin (entry, { css } = {}) { return { name: 'bankai', resolveId (id) { @@ -18,6 +18,10 @@ export default function bankaiPlugin (entry) { load (id) { if (id === RESOLVED_CLIENT_ID) { return [ + // the style.css convention: CSS is a client concern, so the + // client glue imports it and server code never sees it — the + // v8 answer to what sheetify transforms did in v9 + ...(css ? [`import ${JSON.stringify(css)}`] : []), `import create from ${JSON.stringify(entry)}`, 'const app = typeof create === "function" && !create.mount ? create() : create', 'app.mount(app.selector || "body")' @@ -26,3 +30,16 @@ export default function bankaiPlugin (entry) { } } } + +// /style.css, when it exists +export async function findCss (entry) { + const { access } = await import('node:fs/promises') + const { join, dirname } = await import('node:path') + const candidate = join(dirname(entry), 'style.css') + try { + await access(candidate) + return candidate + } catch (e) { + return null + } +} diff --git a/packages/bankai/lib/serve.js b/packages/bankai/lib/serve.js index 7de3282..d84a88c 100644 --- a/packages/bankai/lib/serve.js +++ b/packages/bankai/lib/serve.js @@ -1,18 +1,26 @@ // bankai serve — the production server. Static assets from dist // (precompressed variants negotiated, hashed assets cached forever); -// everything else is a page: 103 Early Hints from the build manifest, -// then streaming SSR of the entry module — imported natively, because -// the server side never needed a build. +// prerendered routes served as static HTML; everything else is a page: +// 103 Early Hints from the build manifest, then streaming SSR of the +// entry module — imported natively, because the server side never +// needed a build. `h2: true` serves HTTP/2 with a generated local cert +// (allowHTTP1 for tools) — browsers only act on Early Hints over h2/h3, +// so production deployments want this or a fronting h2 proxy. -import { createServer } from 'node:http' +import http from 'node:http' +import http2 from 'node:http2' +import { execFile } from 'node:child_process' import { createReadStream } from 'node:fs' -import { readFile, stat } from 'node:fs/promises' +import { readFile, stat, mkdir } from 'node:fs/promises' import { join, normalize, extname, resolve } from 'node:path' import { pathToFileURL } from 'node:url' +import { promisify } from 'node:util' import { resolveApp } from './app.js' import { documentHead, documentTail, assetLinks } from './document.js' +const execFileP = promisify(execFile) + const MIME = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', @@ -28,13 +36,13 @@ const MIME = { '.ico': 'image/x-icon' } -export default async function serve ({ outDir = 'dist', port = 8080 }) { +export default async function serve ({ outDir = 'dist', port = 8080, h2 = false }) { outDir = resolve(outDir) const meta = JSON.parse(await readFile(join(outDir, 'bankai.json'), 'utf8')) const mod = await import(pathToFileURL(meta.entry)) const links = assetLinks(meta.assets) - const server = createServer(async (req, res) => { + async function handler (req, res) { const url = new URL(req.url, 'http://localhost') const pathname = decodeURIComponent(url.pathname) @@ -49,7 +57,14 @@ export default async function serve ({ outDir = 'dist', port = 8080 }) { } } - // page: hints first, then stream + // prerendered page? + const prerendered = normalize(join(outDir, pathname, 'index.html')) + if (prerendered.startsWith(outDir) && await isFile(prerendered)) { + if (links.length && res.writeEarlyHints) res.writeEarlyHints({ link: links }) + return sendFile(req, res, prerendered, pathname, { link: links.join(', ') }) + } + + // live page: hints first, then stream try { const app = resolveApp(mod, meta.entry) const state = {} @@ -57,13 +72,22 @@ export default async function serve ({ outDir = 'dist', port = 8080 }) { if (links.length && res.writeEarlyHints) { res.writeEarlyHints({ link: links }) } + + // first chunk before the head: stores + the first render slice have + // run by then, so state.title is populated + const reader = app.toStream(req.url, state).getReader() + const first = await reader.read() + res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', link: links.join(', ') }) - res.write(documentHead({ title: meta.title, ...meta.assets })) - for await (const chunk of app.toStream(req.url, state)) { - res.write(chunk) + res.write(documentHead({ title: state.title || meta.title, ...meta.assets })) + if (!first.done) res.write(first.value) + for (;;) { + const { done, value } = await reader.read() + if (done) break + res.write(value) } res.end(documentTail(state)) } catch (err) { @@ -71,17 +95,46 @@ export default async function serve ({ outDir = 'dist', port = 8080 }) { if (!res.headersSent) res.writeHead(500, { 'content-type': 'text/plain' }) res.end('bankai: render error') } - }) + } + + let server + if (h2) { + const { key, cert } = await localCert(outDir) + server = http2.createSecureServer({ key, cert, allowHTTP1: true }, handler) + } else { + server = http.createServer(handler) + } await new Promise((resolveListen) => server.listen(port, resolveListen)) return { server, port: server.address().port, - origin: `http://localhost:${server.address().port}`, + origin: `${h2 ? 'https' : 'http'}://localhost:${server.address().port}`, close: () => new Promise((resolveClose) => server.close(resolveClose)) } } +// self-signed localhost cert, generated once via openssl and cached +// alongside the build (never commit dist) +async function localCert (outDir) { + const dir = join(outDir, '.bankai-cert') + const keyPath = join(dir, 'key.pem') + const certPath = join(dir, 'cert.pem') + if (!(await isFile(keyPath)) || !(await isFile(certPath))) { + await mkdir(dir, { recursive: true }) + await execFileP('openssl', [ + 'req', '-x509', '-newkey', 'rsa:2048', '-nodes', '-days', '365', + '-subj', '/CN=localhost', + '-addext', 'subjectAltName=DNS:localhost,IP:127.0.0.1', + '-keyout', keyPath, '-out', certPath + ]) + } + return { + key: await readFile(keyPath), + cert: await readFile(certPath) + } +} + async function isFile (path) { try { return (await stat(path)).isFile() @@ -90,8 +143,9 @@ async function isFile (path) { } } -async function sendFile (req, res, file, pathname) { +async function sendFile (req, res, file, pathname, extraHeaders = {}) { const headers = { + ...extraHeaders, 'content-type': MIME[extname(file)] || 'application/octet-stream', // hashed build assets are immutable; everything else revalidates 'cache-control': pathname.startsWith('/assets/') diff --git a/packages/bankai/test/build-serve.test.js b/packages/bankai/test/build-serve.test.js index 07d3c8b..adb1cb2 100644 --- a/packages/bankai/test/build-serve.test.js +++ b/packages/bankai/test/build-serve.test.js @@ -16,11 +16,11 @@ import serve from '../lib/serve.js' const repo = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..') const entry = join(repo, 'examples', 'counter', 'app.js') -let outDir, meta, srv +let outDir, meta, prerendered, srv before(async () => { outDir = await mkdtemp(join(tmpdir(), 'bankai-test-')) - ;({ meta } = await build({ entry, outDir, title: 'counter' })) + ;({ meta, prerendered } = await build({ entry, outDir, title: 'counter', prerender: ['/'] })) srv = await serve({ outDir, port: 0 }) }) @@ -58,16 +58,38 @@ test('build produced manifest, metadata and precompressed assets', async () => { await access(join(outDir, chunk.slice(1) + '.gz')) }) -test('pages get 103 Early Hints carrying the route assets', async () => { +test('the style.css convention bundles css the server never imports', async () => { + assert.strictEqual(meta.assets.css.length, 1, 'extracted css asset') + const res = await get('/some/page') + const text = res.body.toString() + assert.match(text, //) + assert.match(String(res.headers.link), /as=style/, 'stylesheet in the Link header') +}) + +test('prerendered routes are written and served statically with hints', async () => { + assert.deepStrictEqual(prerendered, ['/']) + await access(join(outDir, 'index.html')) const res = await get('/') + assert.strictEqual(res.status, 200) + assert.match(res.body.toString(), /count is 0/) + assert.strictEqual(res.interim[0]?.statusCode, 103, 'prerendered pages still send Early Hints') +}) + +test('the SSR comes from state (DOMTitleChange during render)', async () => { + const res = await get('/some/page') + assert.match(res.body.toString(), /<title>count is 0<\/title>/) +}) + +test('live pages get 103 Early Hints carrying the route assets', async () => { + const res = await get('/some/page') assert.strictEqual(res.interim.length, 1, 'one interim response') assert.strictEqual(res.interim[0].statusCode, 103) assert.match(String(res.interim[0].headers.link), /rel=modulepreload/) assert.match(String(res.headers.link), /rel=modulepreload/, 'Link header repeated on the final response') }) -test('pages stream SSR html with a filtered initialState tail', async () => { - const res = await get('/') +test('live pages stream SSR html with a filtered initialState tail', async () => { + const res = await get('/some/page') const text = res.body.toString() assert.strictEqual(res.status, 200) assert.match(text, /<h1>count is 0<\/h1>/, 'server-rendered view') @@ -76,6 +98,38 @@ test('pages stream SSR html with a filtered initialState tail', async () => { assert.ok(!/initialState=.*"events"/.test(text), 'internals filtered from state') }) +test('h2: HTTP/2 server sends Early Hints and streams the page', async (t) => { + const { default: http2 } = await import('node:http2') + let h2srv + try { + h2srv = await serve({ outDir, port: 0, h2: true }) + } catch (err) { + t.skip('openssl unavailable: ' + err.message) + return + } + + const session = http2.connect(`https://localhost:${h2srv.port}`, { rejectUnauthorized: false }) + const result = await new Promise((resolve, reject) => { + const req = session.request({ ':path': '/some/page' }) + let interim = null + let status = null + let body = '' + req.on('headers', (headers) => { interim = headers }) + req.on('response', (headers) => { status = headers[':status'] }) + req.on('data', (d) => { body += d }) + req.on('end', () => resolve({ interim, status, body })) + req.on('error', reject) + req.end() + }) + session.close() + await h2srv.close() + + assert.strictEqual(result.status, 200) + assert.strictEqual(result.interim?.[':status'], 103, '103 interim over h2') + assert.match(String(result.interim?.link), /rel=modulepreload/) + assert.match(result.body, /count is 0/) +}) + test('hashed assets are immutable and served precompressed on request', async () => { const chunk = meta.assets.scripts[0] diff --git a/scripts/size.js b/scripts/size.js new file mode 100644 index 0000000..3c7feeb --- /dev/null +++ b/scripts/size.js @@ -0,0 +1,64 @@ +// The size budget: what does the framework itself cost on the wire? +// Bundles @choojs/core + @choojs/html (browser condition) minified via +// the same Vite/Rolldown pipeline apps use, then reports min+gzip and +// min+brotli. CI fails if min+gzip exceeds the budget. +// +// npm run size + +import { build } from 'vite' +import { readFile, readdir, rm, mkdtemp } from 'node:fs/promises' +import { join } from 'node:path' +import { tmpdir } from 'node:os' +import { gzipSync, brotliCompressSync, constants } from 'node:zlib' + +// The promise the README makes; raise only with a paper trail. +// Context: v7's "4kb" was choo alone — nanohtml lived in the browserify +// transform. This number is the whole framework: core, html engine, +// morph, hydrate, router, bus. Currently ~7.97 kB gzip; the headroom is +// margin, not license. +const BUDGET_GZIP = 8.5 * 1024 + +const VIRTUAL = '\0size:entry' + +const outDir = await mkdtemp(join(tmpdir(), 'choo-size-')) +await build({ + appType: 'custom', + logLevel: 'error', + plugins: [{ + name: 'size-entry', + resolveId: (id) => id === 'size:entry' ? VIRTUAL : undefined, + load: (id) => id === VIRTUAL + ? "import choo, { Choo, lazy } from '@choojs/core'\n" + + "import html from '@choojs/html'\n" + + "import raw from '@choojs/html/raw'\n" + + 'window.__keep = { choo, Choo, lazy, html, raw }\n' + : undefined + }], + build: { + outDir, + emptyOutDir: true, + rollupOptions: { input: { framework: 'size:entry' } } + } +}) + +const assets = await readdir(join(outDir, 'assets')) +const file = assets.find((name) => name.endsWith('.js')) +const code = await readFile(join(outDir, 'assets', file)) +await rm(outDir, { recursive: true, force: true }) + +const gz = gzipSync(code, { level: constants.Z_BEST_COMPRESSION }).length +const br = brotliCompressSync(code, { + params: { [constants.BROTLI_PARAM_QUALITY]: constants.BROTLI_MAX_QUALITY } +}).length + +const kb = (n) => (n / 1024).toFixed(2) + ' kB' +console.log(`@choojs/core + @choojs/html (browser, minified)`) +console.log(` raw: ${kb(code.length)}`) +console.log(` gzip: ${kb(gz)} (budget ${kb(BUDGET_GZIP)})`) +console.log(` brotli: ${kb(br)}`) + +if (gz > BUDGET_GZIP) { + console.error(`\nsize budget exceeded: ${kb(gz)} > ${kb(BUDGET_GZIP)} min+gzip`) + process.exit(1) +} +console.log('\nwithin budget ✔')