create-reactaform-app 0.1.0

package/README.md

@@ -0,0 +1,125 @@
+# create-reactaform-app
+
+Scaffold a minimal Vite (default) or Next.js React app with ReactaForm preconfigured. Paste a form definition and see results instantly.
+
+## Quick start
+Create a new app from the CLI (JavaScript):
+
+```bash
+npx create-reactaform-app my-app
+```
+
+TypeScript project:
+
+```bash
+npx create-reactaform-app my-app --ts
+```
+
+Create a Next.js app (App Router):
+
+```bash
+npx create-reactaform-app my-next-app --next
+```
+
+Use an example overlay (overwrites the starter `formDefinition`):
+
+```bash
+npx create-reactaform-app my-app --ts --example contact-form
+```
+
+After creating the project:
+
+```bash
+cd my-app
+npm install
+npm run dev
+```
+
+Open the URL shown by the dev server (usually http://localhost:5173 or http://localhost:3000).
+
+## What you get
+
+- Vite + React app or Next.js App Router scaffolded
+- `reactaform` installed and wired into the starter app (`src/App.jsx` or `app/page`)
+- A starter `formDefinition` file you can edit to update the UI instantly
+
+## Project layout (Vite)
+
+my-app/
+- src/
+  - App.jsx         # ReactaForm renderer
+  - formDefinition.js
+  - main.jsx
+- index.html
+- package.json
+- vite.config.js
+
+## Project layout (Next.js App Router)
+
+my-next-app/
+- app/
+  - page.jsx       # imports `./formDefinition`
+  - formDefinition.js
+- package.json
+
+## How it works
+
+1. CLI scaffolds a base project (Vite or Next) using the official initializers.
+2. The CLI copies small template files into the generated project (App wiring, styles).
+3. The CLI creates a starter `formDefinition.js` (or `.ts` when `--ts`) inside the app so `ReactaForm` has data to render.
+4. If `--example <name>` is provided, the example files are overlaid into the project (JS examples are converted to TypeScript when `--ts`).
+
+## Starter `formDefinition` example
+
+```js
+// src/formDefinition.js
+export const formDefinition = {
+  name: 'contactForm',
+  displayName: 'Contact Form',
+  version: '1.0.0',
+  properties: [
+    { name: 'fullName', displayName: 'Full Name', type: 'text', defaultValue: '', required: true },
+    { name: 'email', displayName: 'Email', type: 'email', defaultValue: '', required: true }
+  ]
+};
+```
+
+## CLI options
+
+- `--ts`       Create a TypeScript project
+- `--next`     Create a Next.js App Router project
+- `--install`  Run `npm install` after scaffolding
+- `--example`  Overlay an example (e.g. `--example contact-form`)
+
+## Testing the CLI locally
+
+Pack and test without publishing:
+
+```bash
+npm pack
+npx ./create-reactaform-app-0.1.0.tgz my-app-test --ts --example contact-form
+```
+
+Or link locally for iterative testing:
+
+```bash
+npm link
+create-reactaform-app my-app-test --ts --example contact-form
+```
+
+## Publishing notes
+
+- Ensure `bin/cli.js` is executable and has the Node shebang (`#!/usr/bin/env node`).
+- Add `repository`, `author`, `files`, and `publishConfig` to `package.json` before publishing.
+
+## Requirements
+
+- Node.js >= 18
+
+## Contributing
+
+Contributions welcome: open an issue or PR with improvements, examples, or bugfixes.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { createApp } from '../src/createApp.js';
+
+const args = process.argv.slice(2);
+const name = args.find(arg => !arg.startsWith('-'));
+
+if (!name) {
+  console.error('❌ Please provide a project name.');
+  console.log('Usage: npx create-reactaform-app my-app');
+  process.exit(1);
+}
+
+const options = {
+  ts: args.includes('--ts'),
+  next: args.includes('--next'),
+  install: args.includes('--install'),
+};
+
+// parse --example value (support `--example name` and `--example=name`)
+const exampleArg = args.find(a => a === '--example' || a.startsWith('--example='));
+if (exampleArg) {
+  if (exampleArg.includes('=')) {
+    options.example = exampleArg.split('=')[1];
+  } else {
+    const idx = args.indexOf('--example');
+    if (idx >= 0 && idx < args.length - 1 && !args[idx + 1].startsWith('-')) {
+      options.example = args[idx + 1];
+    }
+  }
+}
+
+createApp(name, options).catch(err => {
+  console.error('❌ Failed to create app');
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "create-reactaform-app",
+  "version": "0.1.0",
+  "description": "Create a Vite/Next.js + React app with ReactaForm preconfigured",
+  "bin": {
+    "create-reactaform-app": "./bin/cli.js"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": ["vite", "react", "ReactaForm", "cli"],
+  "author": "yanggmtl <yanggmtl@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yanggmtl/create-reactaform-app.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yanggmtl/create-reactaform-app/issues"
+  },
+  "homepage": "https://github.com/yanggmtl/create-reactaform-app#readme",
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "echo \"No tests specified\" && exit 0",
+    "lint": "echo \"No lint configured\" && exit 0"
+  },
+  "license": "MIT"
+}

package/src/createApp.js

@@ -0,0 +1,269 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { exec } from "./utils/exec.js";
+import { copyDir } from "./utils/fs.js";
+import fs from "node:fs/promises";
+import * as _logModule from "./utils/log.js";
+const log = _logModule.log ??
+  _logModule.default ?? {
+    info: (msg) => console.log(msg),
+    success: (msg) => console.log(msg),
+    error: (msg) => console.error(msg),
+  };
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export async function createApp(appName, options) {
+  // `scaffoldTemplate` is the template name passed to `create-vite` (use Vite's
+  // official React templates: `react` / `react-ts`).
+  // `template` is the local folder name under `src/templates` that we'll copy
+  // into the generated project (we keep `vite` / `vite-ts` here).
+  const scaffoldTemplate = options.next
+    ? options.ts
+      ? "next-ts"
+      : "next"
+    : options.ts
+      ? "react-ts"
+      : "react";
+  const template = options.next
+    ? options.ts
+      ? "next-ts"
+      : "next"
+    : options.ts
+      ? "vite-ts"
+      : "vite";
+
+  const creatingLabel = options.next ? "Next.js" : "ReactaForm";
+  log.info(`Creating ${creatingLabel} app: ${appName}`);
+
+  // 1. Scaffold Vite/Next.js (try primary command, then a fallback for environments
+  // where `npm create` may fail)
+  // Run scaffold commands with CI=true to force non-interactive defaults
+  const spawnEnv = { ...process.env, CI: "true" };
+
+  const extraFlags = ["--yes"];
+
+  if (options.next) {
+    // Scaffold Next.js app (try npm create, fallback to npx)
+    const nextArgsBase = ["create", "next-app@latest", appName];
+    // add flags after a -- so they're passed to the initializer
+    const nextArgsTS = options.ts
+      ? ["--", "--ts", "--use-npm"]
+      : ["--", "--use-npm"];
+    try {
+      await exec("npm", [...nextArgsBase, ...nextArgsTS, ...extraFlags], {
+        env: spawnEnv,
+        capture: true,
+      });
+    } catch (err) {
+      try {
+        await exec(
+          "npx",
+          ["create-next-app@latest", appName, ...nextArgsTS, ...extraFlags],
+          { env: spawnEnv, capture: true },
+        );
+      } catch (err2) {
+        // give up and rethrow
+        throw err2;
+      }
+    }
+  } else {
+    // Vite React scaffolding (existing behavior)
+    try {
+      await exec(
+        "npm",
+        [
+          "create",
+          "vite@latest",
+          appName,
+          "--",
+          "--template",
+          scaffoldTemplate,
+          ...extraFlags,
+        ],
+        { env: spawnEnv, capture: true },
+      );
+    } catch (err) {
+      // Fallback: try `npm init` or `npx create-vite` style invocation
+      try {
+        await exec(
+          "npm",
+          [
+            "init",
+            "vite@latest",
+            appName,
+            "--",
+            "--template",
+            scaffoldTemplate,
+            ...extraFlags,
+          ],
+          { env: spawnEnv, capture: true },
+        );
+      } catch (err2) {
+        // final fallback: npx
+        await exec(
+          "npx",
+          [
+            "create-vite@latest",
+            appName,
+            "--",
+            "--template",
+            scaffoldTemplate,
+            ...extraFlags,
+          ],
+          { env: spawnEnv, capture: true },
+        );
+      }
+    }
+  }
+
+  const appDir = path.resolve(process.cwd(), appName);
+
+  // 2. Install ReactaForm
+  await exec("npm", ["install", "reactaform"], { cwd: appDir });
+
+  // 3. Copy templates (for Next copy to project root, for React copy to /src)
+  const templateDir = path.join(__dirname, "templates", template);
+  const targetDir = options.next ? appDir : path.join(appDir, "src");
+
+  await copyDir(templateDir, targetDir);
+
+  // For Next apps we write `formDefinition.*` inside `app/`.
+  if (options.next) {
+    try {
+      const rootJs = path.join(appDir, "formDefinition.js");
+      const rootTs = path.join(appDir, "formDefinition.ts");
+      await fs.unlink(rootJs).catch(() => {});
+      await fs.unlink(rootTs).catch(() => {});
+    } catch (e) {
+      // ignore
+    }
+  }
+
+  // Copy shared formDefinition into the new project. For Next apps place it
+  // inside the `app/` folder so pages can import `./formDefinition`.
+  // Determine where to write app-local files (Next -> app/, React -> src)
+  const writeDir = options.next ? path.join(appDir, "app") : targetDir;
+  await fs.mkdir(writeDir, { recursive: true });
+
+  // If an `--example` was requested, copy example files first so they
+  // overlay template defaults. Examples live under
+  // `src/templates/examples/<example>/js` (we only keep JS examples).
+  if (options.example) {
+    try {
+      const exampleDirJs = path.join(
+        __dirname,
+        "templates",
+        "examples",
+        options.example,
+        "js",
+      );
+      await copyDir(exampleDirJs, writeDir);
+    } catch (e) {
+      // ignore if example folder doesn't exist
+    }
+  }
+
+  // Choose source formDefinition: prefer example's JS file when present,
+  // otherwise fall back to the shared common file. Then write it as .js or
+  // convert to .ts if requested.
+  try {
+    const commonFormPath = path.join(
+      __dirname,
+      "templates",
+      "common",
+      "formDefinition.js",
+    );
+    const exampleFormPath = options.example
+      ? path.join(
+          __dirname,
+          "templates",
+          "examples",
+          options.example,
+          "js",
+          "formDefinition.js",
+        )
+      : null;
+
+    let sourcePath = commonFormPath;
+    if (exampleFormPath) {
+      try {
+        await fs.access(exampleFormPath);
+        sourcePath = exampleFormPath;
+      } catch (e) {
+        // example form not present, keep common
+      }
+    }
+
+    let formData = await fs.readFile(sourcePath, "utf8");
+    const outName = options.ts ? "formDefinition.ts" : "formDefinition.js";
+    if (options.ts) {
+      formData = formData.replace(
+        /export const formDefinition\s*=\s*/m,
+        "export const formDefinition: Record<string, unknown> = ",
+      );
+    }
+
+    await fs.writeFile(path.join(writeDir, outName), formData, "utf8");
+
+    // If we wrote a TS file for a previously-copied example, remove the JS
+    // variant so project has the correct extension.
+    if (options.ts) {
+      try {
+        await fs.unlink(path.join(writeDir, "formDefinition.js"));
+      } catch (e) {
+        // ignore if not present
+      }
+    }
+  } catch (e) {
+    // fail silently if no source formDefinition found
+  }
+
+  // If user requested a JS Next app (no --ts), remove any TypeScript files
+  // that might exist in the generated project (safety cleanup).
+  if (options.next && !options.ts) {
+    async function removeTsFiles(dir) {
+      let entries;
+      try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+      } catch (err) {
+        return;
+      }
+
+      for (const entry of entries) {
+        const entryPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          await removeTsFiles(entryPath);
+        } else {
+          const ext = path.extname(entry.name).toLowerCase();
+          if (
+            ext === ".ts" ||
+            ext === ".tsx" ||
+            entry.name === "tsconfig.json" ||
+            entry.name === "next-env.d.ts"
+          ) {
+            try {
+              await fs.unlink(entryPath);
+            } catch (e) {
+              // ignore errors
+            }
+          }
+        }
+      }
+    }
+
+    await removeTsFiles(appDir);
+  }
+
+  // 4. Optional full install
+  if (options.install) {
+    await exec("npm", ["install"], { cwd: appDir });
+  }
+
+  log.success("Done!");
+  log.info(`Next steps:
+  cd ${appName}
+  npm install
+  npm run dev
+`);
+}

