@transclude/create 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joe Dakroub
+
+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/index.js

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+// Starts a project. `npm create transclude my-app`, or `npx create-transclude`.
+//
+// It copies a template and rewrites three things: the package name, the
+// dependency on this framework, and the title on the page. Nothing else is
+// generated, so what lands is what is in `templates/`, and reading that
+// directory tells you exactly what a new project is.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
+
+// `fileURLToPath`, never `url.pathname`: a space in the path stays
+// percent-encoded in the second one, and `Atelier%20Dakroub` is not a directory.
+const root = path.dirname(fileURLToPath(import.meta.url));
+const templates = path.join(root, 'templates');
+
+const TEMPLATES = [
+  { name: 'minimal', what: 'a layout, two pages, a 404 and a stylesheet' },
+  { name: 'blank', what: 'one page, and nothing else' },
+];
+
+/** npm refuses some of what a directory name allows, and so does this. */
+const NAME = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+
+function usage() {
+  const list = TEMPLATES.map((t) => `    ${t.name.padEnd(9)} ${t.what}`).join('\n');
+  return [
+    'Usage: create-transclude [directory] [options]',
+    '',
+    '  --template <name>  which files to start from',
+    `${list}`,
+    '  --yes              take the defaults and ask nothing',
+    '  --link             depend on a local checkout, for working on the framework',
+    '',
+  ].join('\n');
+}
+
+/** Arguments, in the shape the rest of the file wants them. */
+function parse(argv) {
+  const options = { dir: null, template: null, yes: false, link: false };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--yes' || arg === '-y') options.yes = true;
+    else if (arg === '--link') options.link = true;
+    else if (arg === '--help' || arg === '-h') options.help = true;
+    else if (arg === '--template' || arg === '-t') options.template = argv[++i];
+    else if (arg.startsWith('--template=')) options.template = arg.slice('--template='.length);
+    else if (arg.startsWith('-')) throw new Error(`unknown option ${arg}`);
+    else if (options.dir === null) options.dir = arg;
+    else throw new Error(`unexpected argument ${arg}`);
+  }
+  return options;
+}
+
+/**
+ * Every file under `dir`, relative to it.
+ *
+ * `node_modules` and `dist` are skipped so running this from a directory that
+ * was used once does not copy a build into a new project.
+ */
+function walk(dir, base = dir, out = []) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name === 'dist') continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walk(full, base, out);
+    else out.push(path.relative(base, full));
+  }
+  return out;
+}
+
+/**
+ * What a directory can be written into.
+ *
+ * An existing directory is fine when it holds nothing that would be
+ * overwritten; a `.git` from `git init` is the ordinary case. Anything else is
+ * refused rather than merged, because a half-copied project is worse to
+ * untangle than one that never started.
+ */
+function checkTarget(dir) {
+  if (!fs.existsSync(dir)) return;
+  const held = fs.readdirSync(dir).filter((name) => name !== '.git' && name !== '.DS_Store');
+  if (held.length) {
+    throw new Error(`${path.relative(process.cwd(), dir) || '.'} is not empty`);
+  }
+}
+
+/**
+ * What a new project declares.
+ *
+ * `--link` points at a checkout of the framework, which is the only way to try
+ * an unpublished one: the version below is this package's, and the two are
+ * released together.
+ */
+function dependency(link) {
+  if (link) return `file:${path.resolve(root, '..')}`;
+  const { version } = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+  return `^${version}`;
+}
+
+async function ask(options) {
+  // A pipe is not a person. Without a terminal the defaults are the only answers
+  // available, and hanging on a prompt nobody can see is the worse failure.
+  if (options.yes || !process.stdin.isTTY) {
+    return { dir: options.dir ?? 'my-app', template: options.template ?? TEMPLATES[0].name };
+  }
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    let dir = options.dir;
+    while (!dir) dir = (await rl.question('Directory (my-app): ')).trim() || 'my-app';
+
+    let template = options.template;
+    if (!template) {
+      const names = TEMPLATES.map((t) => t.name).join(', ');
+      const answer = (await rl.question(`Template (${names}) [minimal]: `)).trim();
+      template = answer || TEMPLATES[0].name;
+    }
+    return { dir, template };
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * Copies one template, substituting the two placeholders.
+ *
+ * Only `.json`, `.js`, `.html`, `.css` and `.md` are read as text. Anything else
+ * is copied byte for byte, so a template may hold an image without this
+ * corrupting it.
+ */
+function copy(from, to, replacements) {
+  const TEXT = new Set(['.json', '.js', '.html', '.css', '.md', '.txt']);
+
+  for (const rel of walk(from)) {
+    // `.gitignore` in a template would be applied to the template itself by
+    // every tool that reads one, including npm when this is packed.
+    const target = path.join(to, rel === '_gitignore' ? '.gitignore' : rel);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+
+    if (!TEXT.has(path.extname(rel))) {
+      fs.copyFileSync(path.join(from, rel), target);
+      continue;
+    }
+
+    let text = fs.readFileSync(path.join(from, rel), 'utf8');
+    for (const [token, value] of Object.entries(replacements)) {
+      text = text.split(token).join(value);
+    }
+    fs.writeFileSync(target, text);
+  }
+}
+
+async function main() {
+  const options = parse(process.argv.slice(2));
+  if (options.help) {
+    process.stdout.write(usage());
+    return;
+  }
+
+  const answers = await ask(options);
+  const template = TEMPLATES.find((t) => t.name === answers.template);
+  if (!template) {
+    const names = TEMPLATES.map((t) => t.name).join(', ');
+    throw new Error(`no template called ${JSON.stringify(answers.template)}. There is ${names}.`);
+  }
+
+  const target = path.resolve(process.cwd(), answers.dir);
+  checkTarget(target);
+
+  const name = path.basename(target);
+  if (!NAME.test(name)) {
+    throw new Error(`${JSON.stringify(name)} is not a usable package name`);
+  }
+
+  copy(path.join(templates, template.name), target, {
+    __NAME__: name,
+    __TRANSCLUDE__: dependency(options.link),
+  });
+
+  const where = path.relative(process.cwd(), target);
+  process.stdout.write(
+    [
+      `\nCreated ${name} from the ${template.name} template.\n\n`,
+      where ? `  cd ${where}\n` : '',
+      '  npm install\n',
+      '  npm run dev\n\n',
+    ].join(''),
+  );
+}
+
+main().catch((error) => {
+  process.stderr.write(`\n${error.message}\n\n${usage()}`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@transclude/create",
+  "version": "0.1.0",
+  "description": "Starts a transclude project. `npm create @transclude my-app`.",
+  "keywords": [
+    "transclude",
+    "scaffold",
+    "starter",
+    "create"
+  ],
+  "homepage": "https://transclude.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/transclude-dev/transclude.git",
+    "directory": "create"
+  },
+  "bugs": {
+    "url": "https://github.com/transclude-dev/transclude/issues"
+  },
+  "license": "MIT",
+  "author": "Joe Dakroub",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "create-transclude": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "templates",
+    "LICENSE"
+  ]
+}

package/templates/blank/README.md

@@ -0,0 +1,19 @@
+# __NAME__
+
+```sh
+npm install
+npm run dev
+```
+
+A page is an `.html` file in `app/routes/`. The directory tree is the route
+table, so `app/routes/about.html` answers `/about`.
+
+| | |
+| --- | --- |
+| `npm run dev` | the dev server, with hot reload |
+| `npm run check` | types, from the shapes your loaders return |
+| `npm run preview` | build, then serve the build |
+| `npm run build` | write `dist/` |
+
+`dist/static` is self-contained: any static host will serve it. Everything that
+reads a request is served by `npm start`.

package/templates/blank/_gitignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+.env
+.env.*
+!.env.example
+.DS_Store

package/templates/blank/app/routes/index.html

@@ -0,0 +1,4 @@
+<title>__NAME__</title>
+
+<h1>__NAME__</h1>
+<p>Edit <code>app/routes/index.html</code> and this changes.</p>

package/templates/blank/app/styles/global.css

@@ -0,0 +1,10 @@
+/* Linked by every page. It goes through Vite, so nesting and @import work, and
+   the build hashes and compresses it. */
+
+body {
+  margin: 0 auto;
+  padding: 2rem 1rem;
+  max-width: 42rem;
+  font: 16px/1.6 system-ui, sans-serif;
+  color-scheme: light dark;
+}

package/templates/blank/jsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "lib": ["esnext", "dom", "dom.iterable"],
+    "checkJs": false,
+    "noEmit": true
+  },
+  "include": ["app", "transclude.config.js"]
+}

