@transclude/core 0.7.0 → 0.8.2

package/README.md

@@ -15,6 +15,9 @@
   <a href="https://github.com/transclude-dev/transclude/blob/main/LICENSE"
     ><img alt="MIT" src="https://img.shields.io/npm/l/%40transclude%2Fcore?color=0b7285"
   /></a>
+  <a href="https://bsky.app/profile/transclude.dev" rel="me"
+    ><img alt="Bluesky" src="https://img.shields.io/badge/Bluesky-transclude.dev-0b7285"
+  /></a>
 </p>
 
 HTML is the product. A page is an `.html` file, the directory tree is the route
@@ -23,7 +26,10 @@ table, and any fragment of a page is a URL of its own.
 The same app runs on Node, Bun, Deno and workerd, the runtime behind
 Cloudflare Workers, and ships no client JavaScript by default.
 
-**[transclude.dev](https://transclude.dev)** has the documentation.
+**[transclude.dev](https://transclude.dev)** has the documentation, and
+[every example is running](https://transclude.dev/docs/examples).
+[todomvc.transclude.dev](https://todomvc.transclude.dev) ships zero bytes of
+JavaScript, which is easier to believe with the page open.
 
 ```sh
 npm create @transclude my-app
@@ -127,15 +133,23 @@ npm run check:src     # type-check the framework itself
 ```
 
 `examples/` holds apps built against this package the same way any other project
-would be. `todomvc` is TodoMVC with forms and no client JavaScript, `blog` is a
-prerendered site with a sitemap and a feed, `search` swaps a fragment into a
-page that works without it, `htmx` does the same with htmx and the
-`HX-Target` header, `includes` shows transclusion from three sources,
-`auth` guards a section with a layout and a signed cookie, `live` pushes
-updates over server-sent events, `elements` puts a light and a shadow element
-side by side, and `showcase` uses every feature and is where the
-browser checks live, because those need an app to run against. `www/` is the site at transclude.dev: a landing page, the
-documentation under `/docs`, and itself built with the framework.
+would be. Every one of them is deployed, from the same source you would clone.
+
+| Example | What it proves | Running |
+| --- | --- | --- |
+| `todomvc` | Seven actions, one POST handler, zero bytes of JavaScript | [todomvc.transclude.dev](https://todomvc.transclude.dev) |
+| `search` | A fragment that is a substring of the document it came from | [search.transclude.dev](https://search.transclude.dev) |
+| `blog` | Markdown to files, with a sitemap and a feed | [blog.transclude.dev](https://blog.transclude.dev) |
+| `htmx` | htmx and this framework, each doing its own half | [htmx.transclude.dev](https://htmx.transclude.dev) |
+| `includes` | One piece of markup rendered in more than one place | [includes.transclude.dev](https://includes.transclude.dev) |
+| `auth` | A section behind a layout and a signed cookie | [auth.transclude.dev](https://auth.transclude.dev) |
+| `live` | Server-sent events into a fragment | [live.transclude.dev](https://live.transclude.dev) |
+| `elements` | A light element and a shadow one, side by side | [elements.transclude.dev](https://elements.transclude.dev) |
+| `showcase` | Every feature at once, and where the browser checks live | [showcase.transclude.dev](https://showcase.transclude.dev) |
+
+The browser checks are in `showcase` because they need an app to run against.
+`www/` is the site at transclude.dev: a landing page, the documentation under
+`/docs`, the writing under `/blog`, and itself built with the framework.
 
 ### Trying the CLI against this checkout
 

package/bin/dev.js

@@ -28,6 +28,10 @@ import { cookiesOf } from '../src/cookies.js';
 import { loadProject, portOf } from '../src/project.js';
 import { includeContext } from '../src/include.js';
 import { nodeLookup } from '../src/lookup.js';
+import { feed, feedPath, feedType } from '../src/feed.js';
+import { sitemap } from '../src/sitemap.js';
+import { documentStore, PROXY_PATH, proxyHandler } from '../src/proxy.js';
+import { afterFor } from '../src/after.js';
 
 const { root, config } = await loadProject();
 const routesDir = resolveRoutesDir(path.join(root, config.appDir), config.routesDir);
@@ -139,6 +143,17 @@ const contextFor = (route, c, extra = {}) => ({
   // is right for a form, and wrong for a caller that asked for markup.
   fragment: fragmentOf(c),
   action: null,
+
+  // Nothing is held between requests here, so there is nothing to drop. A
+  // no-op rather than an omission: an action calling this is correct code, and
+  // it should not throw in dev and work in production.
+  revalidateTag: () => {},
+
+  // Node keeps running after a response, so this only has to handle the
+  // rejection. `console.error` rather than `config.onError`, which the dev
+  // server does not use for anything else either.
+  after: afterFor(c, (error) => console.error('[transclude] ctx.after:', error)),
+
   ...withResponse(c, extra),
 });
 
@@ -312,6 +327,49 @@ async function buildApp() {
     });
   }
 
+  // Before the route table, the same way production registers them, so a
+  // catch-all route cannot answer for one of these.
+  //
+  // They were missing here entirely. `createApp` mounts them and the dev server
+  // builds its own app, so `/feed.xml` and `/sitemap.xml` were 404 in dev and
+  // correct in the build. That is the worst shape a difference can take: the
+  // thing you check by hand is the thing that was never wired.
+  if (config.sitemap) {
+    app.get('/sitemap.xml', async (c) => {
+      // Only a parameter route ever reads its module, for `paths`. Loading the
+      // rest would compile the whole site to answer one request.
+      const pages = {};
+      for (const route of routes) {
+        if (route.params.length) pages[route.id] = await vite.ssrLoadModule(pageModuleId(route.id));
+      }
+
+      const xml = await sitemap({ routes }, pages, config.sitemap, c.req.query('p') ?? null);
+      return c.body(xml, 200, { 'Content-Type': 'application/xml; charset=utf-8' });
+    });
+  }
+
+  if (config.feed) {
+    app.get(feedPath(config.feed), async (c) => {
+      const xml = await feed(config.feed);
+      return c.body(xml, 200, { 'Content-Type': feedType(config.feed) });
+    });
+  }
+
+  // The browser calls this one, so a page using an external include worked in
+  // the build and 404ed here. Default deny is the config's doing either way: no
+  // `proxy` key, no route.
+  //
+  // `/precache.json` is deliberately not here. It names hashed asset filenames,
+  // which only the build knows, and a service worker holding anything in dev is
+  // a bug rather than a feature. It is build output and stays that way.
+  if (config.proxy) {
+    const handler = proxyHandler(config.proxy, {
+      lookup: config.proxy.lookup ?? nodeLookup(),
+      store: documentStore(config.proxy.cache),
+    });
+    app.get(PROXY_PATH, (c) => handler(c.req.raw));
+  }
+
   // Already ordered most-specific first, so registration order is deterministic
   // rather than something to reason about per-router.
   for (const route of routes) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transclude/core",
-  "version": "0.7.0",
+  "version": "0.8.2",
   "description": "An HTML-first server framework. A page is an .html file, the directory tree is the route table, and any fragment of a page is a URL of its own. Runs on Node, Bun, Deno and workerd, and ships no client JavaScript by default.",
   "keywords": [
     "html",

package/skills/transclude/references/server.md

@@ -154,6 +154,23 @@ something built on Wasm fails there and nowhere else. A prerendered page never
 runs its loader in production, so this stays hidden until something asks for a
 fragment.
 
+### worker.js
+
+```js
+import { workerFrom } from '@transclude/core/worker';
+import * as bundle from './dist/server/assets.js';
+import * as entry from './dist/server/entry.js';
+import manifest from './dist/routes.json';
+import config from './transclude.config.js';
+
+export default workerFrom({ config, manifest, entry, bundle });
+```
+
+The imports stay in the app: a bundler needs a literal path. `workerFrom` builds
+the app on the first request, which is when `env` exists, and takes
+`cookieSecret` from `env.COOKIE_SECRET`. For anything else, call `createApp`
+from `@transclude/core/app` directly.
+
 ### Bindings
 
 `ctx` has no `env`. It carries nothing that names one runtime, and `env` names
@@ -165,12 +182,18 @@ import that.
 
 ```js
 // app/lib/bindings.js — no `node:` imports, this ends up in the worker bundle
-/** @type {Env|null} */
-let current = null;
-
-export const hold = (env) => (current = env);
+// A symbol in the global registry, not a module variable. The build inlines a
+// copy of this file into the server bundle and wrangler bundles `worker.js`
+// with a second one, so a module variable is written in one copy and read in
+// the other.
+const SLOT = Symbol.for('app.bindings');
+
+export const hold = (env) => {
+  globalThis[SLOT] = env;
+};
 
 export const bindings = () => {
+  const current = globalThis[SLOT];
   if (!current) throw new Error('No bindings: this app is running off workerd.');
   return current;
 };

package/src/app.js

@@ -30,6 +30,7 @@ import { pickEncoding } from './negotiate.js';
 import { baseApp, endpointMethods, runEndpoint } from './server.js';
 import { cookiesOf } from './cookies.js';
 import { afterFor } from './after.js';
+import { withDefaults } from './defaults.js';
 
 const IMMUTABLE = 'public, max-age=31536000, immutable';
 const REVALIDATE = 'public, max-age=0, must-revalidate';
@@ -143,7 +144,11 @@ function isShareable(html, ctx) {
  * @returns {object} a Hono app, ready to serve
  */
 export function createApp({
-  config,
+  // Filled in here rather than by the caller, because only one of the four
+  // runtimes has a `loadProject` to fill them in on the way. A worker imports
+  // `transclude.config.js` and hands over exactly what the author wrote, so
+  // every key they left out was undefined until this line.
+  config: written,
   manifest,
   pages,
   endpoints = {},
@@ -164,6 +169,7 @@ export function createApp({
   // it the proxy's allowlist is the whole defense.
   lookup = null,
 }) {
+  const config = withDefaults(written);
   const cache = createCache(config.cache);
 
   // One resolver for the app, so several pages including the same document read

package/src/compiler/index.js

@@ -91,6 +91,25 @@ export function readFlags(source, label = 'element') {
   return resolveFlags(fromProps, fromClient, label);
 }
 
+/**
+ * Script types the browser executes. Everything else is a data block.
+ *
+ * The list is the HTML spec's, minus the legacy spellings nobody writes. An
+ * absent `type` is a classic script, `module` is a module, and both are code.
+ * `importmap` is not executed either, but the browser reads it, which is the
+ * same reason to emit it rather than compile it.
+ *
+ * @param {{ attrs?: Array<{ name: string, value: string }> }} node
+ * @returns {boolean} whether this script holds data rather than code
+ */
+function isDataBlock(node) {
+  const type = node.attrs?.find((attr) => attr.name === 'type')?.value;
+  if (type === undefined) return false;
+
+  const JS = ['', 'module', 'text/javascript', 'application/javascript'];
+  return !JS.includes(type.trim().toLowerCase());
+}
+
 /**
  * Top-level <script>/<style> blocks are pulled out; everything else is template.
  *
@@ -162,6 +181,12 @@ export function splitBlocks(source) {
       // with nothing said. A nested `<script src>` was always markup; only a
       // top-level one went missing.
       else if (attrs.has('src')) out.nodes.push(node);
+      // A type the browser does not run as JavaScript makes this a data block,
+      // which is markup for the same reason a `src` is: there is no code here to
+      // compile. Import maps, JSON-LD, speculation rules written by hand and
+      // whatever a library reads out of the document were all swallowed, because
+      // anything without a marker was read as a client module.
+      else if (isDataBlock(node)) out.nodes.push(node);
       else out.client.push(block);
       continue;
     }

package/src/cookies.js

@@ -39,6 +39,21 @@ export function cookiesOf(request, response, secret = null) {
 
   const requireSecret = (what) => {
     if (secret) return secret;
+
+    // Set-but-empty is worth its own sentence. It happened on a real deploy:
+    // `wrangler secret put` took a blank line, so the binding existed, every
+    // `typeof` along the way said `string`, and the config carried it all the
+    // way here. The only thing that said otherwise was the length. Reading
+    // "needs a secret" while looking at a secret that is plainly set sends you
+    // hunting through the wiring instead of the value.
+    if (typeof secret === 'string') {
+      throw new Error(
+        `[transclude] ${what} needs a secret, and \`cookieSecret\` is set to an ` +
+          `empty string. Whatever supplies it handed over nothing: on a worker that ` +
+          `is usually a \`wrangler secret put\` that took a blank line`,
+      );
+    }
+
     throw new Error(
       `[transclude] ${what} needs a secret. Set \`cookieSecret\` in ` +
         `transclude.config.js (read it from the environment there, not from a literal)`,

package/src/defaults.js

@@ -0,0 +1,51 @@
+// What a config means when it does not say.
+//
+// Split out of `project.js` because that file reads a disk and this has to run
+// where there is no disk. `loadProject` is Node's way in, and a worker has no
+// equivalent: it imports `transclude.config.js` directly, so the object reaching
+// `createApp` there is exactly what the author wrote and nothing more.
+//
+// That gap was live for a while. `fragmentParam` was only ever filled in by
+// `loadProject`, so on workerd `config.fragmentParam` was undefined, the check
+// for it read as "no parameter configured", and every `?fragment=` request was
+// answered with the whole document. A swap then wrote a second copy of the page
+// into the element it was meant to replace. It looked like a compiler bug and it
+// was a missing default.
+//
+// Applied in `createApp` rather than in each entry, so there is one place and no
+// runtime can skip it.
+//
+// No `node:` imports.
+
+/** Every key with a value, and the value it takes when the config is quiet. */
+export const DEFAULTS = {
+  appDir: 'app',
+  routesDir: 'routes',
+  elementsDir: 'elements',
+  publicDir: 'public',
+  iconsDir: 'icons',
+  outDir: 'dist',
+  typesFile: 'app/transclude-env.d.ts',
+  stylesheet: null,
+  lang: 'en',
+  fragmentParam: 'fragment',
+  trailingSlash: 'never',
+  strict: false,
+  csrf: true,
+  csp: false,
+  speculate: false,
+};
+
+/**
+ * A config with every default filled in.
+ *
+ * A key the author wrote wins, including one written as `null` or `false`. Only
+ * an absent key takes the default, which is what lets `fragmentParam: null` turn
+ * the parameter off rather than quietly turning it back on.
+ *
+ * @param {object} [config] whatever `transclude.config.js` exported
+ * @returns {object} the same keys, plus the ones it did not mention
+ */
+export function withDefaults(config = {}) {
+  return { ...DEFAULTS, ...config };
+}

package/src/project.js

@@ -11,6 +11,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { withDefaults } from './defaults.js';
 
 export const CONFIG_FILE = 'transclude.config.js';
 
@@ -80,24 +81,11 @@ export function findRoot(from = process.cwd()) {
  *
  * `port` is not here. `portOf` already answers it, and it reads the environment
  * first, which a plain default cannot do.
+ *
+ * They live in `defaults.js` rather than here, because a worker has no
+ * `loadProject` and needs the same answers. `createApp` applies them for every
+ * runtime, and this file is only Node's way in.
  */
-const DEFAULTS = {
-  appDir: 'app',
-  routesDir: 'routes',
-  elementsDir: 'elements',
-  publicDir: 'public',
-  iconsDir: 'icons',
-  outDir: 'dist',
-  typesFile: 'app/transclude-env.d.ts',
-  stylesheet: null,
-  lang: 'en',
-  fragmentParam: 'fragment',
-  trailingSlash: 'never',
-  strict: false,
-  csrf: true,
-  csp: false,
-  speculate: false,
-};
 
 /**
  * The root and its config together, because nothing needs one without the other.
@@ -117,7 +105,7 @@ export async function loadProject(from = process.cwd()) {
     throw new Error(`[transclude] ${CONFIG_FILE} must export a config object as its default`);
   }
   assertNoSplitDirs(config, file);
-  return { root, config: { ...DEFAULTS, ...config }, configFile: file };
+  return { root, config: withDefaults(config), configFile: file };
 }
 
 /**

package/src/worker.js

@@ -5,6 +5,8 @@
 // is WebCrypto and therefore async. Those are runtime facts, so they live here.
 // Which modules to import is an app fact, so that stays in the app's own entry.
 
+import { createApp } from './app.js';
+
 /** base64 in, bytes out. `atob` is in every runtime that has no `Buffer`. */
 const decode = (base64) => Uint8Array.from(atob(base64), (c) => c.charCodeAt(0));
 
@@ -85,3 +87,58 @@ export async function hash(body) {
   for (const byte of bytes) base64 += String.fromCharCode(byte);
   return `"${btoa(base64).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '').slice(0, 20)}"`;
 }
+
+/**
+ * The whole worker, for an app that wants the ordinary wiring.
+ *
+ * Nine apps in this repository wrote the same forty lines: parse the manifest,
+ * wrap each byte map, build the app on the first request because that is when
+ * `env` exists, and hand the request on. The imports have to stay in the app's
+ * own file, because a bundler needs a literal path to follow. The wiring does
+ * not, and this is it.
+ *
+ * `cookieSecret` comes from `env.COOKIE_SECRET` when there is one, which is the
+ * only piece of config a worker cannot read at import time. An app needing
+ * something else calls `createApp` itself: this covers the common shape rather
+ * than every shape.
+ *
+ * @param {object} options
+ * @param {object} options.config the app's `transclude.config.js`
+ * @param {string|object} options.manifest `dist/routes.json`, text or parsed
+ * @param {object} options.entry everything `dist/server/entry.js` exports
+ * @param {object} options.bundle everything `dist/server/assets.js` exports
+ * @returns {{ fetch: (request: Request, env: object, ctx: object) => Response|Promise<Response> }}
+ */
+export function workerFrom({ config, manifest, entry, bundle }) {
+  // Built on the first request rather than at import, because that is when
+  // `env` exists. There is no `process.env` here, so a secret read any earlier
+  // is undefined, and signing refuses.
+  let app = null;
+
+  return {
+    fetch(request, env, ctx) {
+      app ??= createApp({
+        config: { ...config, cookieSecret: env.COOKIE_SECRET ?? config.cookieSecret },
+        // There is no JSON module type in Workers, so the manifest usually
+        // arrives as a string. Used as an object it gives a route table of
+        // `undefined` and a site of 404s that looks exactly like a routing bug.
+        manifest: typeof manifest === 'string' ? JSON.parse(manifest) : manifest,
+        pages: entry.pages,
+        endpoints: entry.endpoints,
+        middleware: entry.middleware,
+        statics: bytesFrom(bundle.statics),
+        assets: bytesFrom(bundle.assets),
+        publicFiles: fileHandler(bundle.publicFiles),
+        notFound: pageEntry(bundle.notFound),
+        errorPage: pageEntry(bundle.errorPage),
+        hash,
+        // The edge compresses. Doing it here would be a second pass over bytes
+        // already going through one.
+        compress: null,
+        precache: bundle.precache,
+      });
+
+      return app.fetch(request, env, ctx);
+    },
+  };
+}