package/src/templates/common/formDefinition.js

@@ -0,0 +1,24 @@
+/**
+ * Shared example ReactaForm definition.
+ */
+export const formDefinition = {
+  name: 'contactForm',
+  displayName: 'Contact Form',
+  version: '1.0.0',
+  properties: [
+    {
+      name: 'fullName',
+      displayName: 'Full Name',
+      type: 'text',
+      defaultValue: '',
+      required: true,
+    },
+    {
+      name: 'email',
+      displayName: 'Email',
+      type: 'email',
+      defaultValue: '',
+      required: true,
+    },
+  ],
+};

package/src/templates/examples/contact-form/js/formDefinition.js

@@ -0,0 +1,31 @@
+/**
+ * Contact form example (JavaScript)
+ */
+export const formDefinition = {
+  name: 'contactForm',
+  displayName: 'Contact Form (Example)',
+  version: '1.0.0',
+  properties: [
+    {
+      name: 'fullName',
+      displayName: 'Full Name',
+      type: 'text',
+      defaultValue: '',
+      required: true,
+    },
+    {
+      name: 'email',
+      displayName: 'Email',
+      type: 'email',
+      defaultValue: '',
+      required: true,
+    },
+    {
+      name: 'message',
+      displayName: 'Message',
+      type: 'multiline',
+      defaultValue: '',
+      required: false,
+    },
+  ],
+};

