create-cubing-app 0.35.6-rc8 → 0.36.2

package/README.md

@@ -1,6 +1,6 @@
-# `cubing-app-template`
+# `create-cubing-app`
 
-This is a template project for project using [`cubing.js`](https://github.com/cubing/cubing.js) with `node` and `npm`. In an editor like VSCode, this will give you nice imports, autocompletions, and other TypeScript benefits.
+This is a tool to initialize apps using [`cubing.js`](https://github.com/cubing/cubing.js) with `node` and `npm`. In an editor like VS Code, this will give you nice imports, autocompletions, and other TypeScript benefits.
 
 See <https://js.cubing.net/cubing/> for (in-progress) documentation on `cubing.js`. If you think you have any issues, don't hesitate to [file an issue here](https://github.com/cubing/cubing.js/issues/new/choose).
 
@@ -9,11 +9,8 @@ See <https://js.cubing.net/cubing/> for (in-progress) documentation on `cubing.j
 Make sure `node` is installed first (which will also install `npm`): <https://nodejs.org/en/download/>
 
 ```shell
-# Set up the project for the first time
-git clone https://github.com/cubing/cubing-app-template my-app && cd my-app
-npm install
-
-# Start working on the project at http://localhost:1234
+npm create --yes cubing-app@latest my-cubing-project
+cd my-cubing-project
 npm run dev
 ```
 
@@ -25,7 +22,7 @@ npm run build
 
 The site will be built to the `dist/web` folder, ready to place onto any static web server.
 
-(Note: the output uses module scripts, which means you can't just open the output HTML files directly in the browser. You have to use a web server. Something like `python3 -m http.server -d dist/web` might help if you just need to test the output locally.)
+(Note: the output uses module scripts, which means you can't just open the output HTML files directly in the browser. You have to use a web server. If you want to test the output of `npm run build` locally on your computer, you can run: `npx http-server ./dist/web`)
 
 ## Getting the latest version of `cubing.js`
 

package/bin/create-cubing-app.js

@@ -1,6 +1,13 @@
 #!/usr/bin/env node
 import { exec } from "child_process";
-import { mkdir, readFile, writeFile } from "fs/promises";
+import { exists } from "fs";
+import { mkdir, readFile, stat, writeFile } from "fs/promises";
+import { join, resolve } from "path";
+import { exit, stderr } from "process";
+import { createInterface } from "readline";
+import { promisify } from "util";
+
+const CREATE_CUBING_APP_PACKAGE_JSON = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf-8"));
 
 function execPromise(cmd, options) {
 	return new Promise((resolve, reject) => {
@@ -14,95 +21,120 @@ function execPromise(cmd, options) {
 	});
 }
 
+function printHelpAndExit() {
+	stderr.write(`Usage:
+
+npm create cubing-app <project folder name>
+
+The project folder name should consist of only letters, numbers, dashes, and u
+nderscores.
+`);
+	exit(1);
+}
+
+let projectPath = process.argv[2];
+if (!projectPath) {
+	const readline = createInterface({
+		input: process.stdin,
+		output: process.stdout,
+	});
+
+	projectPath = await new Promise((resolve, reject) => {
+		try {
+			readline.question(
+				`Where would you like to place the project?
+(Enter a path or name for a new folder.)
+`,
+				resolve,
+			);
+		} catch (e) {
+			reject(e);
+		} finally {
+		}
+	});
+	readline.close();
+	if (projectPath === "") {
+		console.log("Please enter a non-empty project path.");
+		exit(1);
+	}
+}
+
+function projectPathed(path) {
+	return join(projectPath, path);
+}
+
+console.log(`---------------------------------
+Creating a cubing project in the following folder:
+${projectPath}
+`);
+
+// We could uses `stat` from `"fs/promises"`, but I'm not too enthused about
+// catching an error in the "expected" path. So we use `exists`.
+if (await promisify(exists)(projectPath)) {
+	process.stderr.write(`Project already exists in the current folder: ${projectPath}
+Please select a different name (or delete the existing project folder).
+`);
+	exit(1);
+}
+await mkdir(projectPath, { recursive: true });
+
 const initialPackageJSON = {
+	type: "module",
 	scripts: {
-		build:
-			'node -e \'import("barely-a-dev-server").then(s => s.barelyServe({entryRoot: "src", dev: false, outDir: "dist/web"}))\'',
-		dev: 'node -e \'import("barely-a-dev-server").then(s => s.barelyServe({entryRoot: "src"}))\'',
+    "build": CREATE_CUBING_APP_PACKAGE_JSON.scripts["build"],
+    "dev": CREATE_CUBING_APP_PACKAGE_JSON.scripts["dev"],
 		clean: "rm -rf ./dist",
+		"upgrade-cubing": "npm install --save cubing@latest",
 	},
 };
 await writeFile(
-	"./package.json",
+	projectPathed("package.json"),
 	JSON.stringify(initialPackageJSON, null, "  "),
 );
 
-await execPromise("npm install --save cubing");
-await execPromise("npm install --save-dev barely-a-dev-server");
-
-await mkdir("./src", { recursive: true });
+const execOptions = {
+	cwd: projectPath,
+};
+await mkdir(projectPathed("script"), { recursive: true });
+await mkdir(projectPathed("src"), { recursive: true });
 async function transferFile(rootedPath, contents) {
-	const indexHTML = await readFile(new URL(`./${rootedPath}`, import.meta.url));
-	await writeFile(`./${rootedPath}`, indexHTML);
+	contents ??= await (async () => {
+		const filePath = new URL(join("..", rootedPath), import.meta.url);
+		return readFile(filePath, "utf-8");
+	})();
+	await writeFile(projectPathed(rootedPath), contents);
 }
-await transferFile(
-	"src/index.html",
-	`<!DOCTYPE html>
-<html>
-
-<head>
-  <meta charset="utf8">
-  <title>My Cubing App</title>
-  <link rel="stylesheet" href="./index.css">
-  <!-- Note: the source file is \`main.ts\`, but here we use the transpiled file name it will have on the web server. -->
-  <script src="./main.js" type="module"></script>
-</head>
-
-<body>
-  <h1>My Cubing App</h1>
-  <twisty-player id="main-player"></twisty-player>
-</body>
-
-</html>
-`,
-);
-await transferFile(
-	"src/main.ts",
-	`// Always keep the following line if you are using any twisty players on your page.
-import "cubing/twisty";
-// Use the following line for specific imports from \`cubing/twisty\`.
-import { TwistyAlgViewer, type TwistyPlayer } from "cubing/twisty";
-
-// Import from other modules as usual.
-import { randomScrambleForEvent } from "cubing/scramble";
-
-class App {
-  // Example of getting an element from the page.
-  twistyPlayer: TwistyPlayer = document.querySelector("#main-player")!;
-  // Example of creating a new element and adding it to the page.
-  twistyAlgViewer = document.body.appendChild(
-    new TwistyAlgViewer({ twistyPlayer: this.twistyPlayer })
-  );
-  constructor() {
-    this.updateScramble();
-  }
-
-  async updateScramble() {
-    this.twistyPlayer.alg = await randomScrambleForEvent("333");
-  }
-}
-
-// Make the app object available in the console for debugging.
-// Try running: app.updateScramble()
-globalThis.app = new App();
-`,
-);
-await transferFile(
-	"src/index.css",
-	`/* Center everything on the page. */
-html, body {
-  height: 100%;
-  margin: 0;
-  display: grid;
-  place-content: center;
-  gap: 1em;
-  font-family: sans-serif;
-}
-`,
-);
+await transferFile("script/build.js");
+await transferFile("script/dev.js");
+await transferFile("src/index.html");
+await transferFile("src/main.ts");
+await transferFile("src/index.css");
 await transferFile(
 	".gitignore",
 	`/dist
 /node_modules
 `,
 );
+await transferFile("tsconfig.json");
+
+await execPromise("npm install --save cubing", execOptions);
+await execPromise("npm install --save-dev barely-a-dev-server", execOptions);
+
+console.log(`Your cubing app has been created.
+To work on it, run:
+
+    cd \"${projectPath.replaceAll('"', '\\"')}\"
+    npm run dev
+
+Edit the files in \`src\` and open the displayed URL in browser to see changes.
+
+--------
+
+To create an optimized build of your app that can be uploaded to a file server, run:
+
+    npm run build
+
+When a new version of \`cubing.js\` is released in the future, you can upgrade using:
+
+    npm install --save cubing@latest
+`);

package/package.json

@@ -1,18 +1,27 @@
 {
   "name": "create-cubing-app",
-  "version": "0.35.6-rc8",
+  "version": "0.36.2",
   "type": "module",
   "bin": "./bin/create-cubing-app.js",
   "scripts": {
-    "build": "node -e 'import(\"barely-a-dev-server\").then(s => s.barelyServe({entryRoot: \"src\", dev: false, outDir: \"dist/web\"}))'",
-    "dev": "node -e 'import(\"barely-a-dev-server\").then(s => s.barelyServe({entryRoot: \"src\"}))'",
+    "build": "node script/build.js",
+    "dev": "node script/build.js -- --dev",
+    "roll-cubing-commit": "./script/roll-cubing-commit.bash",
     "clean": "rm -rf ./dist"
   },
   "dependencies": {
-    "cubing": "^0.35.6"
+    "cubing": "^0.43.4"
   },
   "devDependencies": {
-    "barely-a-dev-server": "^0.4.8",
-    "esbuild": "^0.16.16"
-  }
+    "@types/validate-npm-package-name": "^4.0.0",
+    "barely-a-dev-server": "^0.6.0",
+    "esbuild": "^0.19.2",
+    "validate-npm-package-name": "^5.0.0"
+  },
+  "files": [
+    "./bin",
+    "./script",
+    "./src",
+    "./tsconfig.json"
+  ]
 }

package/script/build.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+import {barelyServe} from "barely-a-dev-server";
+
+export const COMMON_BUILD_OPTIONS = {
+  entryRoot: "./src",
+  esbuildOptions: {chunkNames: "chunks/[name]-[hash]"}
+}
+
+if (process.argv.at(-1) === "--dev") {
+
+  barelyServe(COMMON_BUILD_OPTIONS);
+
+} else {
+
+  const outDir = "./dist/web";
+  await barelyServe({
+    ...COMMON_BUILD_OPTIONS,
+    dev: false,
+    outDir,
+  });
+
+  console.log(`
+  Your app has been built in: ${outDir}
+  
+  `)
+}

package/script/common-build-options.js

@@ -0,0 +1,4 @@
+export const COMMON_BUILD_OPTIONS = {
+  entryRoot: "./src",
+  esbuildOptions: {chunkNames: "chunks/[name]-[hash]"}
+}

package/script/dev.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import {barelyServe} from "barely-a-dev-server";
+import { COMMON_BUILD_OPTIONS } from "./common-build-options.js";
+
+barelyServe(COMMON_BUILD_OPTIONS);

package/script/roll-cubing-commit.bash

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+
+# This is simplified `bash` version of: https://github.com/lgarron/scripts/blob/9aa4a016c7853b7a7588dd11bacd327156251b1e/web/npm-roll
+
+if [ ! -z "$(git status --porcelain)" ]
+then
+  echo "git status must be clean"
+  echo ""
+  git status
+  exit 1
+fi
+
+VERSION=$(npm show cubing version)
+echo "Rolling \`cubing\` to version: v${VERSION}"
+
+npm install "cubing@v${VERSION}"
+git stage package*
+git commit -m "\`npm install cubing@v${VERSION}\`"

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "es2022",
+    "moduleResolution": "bundler",
+    "verbatimModuleSyntax": true, // avoids surprises with `cubing/twisty`
+  }
+}