@jxsuite/create 1.6.0 → 1.8.0

package/README.md

@@ -39,13 +39,13 @@ Two disjoint id namespaces feed `--template`. A **built-in template id wins**; o
 | `mobile-first`  | Same files, mobile-first `$media` (min-width queries, 375px base)                     |
 | `mobile-app`    | Mobile-first `$media`, `viewport-fit=cover`, a `theme-color` meta, and a file overlay |
 
-`template/` (singular) is the shared skeleton copied on every non-starter scaffold: `gitignore` → `.gitignore`, `layouts/`, `pages/`. `templates/` (plural) holds per-template overlay trees copied **after** the skeleton with `force: true`, and today contains exactly one: `mobile-app/`, which replaces `layouts/base.json` with an app shell (bottom nav bar, safe-area insets) and `pages/index.md` with an app-flavored home page, and adds `pages/explore.md` and `pages/profile.md`. So `blank`, `desktop-first` and `mobile-first` differ only in the generated `project.json` (zero file differences). Breakpoint maps live in `templates.ts` (`mediaForTemplate`).
+`template/` (singular) is the shared skeleton copied on every non-starter scaffold: `gitignore` → `.gitignore`, `layouts/`, `pages/`. `templates/` (plural) holds per-template overlay trees copied **after** the skeleton with `force: true`, and today contains exactly one: `mobile-app/`, which replaces `layouts/base.jxn` with an app shell (bottom nav bar, safe-area insets) and `pages/index.md` with an app-flavored home page, and adds `pages/explore.md` and `pages/profile.md`. So `blank`, `desktop-first` and `mobile-first` differ only in the generated `project.json` (zero file differences). Breakpoint maps live in `templates.ts` (`mediaForTemplate`).
 
 Starter ids come from [`@jxsuite/starters`](../starters/README.md). Its `registry.json` is the current list. A starter clone copies the starter tree verbatim except `node_modules`, `dist`, `.cache`, `.jx-cache`, `.git`, and `images.json`, then re-stamps `project.json` in place: `name` always, `url` only when non-empty, `build.adapter` only when the adapter is not `static`, and the `<meta name="description">` content only when a description was given. The starter's design tokens, content collections, image pipeline, and the rest of `$head` survive; its `package.json` does not, because it is rebuilt from scratch (see below).
 
 ## What gets generated
 
-`project.json` leads with `$schema: "./project.schema.json"` and carries `$head`, `$media`, `build` (`{ outDir: "./dist", trailingSlash: "always" }`, plus `adapter` when it is not `static`), `content: {}`, `defaults: { lang: "en", layout: "./layouts/base.json" }`, `extensions: ["@jxsuite/parser"]`, `name`, `style`, and `url`.
+`project.json` leads with `$schema: "./project.schema.json"` and carries `$head`, `$media`, `build` (`{ outDir: "./dist", trailingSlash: "always" }`, plus `adapter` when it is not `static`), `content: {}`, `defaults: { lang: "en", layout: "./layouts/base.jxn" }`, `extensions: ["@jxsuite/parser"]`, `name`, `style`, and `url`.
 
 `package.json` is `private: true`, MIT, with `build`/`dev`/`preview` scripts calling the `jx` CLI. Its name is the project name lowercased with non-alphanumerics collapsed to hyphens. `@jxsuite/parser` is a dependency; `@jxsuite/compiler`, `@jxsuite/runtime` and `@jxsuite/server` are devDependencies. Any non-static adapter adds `hono: "^4"`; the two Cloudflare adapters additionally add `wrangler: "^4"`, a `deploy` script (`wrangler deploy` or `wrangler pages deploy dist`), and a generated `wrangler.jsonc`.
 

package/generate.ts