package/templates/blank/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "__NAME__",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "node --env-file-if-exists=.env node_modules/.bin/transclude-dev",
+    "build": "transclude-build",
+    "start": "node --env-file-if-exists=.env node_modules/.bin/transclude-serve",
+    "preview": "npm run build && npm start",
+    "check": "transclude-check"
+  },
+  "dependencies": {
+    "@transclude/core": "__TRANSCLUDE__"
+  },
+  "devDependencies": {
+    "typescript": "^5.9",
+    "vite": "^8"
+  }
+}

package/templates/blank/transclude.config.js

@@ -0,0 +1,27 @@
+// Every path the framework needs is here, relative to `appDir` unless it says
+// otherwise. `npx transclude-check` reads this too.
+//
+// The keys left out have defaults, and the defaults are the quiet ones: no
+// proxy, no feed, no sitemap, no service worker list, no script on any page.
+// See the configuration page in the docs for the whole list.
+
+export default {
+  appDir: 'app',
+  routesDir: 'routes',
+  elementsDir: 'elements',
+  stylesheet: 'app/styles/global.css',
+
+  // Dev and production both listen here, so this app has one port. `PORT` in the
+  // environment wins.
+  port: 1960,
+
+  // `never` redirects /about/ to /about with a 301, so a page has one URL.
+  trailingSlash: 'never',
+
+  // Signs cookies, which is what makes one usable as a session. Read it from the
+  // environment: this file is yours, so where the secret lives is your decision.
+  cookieSecret: globalThis.process?.env?.COOKIE_SECRET ?? null,
+
+  outDir: 'dist',
+  typesFile: 'app/transclude-env.d.ts',
+};