package/src/templates/next/app/globals.css

@@ -0,0 +1,7 @@
+html, body {
+  padding: 0;
+  margin: 0;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial;
+}
+
+* { box-sizing: border-box; }

package/src/templates/next/app/layout.jsx

@@ -0,0 +1,13 @@
+import './globals.css';
+
+export const metadata = {
+  title: 'ReactaForm Next App',
+};
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}

package/src/templates/next/app/page.jsx

@@ -0,0 +1,11 @@
+"use client";
+import { ReactaForm } from 'reactaform';
+import { formDefinition } from './formDefinition';
+
+export default function Page() {
+  return (
+    <div style={{ padding: 24, maxWidth: 600 , flex: '1', margin: '0 auto'}}>
+      <ReactaForm definitionData={formDefinition} />
+    </div>
+  );
+}

package/src/templates/next-ts/app/globals.css

@@ -0,0 +1,7 @@
+html, body {
+  padding: 0;
+  margin: 0;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial;
+}
+
+* { box-sizing: border-box; }

package/src/templates/next-ts/app/layout.tsx

@@ -0,0 +1,13 @@
+import './globals.css';
+
+export const metadata = {
+  title: 'ReactaForm Next App',
+};
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}

package/src/templates/next-ts/app/page.tsx

@@ -0,0 +1,11 @@
+"use client";
+import { ReactaForm } from 'reactaform';
+import { formDefinition } from './formDefinition';
+
+export default function Page() {
+  return (
+    <div style={{ padding: 24, maxWidth: 600 , flex: '1', margin: '0 auto'}}>
+      <ReactaForm definitionData={formDefinition} />
+    </div>
+  );
+}