@@ -205,7 +205,10 @@ async function populateProject(destPath: string, opts: ProjectOptions) {
   const packageJson = buildPackageJson({ adapter, description, name });
 
   const writes = [
-    writeFile(join(destPath, NEW_PROJECT_FILE_NAME), serializeProjectFile(projectJson, null)),
+    writeFile(
+      join(destPath, NEW_PROJECT_FILE_NAME),
+      withExtensionsNote(serializeProjectFile(projectJson, null)),
+    ),
     writeFile(join(destPath, "package.json"), `${JSON.stringify(packageJson, null, "  ")}\n`),
     cp(join(TEMPLATE_DIR, "gitignore"), join(destPath, ".gitignore")),
     cp(join(TEMPLATE_DIR, "layouts"), join(destPath, "layouts"), { recursive: true }),
@@ -218,6 +221,7 @@ async function populateProject(destPath: string, opts: ProjectOptions) {
   }
 
   await Promise.all(writes);
+  await writeEditorSupport(destPath);
 
   // The .gitignore, layouts/ and pages/ above are copies too, carrying the template's modes.
   // The overlay below would otherwise fail to `force` over a file that came across read-only.
@@ -298,6 +302,9 @@ async function scaffoldFromStarter(
     applyDesign(project, design, { starter: true });
   }
   await writeFile(projectPath, serializeProjectFile(project, starterText, projectPath));
+  await writeEditorSupport(destPath);
+  // Copied from a read-only install as the rest was, so made writable as the rest was.
+  await makeWritable(destPath);
 
   // Rebuild package.json so scaffolded projects get current dep ranges and scripts regardless of
   // What the in-repo starter pinned.
@@ -314,6 +321,36 @@ async function scaffoldFromStarter(
   }
 }
 
+/**
+ * A new project file, with one comment in it saying what `extensions` is for: the line a new user
+ * most needs explained, and the format's main advantage shown rather than described
+ * (`site-architecture.md` §2.4). The canonical form has no comments, so it goes in after.
+ *
+ * @param text The project file in its canonical form.
+ */
+function withExtensionsNote(text: string): string {
+  return text.replace(
+    /^extensions\b/m,
+    "// Extensions add what Jx does not do on its own. @jxsuite/parser reads pages/index.md and\n" +
+      "// every Markdown collection; turn others on in Studio, under Project Settings > Extensions.\n" +
+      "extensions",
+  );
+}
+
+/**
+ * What lets an editor and GitHub read `.jxn` from the first commit: Linguist knows KDL only as
+ * `.kdl`, and VS Code needs telling too. Both cost nothing, and an existing file is kept.
+ *
+ * @param destPath The project's root.
+ */
+async function writeEditorSupport(destPath: string): Promise<void> {
+  await mkdir(join(destPath, ".vscode"), { recursive: true });
+  await Promise.all([
+    cp(join(TEMPLATE_DIR, "gitattributes"), join(destPath, ".gitattributes"), { force: false }),
+    cp(join(TEMPLATE_DIR, "vscode"), join(destPath, ".vscode"), { force: false, recursive: true }),
+  ]);
+}
+
 /**
  * Apply the design quickstart (colors, fonts, breakpoints) to a project.json object, in place.
  *
@@ -499,7 +536,7 @@ function buildProjectJson({ name, description, url, adapter, template = "blank"
     content: {},
     defaults: {
       lang: "en",
-      layout: "./layouts/base.json",
+      layout: "./layouts/base.jxn",
     },
     extensions: ["@jxsuite/parser"],
     name,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/create",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Scaffold a new Jx project",
   "license": "MIT",
   "repository": {
@@ -37,7 +37,7 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/schema": "^5.4.0",
-    "@jxsuite/starters": "^3.3.2"
+    "@jxsuite/schema": "^5.6.0",
+    "@jxsuite/starters": "^3.5.0"
   }
 }

package/template/gitattributes

@@ -0,0 +1,2 @@
+# Jx Notation is KDL 2, which GitHub highlights only as .kdl
+*.jxn linguist-language=KDL

package/template/layouts/base.jxn

@@ -0,0 +1,38 @@
+/- kdl-version 2
+
+div {
+    style {
+        margin "0"
+        padding "0"
+        minHeight "100vh"
+        display flex
+        flexDirection column
+        fontFamily "system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif"
+        lineHeight "1.6"
+        color "#1a1a1a"
+    }
+    header {
+        style padding="1rem 2rem" borderBottom="1px solid #e5e5e5"
+        a href="/" {
+            style textDecoration=none fontSize="1.25rem" fontWeight="700" color="#1a1a1a"
+            - "My Site"
+        }
+    }
+    main {
+        style flex="1" maxWidth="800px" margin="0 auto" padding="2rem" width="100%"
+        slot
+    }
+    footer {
+        style {
+            padding "1.5rem 2rem"
+            borderTop "1px solid #e5e5e5"
+            textAlign center
+            fontSize "0.875rem"
+            color "#666"
+        }
+        p {
+            style margin="0"
+            - "Built with Jx"
+        }
+    }
+}

package/template/vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["kdl-org.kdl"]
+}

package/template/vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "files.associations": {
+    "*.jxn": "kdl"
+  }
+}

package/template-versions.json

@@ -1,6 +1,6 @@
 {
-  "parser": "^4.3.2",
-  "compiler": "^8.4.0",
-  "runtime": "^6.2.1",
-  "server": "^8.5.0"
+  "parser": "^4.3.4",
+  "compiler": "^8.6.0",
+  "runtime": "^6.3.0",
+  "server": "^8.7.0"
 }

package/templates/mobile-app/layouts/base.jxn

@@ -0,0 +1,73 @@
+/- kdl-version 2
+
+div {
+    style {
+        margin "0"
+        padding "0"
+        height "100dvh"
+        display flex
+        flexDirection column
+        fontFamily "system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif"
+        lineHeight "1.6"
+        color "#1a1a1a"
+        backgroundColor "#ffffff"
+    }
+    header {
+        style {
+            padding "0.75rem 1rem"
+            paddingTop "calc(0.75rem + env(safe-area-inset-top))"
+            borderBottom "1px solid #e5e5e5"
+            textAlign center
+        }
+        span {
+            style fontSize="1.05rem" fontWeight="700"
+            - "My App"
+        }
+    }
+    main {
+        style flex="1" overflowY=auto padding="1rem" width="100%"
+        slot
+    }
+    nav {
+        style {
+            display flex
+            borderTop "1px solid #e5e5e5"
+            paddingBottom "env(safe-area-inset-bottom)"
+            backgroundColor "#ffffff"
+        }
+        a href="/" {
+            style {
+                flex "1"
+                padding "0.75rem 0"
+                textAlign center
+                textDecoration none
+                fontSize "0.8rem"
+                fontWeight "600"
+                color "#1a1a1a"
+            }
+            - Home
+        }
+        a href="/explore/" {
+            style {
+                flex "1"
+                padding "0.75rem 0"
+                textAlign center
+                textDecoration none
+                fontSize "0.8rem"
+                color "#666"
+            }
+            - Explore
+        }
+        a href="/profile/" {
+            style {
+                flex "1"
+                padding "0.75rem 0"
+                textAlign center
+                textDecoration none
+                fontSize "0.8rem"
+                color "#666"
+            }
+            - Profile
+        }
+    }
+}

package/templates/mobile-app/pages/index.md

@@ -4,4 +4,4 @@ title: Home
 
 # Welcome
 
-Your new Jx app is ready. Edit this page at `pages/index.md`, and the app shell (header and bottom navigation) at `layouts/base.json`.
+Your new Jx app is ready. Edit this page at `pages/index.md`, and the app shell (header and bottom navigation) at `layouts/base.jxn`.

package/template/layouts/base.json

@@ -1,63 +0,0 @@
-{
-  "tagName": "div",
-  "style": {
-    "margin": "0",
-    "padding": "0",
-    "minHeight": "100vh",
-    "display": "flex",
-    "flexDirection": "column",
-    "fontFamily": "system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif",
-    "lineHeight": "1.6",
-    "color": "#1a1a1a"
-  },
-  "children": [
-    {
-      "tagName": "header",
-      "style": {
-        "padding": "1rem 2rem",
-        "borderBottom": "1px solid #e5e5e5"
-      },
-      "children": [
-        {
-          "tagName": "a",
-          "attributes": { "href": "/" },
-          "style": {
-            "textDecoration": "none",
-            "fontSize": "1.25rem",
-            "fontWeight": "700",
-            "color": "#1a1a1a"
-          },
-          "children": ["My Site"]
-        }
-      ]
-    },
-    {
-      "tagName": "main",
-      "style": {
-        "flex": "1",
-        "maxWidth": "800px",
-        "margin": "0 auto",
-        "padding": "2rem",
-        "width": "100%"
-      },
-      "children": [{ "tagName": "slot" }]
-    },
-    {
-      "tagName": "footer",
-      "style": {
-        "padding": "1.5rem 2rem",
-        "borderTop": "1px solid #e5e5e5",
-        "textAlign": "center",
-        "fontSize": "0.875rem",
-        "color": "#666"
-      },
-      "children": [
-        {
-          "tagName": "p",
-          "style": { "margin": "0" },
-          "children": ["Built with Jx"]
-        }
-      ]
-    }
-  ]
-}

package/templates/mobile-app/layouts/base.json

@@ -1,96 +0,0 @@
-{
-  "tagName": "div",
-  "style": {
-    "margin": "0",
-    "padding": "0",
-    "height": "100dvh",
-    "display": "flex",
-    "flexDirection": "column",
-    "fontFamily": "system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif",
-    "lineHeight": "1.6",
-    "color": "#1a1a1a",
-    "backgroundColor": "#ffffff"
-  },
-  "children": [
-    {
-      "tagName": "header",
-      "style": {
-        "padding": "0.75rem 1rem",
-        "paddingTop": "calc(0.75rem + env(safe-area-inset-top))",
-        "borderBottom": "1px solid #e5e5e5",
-        "textAlign": "center"
-      },
-      "children": [
-        {
-          "tagName": "span",
-          "style": {
-            "fontSize": "1.05rem",
-            "fontWeight": "700"
-          },
-          "children": ["My App"]
-        }
-      ]
-    },
-    {
-      "tagName": "main",
-      "style": {
-        "flex": "1",
-        "overflowY": "auto",
-        "padding": "1rem",
-        "width": "100%"
-      },
-      "children": [{ "tagName": "slot" }]
-    },
-    {
-      "tagName": "nav",
-      "style": {
-        "display": "flex",
-        "borderTop": "1px solid #e5e5e5",
-        "paddingBottom": "env(safe-area-inset-bottom)",
-        "backgroundColor": "#ffffff"
-      },
-      "children": [
-        {
-          "tagName": "a",
-          "attributes": { "href": "/" },
-          "style": {
-            "flex": "1",
-            "padding": "0.75rem 0",
-            "textAlign": "center",
-            "textDecoration": "none",
-            "fontSize": "0.8rem",
-            "fontWeight": "600",
-            "color": "#1a1a1a"
-          },
-          "children": ["Home"]
-        },
-        {
-          "tagName": "a",
-          "attributes": { "href": "/explore/" },
-          "style": {
-            "flex": "1",
-            "padding": "0.75rem 0",
-            "textAlign": "center",
-            "textDecoration": "none",
-            "fontSize": "0.8rem",
-            "color": "#666"
-          },
-          "children": ["Explore"]
-        },
-        {
-          "tagName": "a",
-          "attributes": { "href": "/profile/" },
-          "style": {
-            "flex": "1",
-            "padding": "0.75rem 0",
-            "textAlign": "center",
-            "textDecoration": "none",
-            "fontSize": "0.8rem",
-            "color": "#666"
-          },
-          "children": ["Profile"]
-        }
-      ]
-    }
-  ]
-}