package/templates/blank/vite.config.js

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vite';
+import transclude from '@transclude/core';
+import config from './transclude.config.js';
+
+export default defineConfig({
+  appType: 'custom',
+  plugins: [transclude(config)],
+});

package/templates/minimal/README.md

@@ -0,0 +1,20 @@
+# __NAME__
+
+```sh
+npm install
+npm run dev
+```
+
+A page is an `.html` file in `app/routes/`. The directory tree is the route
+table, so `app/routes/about.html` answers `/about`. `_layout.html` wraps every
+page beside it and below.
+
+| | |
+| --- | --- |
+| `npm run dev` | the dev server, with hot reload |
+| `npm run check` | types, from the shapes your loaders return |
+| `npm run preview` | build, then serve the build |
+| `npm run build` | write `dist/` |
+
+`dist/static` is self-contained: any static host will serve it. Everything that
+reads a request is served by `npm start`.

package/templates/minimal/_gitignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+.env
+.env.*
+!.env.example
+.DS_Store

package/templates/minimal/app/public/robots.txt

@@ -0,0 +1,2 @@
+User-agent: *
+Allow: /

package/templates/minimal/app/routes/404.html

@@ -0,0 +1,4 @@
+<title>Not found</title>
+
+<h1>Not found</h1>
+<p>No page has that address. <a href="/">Back to the start</a>.</p>

package/templates/minimal/app/routes/_layout.html

