create-flamefront 0.0.0 → 0.1.4

package/README.md

@@ -0,0 +1,15 @@
+# create-flamefront
+
+Create a Flamefront app with one server-rendered Octane route:
+
+```sh
+pnpm create flamefront@latest my-app
+cd my-app
+pnpm dev
+```
+
+Use `--no-install` to create the project files without installing dependencies.
+The target directory must be empty.
+
+See the [Flamefront create-app guide](https://github.com/aleclarson/flamefront/blob/main/docs/create-app.md)
+for the generated files and how they work.

package/bin/create-flamefront.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { run } from "../src/cli.js"
+
+await run(process.argv.slice(2))

package/package.json

@@ -1,13 +1,27 @@
 {
   "name": "create-flamefront",
-  "version": "0.0.0",
-  "description": "",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+  "version": "0.1.4",
+  "private": false,
+  "description": "Create a Flamefront app.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aleclarson/flamefront.git",
+    "directory": "packages/create-flamefront"
   },
-  "keywords": [],
-  "author": "",
-  "license": "All rights reserved",
-  "type": "commonjs"
+  "type": "module",
+  "bin": {
+    "create-flamefront": "./bin/create-flamefront.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "template"
+  ],
+  "engines": {
+    "node": ">=26.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/src/cli.d.ts

@@ -0,0 +1,33 @@
+export type PackageManager = "bun" | "npm" | "pnpm" | "yarn"
+
+export interface CreateProjectOptions {
+  readonly cwd?: string
+  readonly install?: boolean
+  readonly installDependencies?: (
+    packageManager: PackageManager,
+    directory: string,
+  ) => Promise<void> | void
+  readonly packageManager?: PackageManager
+}
+
+export interface CreatedProject {
+  readonly name: string
+  readonly packageManager: PackageManager
+  readonly targetDirectory: string
+}
+
+export function detectPackageManager(
+  environment?: Record<string, string | undefined>,
+): PackageManager
+
+export function projectName(directory: string): string
+
+export function createProject(
+  directory: string,
+  options?: CreateProjectOptions,
+): Promise<CreatedProject>
+
+export function run(
+  arguments_: readonly string[],
+  options?: Omit<CreateProjectOptions, "install">,
+): Promise<void>

package/src/cli.js

@@ -0,0 +1,198 @@
+import { spawn } from "node:child_process"
+import {
+  cp,
+  mkdir,
+  readFile,
+  readdir,
+  rename,
+  stat,
+  writeFile,
+} from "node:fs/promises"
+import { basename, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const templateDirectory = fileURLToPath(
+  new URL("../template/", import.meta.url),
+)
+const packageMetadata = JSON.parse(
+  await readFile(new URL("../package.json", import.meta.url), "utf8"),
+)
+
+const usage = `Create a Flamefront app.
+
+Usage:
+  create-flamefront <directory> [--no-install]
+
+Options:
+  --no-install  Create the project without installing dependencies
+  -h, --help    Show this help
+  -v, --version Show the installed create-flamefront version`
+
+export function detectPackageManager(environment = process.env) {
+  const userAgent = environment.npm_config_user_agent ?? ""
+  const name = userAgent.split("/", 1)[0]
+
+  return ["pnpm", "npm", "yarn", "bun"].includes(name) ? name : "npm"
+}
+
+export function projectName(directory) {
+  const name = basename(resolve(directory))
+  const valid =
+    name.length <= 214 &&
+    /^(?:[a-z0-9][a-z0-9._-]*)$/.test(name) &&
+    !name.startsWith(".") &&
+    !name.startsWith("_")
+
+  if (!valid) {
+    throw new Error(
+      `${JSON.stringify(name)} is not a valid package name. Use lowercase letters, numbers, dots, hyphens, or underscores.`,
+    )
+  }
+
+  return name
+}
+
+function parseArguments(arguments_) {
+  let install = true
+  let directory
+
+  for (const argument of arguments_) {
+    if (argument === "--no-install") {
+      install = false
+    } else if (argument === "-h" || argument === "--help") {
+      return { help: true }
+    } else if (argument === "-v" || argument === "--version") {
+      return { version: true }
+    } else if (argument.startsWith("-")) {
+      throw new Error(`Unknown option: ${argument}`)
+    } else if (directory === undefined) {
+      directory = argument
+    } else {
+      throw new Error("Provide exactly one target directory.")
+    }
+  }
+
+  if (directory === undefined) {
+    throw new Error("A target directory is required.")
+  }
+
+  return { directory, install }
+}
+
+async function ensureEmptyDirectory(directory) {
+  try {
+    const details = await stat(directory)
+
+    if (!details.isDirectory()) {
+      throw new Error(`${directory} exists and is not a directory.`)
+    }
+
+    const entries = await readdir(directory)
+
+    if (entries.length > 0) {
+      throw new Error(`${directory} is not empty.`)
+    }
+  } catch (error) {
+    if (error?.code !== "ENOENT") {
+      throw error
+    }
+
+    await mkdir(directory, { recursive: true })
+  }
+}
+
+async function installDependencies(packageManager, directory) {
+  await new Promise((fulfill, reject) => {
+    const child = spawn(packageManager, ["install"], {
+      cwd: directory,
+      stdio: "inherit",
+    })
+
+    child.on("error", reject)
+    child.on("exit", (code, signal) => {
+      if (code === 0) {
+        fulfill()
+      } else {
+        reject(
+          new Error(
+            signal
+              ? `${packageManager} install was terminated by ${signal}.`
+              : `${packageManager} install exited with code ${code}.`,
+          ),
+        )
+      }
+    })
+  })
+}
+
+export async function createProject(directory, options = {}) {
+  const targetDirectory = resolve(options.cwd ?? process.cwd(), directory)
+  const name = projectName(targetDirectory)
+  const packageManager = options.packageManager ?? detectPackageManager()
+
+  await ensureEmptyDirectory(targetDirectory)
+  await cp(templateDirectory, targetDirectory, { recursive: true })
+  await rename(
+    resolve(targetDirectory, "gitignore"),
+    resolve(targetDirectory, ".gitignore"),
+  )
+
+  const packageFile = resolve(targetDirectory, "package.json")
+  const template = await readFile(packageFile, "utf8")
+
+  await writeFile(
+    packageFile,
+    template
+      .replaceAll("__PACKAGE_NAME__", name)
+      .replaceAll("__FLAMEFRONT_VERSION__", packageMetadata.version),
+  )
+
+  if (options.install !== false) {
+    await (options.installDependencies ?? installDependencies)(
+      packageManager,
+      targetDirectory,
+    )
+  }
+
+  return { name, packageManager, targetDirectory }
+}
+
+export async function run(arguments_, options = {}) {
+  try {
+    const parsed = parseArguments(arguments_)
+
+    if (parsed.help) {
+      console.log(usage)
+      return
+    }
+
+    if (parsed.version) {
+      console.log(packageMetadata.version)
+      return
+    }
+
+    const result = await createProject(parsed.directory, {
+      cwd: options.cwd,
+      install: parsed.install,
+      installDependencies: options.installDependencies,
+      packageManager: options.packageManager,
+    })
+    const relativeTarget = parsed.directory === "." ? "." : parsed.directory
+
+    console.log(`Created ${result.name} in ${result.targetDirectory}.`)
+    if (!parsed.install) {
+      console.log(
+        `\nNext steps:\n  cd ${relativeTarget}\n  ${result.packageManager} install\n  ${result.packageManager} run dev`,
+      )
+    } else {
+      console.log(
+        `\nNext steps:\n  cd ${relativeTarget}\n  ${result.packageManager} run dev`,
+      )
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+
+    console.error(`create-flamefront: ${message}`)
+    process.exitCode = 1
+  }
+}

package/template/gitignore

@@ -0,0 +1,3 @@
+.flamefront/
+dist/
+node_modules/

package/template/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Flamefront app</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/template/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "__PACKAGE_NAME__",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=26.0.0"
+  },
+  "scripts": {
+    "dev": "ff dev",
+    "build": "ff build",
+    "preview": "ff preview",
+    "routes": "ff routes",
+    "typegen": "ff typegen",
+    "typecheck": "tsc"
+  },
+  "dependencies": {
+    "@octanejs/remix-router": "0.1.48",
+    "@octanejs/vite-plugin": "0.1.54",
+    "flamefront": "^__FLAMEFRONT_VERSION__",
+    "octane": "0.2.7"
+  },
+  "devDependencies": {
+    "@types/node": "26.5.1",
+    "typescript": "5.9.3",
+    "vite": "8.3.0"
+  }
+}

package/template/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+allowBuilds:
+  esbuild: true

package/template/src/AppShell.tsrx

@@ -0,0 +1,8 @@
+import { Outlet } from "@octanejs/remix-router"
+
+export default function AppShell() @{
+  <div className="app-shell">
+    <header>Flamefront</header>
+    <Outlet />
+  </div>
+}

package/template/src/HomePage.tsrx

@@ -0,0 +1,16 @@
+import { useLoaderData } from "@octanejs/remix-router"
+import type { LoaderArgs } from "flamefront/server"
+
+export async function loader({ request }: LoaderArgs<"/">) {
+  return { pathname: new URL(request.url).pathname }
+}
+
+export default function HomePage() @{
+  const data = useLoaderData<typeof loader>()
+
+  <main>
+    <p className="eyebrow">Server-rendered with Flamefront</p>
+    <h1>Your app is ready.</h1>
+    <p>The loader handled {data.pathname}</p>
+  </main>
+}

package/template/src/app.ts

@@ -0,0 +1,6 @@
+import { defineApp, serverRoute } from "flamefront"
+
+export const app = defineApp({
+  shell: "/src/AppShell.tsrx",
+  routes: [serverRoute("/", "/src/HomePage.tsrx")],
+})

package/template/src/entry-server.ts

@@ -0,0 +1,16 @@
+import { importRoute } from "virtual:flamefront/server-routes"
+import { createServerEntry } from "flamefront/entry"
+import { createOctaneDocuments } from "flamefront/octane"
+import { createRouteRuntime } from "flamefront/server"
+import { app } from "./app.ts"
+
+const runtime = createRouteRuntime({ app, importRoute })
+const documents = createOctaneDocuments({ app, runtime })
+
+export default createServerEntry({
+  app,
+  documents,
+  assets: {
+    clientDirectory: new URL("../client/", import.meta.url),
+  },
+})

package/template/src/env.d.ts

@@ -0,0 +1,27 @@
+declare module "*.tsrx" {
+  const Component: unknown
+
+  export default Component
+}
+
+declare module "virtual:flamefront/remix-routes" {
+  import type { RouteObject } from "@octanejs/remix-router"
+  import type { RouterDocument as RouterDocumentComponent } from "flamefront/octane"
+  import type {
+    GeneratedRouteMetadata,
+    NormalizedRoutingOptions,
+  } from "flamefront"
+
+  export const RouterDocument: RouterDocumentComponent
+  export const routes: RouteObject[]
+  export const routing: NormalizedRoutingOptions
+  export const routeMetadata: readonly GeneratedRouteMetadata[]
+  export function preloadRoute(entry: string): Promise<void>
+}
+
+declare module "virtual:flamefront/server-routes" {
+  import type { RouteModule } from "flamefront/server"
+
+  export function importRoute(entry: string): Promise<RouteModule>
+  export function loadActions(): Promise<void>
+}

package/template/src/main.ts

@@ -0,0 +1,5 @@
+import { startOctaneClient } from "flamefront/octane/client"
+import { app } from "./app.ts"
+import "./styles.css"
+
+await startOctaneClient({ app })

package/template/src/styles.css

@@ -0,0 +1,31 @@
+:root {
+  color: #231a14;
+  background: #fff8ed;
+  font-family: ui-sans-serif, system-ui, sans-serif;
+}
+
+body {
+  margin: 0;
+}
+
+.app-shell {
+  width: min(42rem, calc(100% - 3rem));
+  margin: 0 auto;
+  padding: 3rem 0;
+}
+
+header,
+.eyebrow {
+  color: #b33a16;
+  font-weight: 700;
+}
+
+main {
+  padding-top: 6rem;
+}
+
+h1 {
+  margin: 0.25rem 0;
+  font-size: clamp(2.5rem, 8vw, 5rem);
+  line-height: 0.95;
+}

package/template/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "allowImportingTsExtensions": true,
+    "jsx": "react-jsx",
+    "jsxImportSource": "octane",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "noEmit": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "ESNext",
+    "types": ["node", "vite/client"]
+  },
+  "include": ["src", ".flamefront/types"]
+}

package/template/vite.config.ts

@@ -0,0 +1,7 @@
+import { octane } from "@octanejs/vite-plugin"
+import { flamefront } from "flamefront/vite"
+import { defineConfig } from "vite"
+
+export default defineConfig({
+  plugins: [flamefront({ target: "node" }), octane()],
+})

package/readme.md

@@ -1 +0,0 @@
-Coming soon...