package/src/templates/vite/App.jsx

@@ -0,0 +1,13 @@
+import { ReactaForm } from 'reactaform';
+import { formDefinition } from './formDefinition';
+import './App.css';
+
+export default function App() {
+  return (
+    <div className="App" style={{ padding: 24, maxWidth: 600 }}>
+      <ReactaForm
+        definitionData={formDefinition}
+      />
+    </div>
+  );
+}

package/src/templates/vite-ts/App.tsx

@@ -0,0 +1,13 @@
+import { ReactaForm } from 'reactaform';
+import { formDefinition } from './formDefinition';
+import './App.css';
+
+export default function App() {
+  return (
+    <div className="App" style={{ padding: 24, maxWidth: 600 }}>
+      <ReactaForm
+        definitionData={formDefinition}
+      />
+    </div>
+  );
+}

package/src/utils/exec.js

@@ -0,0 +1,66 @@
+import { spawn } from 'node:child_process';
+
+function isPromptLine(line) {
+  if (!line) return true;
+  // Filter box-drawing lines and create-vite prompt markers
+  if (/^[\s│└┌┐├┤┬┴─]+$/.test(line)) return true;
+  if (line.includes('◇')) return true;
+  if (/Use rolldown-vite/i.test(line)) return true;
+  if (/Install with npm and start now/i.test(line)) return true;
+  return false;
+}
+
+export function exec(command, args, options = {}) {
+  const capture = Boolean(options.capture);
+  const spawnOpts = {
+    shell: process.platform === 'win32',
+    ...options,
+  };
+
+  // When capturing, do not set stdio: 'inherit' so we can filter output
+  if (!capture) spawnOpts.stdio = 'inherit';
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, spawnOpts);
+
+    if (capture) {
+      if (child.stdout) {
+        let stdoutBuf = '';
+        child.stdout.on('data', chunk => {
+          stdoutBuf += chunk.toString();
+          const parts = stdoutBuf.split(/\r?\n/);
+          stdoutBuf = parts.pop();
+          for (const line of parts) {
+            if (!isPromptLine(line)) process.stdout.write(line + '\n');
+          }
+        });
+        child.stdout.on('end', () => {
+          if (stdoutBuf && !isPromptLine(stdoutBuf)) process.stdout.write(stdoutBuf + '\n');
+        });
+      }
+
+      if (child.stderr) {
+        let stderrBuf = '';
+        child.stderr.on('data', chunk => {
+          stderrBuf += chunk.toString();
+          const parts = stderrBuf.split(/\r?\n/);
+          stderrBuf = parts.pop();
+          for (const line of parts) {
+            if (!isPromptLine(line)) process.stderr.write(line + '\n');
+          }
+        });
+        child.stderr.on('end', () => {
+          if (stderrBuf && !isPromptLine(stderrBuf)) process.stderr.write(stderrBuf + '\n');
+        });
+      }
+    }
+
+    child.on('close', code => {
+      if (code !== 0) {
+        reject(new Error(`${command} exited with code ${code}`));
+      } else {
+        resolve();
+      }
+    });
+  });
+}

package/src/utils/fs.js

@@ -0,0 +1,18 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export async function copyDir(src, dest) {
+  await fs.mkdir(dest, { recursive: true });
+  const entries = await fs.readdir(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      await copyDir(srcPath, destPath);
+    } else {
+      await fs.copyFile(srcPath, destPath);
+    }
+  }
+}

package/src/utils/log.js

@@ -0,0 +1,5 @@
+export const log = {
+  info: msg => console.log(`ℹ️  ${msg}`),
+  success: msg => console.log(`✅ ${msg}`),
+  error: msg => console.error(`❌ ${msg}`),
+};