@@ -0,0 +1,16 @@
+<script server>
+  // A layout wraps every page in its directory and below. This one takes the
+  // current path so it can mark the link you are on.
+  export default async ({ route }) => ({ path: route.path });
+</script>
+
+<title>__NAME__</title>
+
+<nav>
+  <a href="/" aria-current="${path === '/' ? 'page' : 'false'}">Home</a>
+  <a href="/about" aria-current="${path === '/about' ? 'page' : 'false'}">About</a>
+</nav>
+
+<!-- The page renders here. A layout with no <slot> is a warning, because
+     nothing inside it could appear. -->
+<main><slot></slot></main>

package/templates/minimal/app/routes/about.html

@@ -0,0 +1,4 @@
+<title>About</title>
+
+<h1>About</h1>
+<p>A second page, so the nav has somewhere to go.</p>

package/templates/minimal/app/routes/index.html

@@ -0,0 +1,4 @@
+<title>Home</title>
+
+<h1>__NAME__</h1>
+<p>Edit <code>app/routes/index.html</code> and this changes.</p>

package/templates/minimal/app/styles/global.css

@@ -0,0 +1,24 @@
+/* Linked by every page. It goes through Vite, so nesting and @import work, and
+   the build hashes and compresses it. */
+
+:root {
+  --muted: #666;
+  color-scheme: light dark;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root { --muted: #999; }
+}
+
+body {
+  margin: 0 auto;
+  padding: 2rem 1rem;
+  max-width: 42rem;
+  font: 16px/1.6 system-ui, sans-serif;
+}
+
+h1 { font-size: 1.6rem; margin: 0 0 1rem; }
+a { color: inherit; }
+
+nav { display: flex; gap: 1rem; margin-bottom: 2rem; }
+nav a[aria-current='page'] { font-weight: 600; }

package/templates/minimal/jsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "lib": ["esnext", "dom", "dom.iterable"],
+    "checkJs": false,
+    "noEmit": true
+  },
+  "include": ["app", "transclude.config.js"]
+}

package/templates/minimal/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "__NAME__",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "node --env-file-if-exists=.env node_modules/.bin/transclude-dev",
+    "build": "transclude-build",
+    "start": "node --env-file-if-exists=.env node_modules/.bin/transclude-serve",
+    "preview": "npm run build && npm start",
+    "check": "transclude-check"
+  },
+  "dependencies": {
+    "@transclude/core": "__TRANSCLUDE__"
+  },
+  "devDependencies": {
+    "typescript": "^5.9",
+    "vite": "^8"
+  }
+}

package/templates/minimal/transclude.config.js

@@ -0,0 +1,27 @@
+// Every path the framework needs is here, relative to `appDir` unless it says
+// otherwise. `npx transclude-check` reads this too.
+//
+// The keys left out have defaults, and the defaults are the quiet ones: no
+// proxy, no feed, no sitemap, no service worker list, no script on any page.
+// See the configuration page in the docs for the whole list.
+
+export default {
+  appDir: 'app',
+  routesDir: 'routes',
+  elementsDir: 'elements',
+  stylesheet: 'app/styles/global.css',
+
+  // Dev and production both listen here, so this app has one port. `PORT` in the
+  // environment wins.
+  port: 1960,
+
+  // `never` redirects /about/ to /about with a 301, so a page has one URL.
+  trailingSlash: 'never',
+
+  // Signs cookies, which is what makes one usable as a session. Read it from the
+  // environment: this file is yours, so where the secret lives is your decision.
+  cookieSecret: globalThis.process?.env?.COOKIE_SECRET ?? null,
+
+  outDir: 'dist',
+  typesFile: 'app/transclude-env.d.ts',
+};

package/templates/minimal/vite.config.js

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vite';
+import transclude from '@transclude/core';
+import config from './transclude.config.js';
+
+export default defineConfig({
+  appType: 'custom',
+  plugins: [transclude(config)],
+});