Merge pull request #6 from OpenScriptJs/develop

Develop

Author: levizwannah

README.md

@@ -8,7 +8,7 @@
 </p>
 
 <p align="center">
-    <strong>The Progressive, PHP-Inspired JavaScript Framework for Artisans.</strong>
+    <strong>The Progressive, Lightweight JavaScript Framework for Artisans.</strong>
 </p>
 
 <p align="center">
@@ -70,7 +70,17 @@ We didn't just build another framework; we built a toolset for developers who va
 
 ### Installation
 
-Install the package via npm:
+Start a project
+```bash
+npm create openscript-app <project-name> <template>
+```
+
+Available templates:
+- `basic`
+- `tailwind`
+- `bootstrap`
+
+Or Install the package via npm:
 
 ```bash
 npm install modular-openscriptjs
@@ -443,7 +453,6 @@ OpenScript is built around an **Inversion of Control (IoC) Container**. Instead
 | **Markup Engine** | `app('h')`               | Helper proxy for creating DOM elements.        |
 | **Router**        | `app('router')`          | Manages navigation and URL handling.           |
 | **Broker**        | `app('broker')`          | Central event bus for decoupled communication. |
-| **Context**       | `app('contextProvider')` | Manages global application state contexts.     |
 
 ---
 
@@ -485,8 +494,9 @@ export default class Counter extends Component {
   }
 }
 
-// CRITICAL: Register before usage!
-ojs(Counter);
+// ./components/App.js
+// CRITICAL: Register counter before usage!
+// ojs(Counter);
 ```
 
 > [!IMPORTANT]
@@ -569,7 +579,7 @@ Listen to global application events dispatched via the Broker. Methods prefixed
 import { parsePayload } from "modular-openscriptjs";
 
 export default class UserProfile extends Component {
-  // Listen for 'auth:login' event
+  // Listen for 'auth' and 'login' event
   async $$auth_login(eventData, eventName) {
     // 1. Parse the payload
     const data = parsePayload(eventData);

package.json

@@ -1,6 +1,6 @@
 {
   "name": "modular-openscriptjs",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "description": "OpenScriptJs Framework - A lightweight, reactive JavaScript framework for building modern web applications",
   "type": "module",
   "main": "./dist/modular-openscriptjs.umd.js",
@@ -19,13 +19,8 @@
       "require": "./build/vite-plugin-openscript.js"
     }
   },
-  "bin": {
-    "create-ojs-app": "bin/create-ojs-app"
-  },
   "files": [
     "dist",
-    "bin",
-    "templates",
     "build/vite-plugin-openscript.js",
     "build/vite-plugin-openscript.d.ts",
     "styles",

packages/create-openscript-app/README.md

@@ -0,0 +1,72 @@
+# create-openscript-app
+
+CLI tool to scaffold new OpenScript projects.
+
+## Usage
+
+```bash
+npx create-openscript-app <project-name> [template]
+```
+
+## Available Templates
+
+| Template    | Description                                  |
+| ----------- | -------------------------------------------- |
+| `basic`     | Basic OpenScript project with Vite (default) |
+| `tailwind`  | Project with TailwindCSS integration         |
+| `bootstrap` | Project with Bootstrap 5 integration         |
+
+## Examples
+
+```bash
+# Create a basic project
+npx create-openscript-app my-app
+
+# Create a project with TailwindCSS
+npx create-openscript-app my-app tailwind
+
+# Create a project with Bootstrap
+npx create-openscript-app my-app bootstrap
+```
+
+## What's Included
+
+Each scaffolded project includes:
+
+- 📦 Vite for fast development and building
+- 🎯 Pre-configured OpenScript setup with Vite plugin
+- 🛣️ Router with example routes
+- 🧩 Example components (App, HomePage, AboutUs, Counter)
+- 📝 Context management setup
+- 📡 Event broker with mediators
+
+## ⚠️ Important: Vite Plugin Required!
+
+**The OpenScript Vite plugin is REQUIRED for your application to work.** All templates come pre-configured with the plugin in `vite.config.js`:
+
+```javascript
+import { defineConfig } from "vite";
+import { openScriptComponentPlugin } from "modular-openscriptjs/plugin";
+
+export default defineConfig({
+  // ...
+  plugins: [
+    openScriptComponentPlugin({
+      componentsDir: "src/components",
+      autoRegister: true,
+      generateTypes: true,
+    }),
+  ],
+});
+```
+
+**Do NOT remove this plugin** - it handles component registration, type generation, and other essential build-time transformations.
+
+## Learn More
+
+- [OpenScriptJs Documentation](https://github.com/OpenScriptJs/modular-openscript)
+- [Vite Documentation](https://vitejs.dev/)
+
+## License
+
+MIT

bin/create-ojs-app packages/create-openscript-app/index.jsbin/create-ojs-app renamed to packages/create-openscript-app/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * create-ojs-app
+ * create-openscript-app
  * CLI tool to scaffold new OpenScript projects
  * Similar to create-react-app, create-vue
  */
@@ -59,11 +59,15 @@ async function createProject(projectName, template = "basic") {
   logSuccess(`Created directory: ${projectName}`);
 
   // Get template path
-  const templatesDir = path.join(__dirname, "..", "templates");
+  const templatesDir = path.join(__dirname, "templates");
   const templatePath = path.join(templatesDir, template);
 
   if (!fs.existsSync(templatePath)) {
     logError(`Template "${template}" not found!`);
+    log("\nAvailable templates:", "cyan");
+    log("  basic      - Basic OpenScript project (default)", "cyan");
+    log("  tailwind   - Project with TailwindCSS integration", "cyan");
+    log("  bootstrap  - Project with Bootstrap 5 integration\n", "cyan");
     fs.rmdirSync(projectPath);
     process.exit(1);
   }
@@ -101,7 +105,7 @@ async function createProject(projectName, template = "basic") {
 
   fs.writeFileSync(
     path.join(projectPath, "package.json"),
-    JSON.stringify(packageJson, null, 2)
+    JSON.stringify(packageJson, null, 2),
   );
   logSuccess("Created package.json");
 
@@ -163,7 +167,7 @@ function updateProjectName(projectPath, projectName) {
     let content = fs.readFileSync(indexHtmlPath, "utf8");
     content = content.replace(
       /<title>.*<\/title>/,
-      `<title>${projectName}</title>`
+      `<title>${projectName}</title>`,
     );
     fs.writeFileSync(indexHtmlPath, content);
   }
@@ -177,17 +181,38 @@ function updateProjectName(projectPath, projectName) {
   }
 }
 
+function showHelp() {
+  log(
+    "\n📦 create-openscript-app - OpenScript Project Scaffolding Tool\n",
+    "bright",
+  );
+  log("Usage:", "cyan");
+  log("  npx create-openscript-app <project-name> [template]\n", "cyan");
+  log("Arguments:", "cyan");
+  log("  project-name  Name of your new project (required)", "cyan");
+  log("  template      Template to use (optional, default: basic)\n", "cyan");
+  log("Available templates:", "cyan");
+  log("  basic      - Basic OpenScript project with Vite", "cyan");
+  log("  tailwind   - Project with TailwindCSS integration", "cyan");
+  log("  bootstrap  - Project with Bootstrap 5 integration\n", "cyan");
+  log("Examples:", "cyan");
+  log("  npx create-openscript-app my-app", "cyan");
+  log("  npx create-openscript-app my-app tailwind", "cyan");
+  log("  npx create-openscript-app my-app bootstrap\n", "cyan");
+}
+
 // Parse command line arguments
 const args = process.argv.slice(2);
 
+// Handle help flag
+if (args.includes("--help") || args.includes("-h")) {
+  showHelp();
+  process.exit(0);
+}
+
 if (args.length === 0) {
   log("\n❌ Please specify a project name\n", "red");
-  log("Usage: npm create ojs-app <project-name> [template]\n", "cyan");
-  log("   or: npx create-ojs-app <project-name> [template]\n", "cyan");
-  log("Available templates:", "cyan");
-  log("  basic      - Basic OpenScript project (default)", "cyan");
-  log("  tailwind   - Project with TailwindCSS integration", "cyan");
-  log("  bootstrap  - Project with Bootstrap 5 integration\n", "cyan");
+  showHelp();
   process.exit(1);
 }
 
@@ -197,7 +222,7 @@ const template = args[1] || "basic";
 // Validate project name
 if (!/^[a-z0-9-_]+$/.test(projectName)) {
   logError(
-    "Project name can only contain lowercase letters, numbers, hyphens, and underscores"
+    "Project name can only contain lowercase letters, numbers, hyphens, and underscores",
   );
   process.exit(1);
 }

packages/create-openscript-app/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "create-openscript-app",
+  "version": "1.0.0",
+  "description": "CLI to scaffold OpenScript projects - Create modern web apps with OpenScriptJs",
+  "type": "module",
+  "bin": {
+    "create-openscript-app": "index.js"
+  },
+  "files": [
+    "index.js",
+    "templates"
+  ],
+  "keywords": [
+    "openscript",
+    "openscriptjs",
+    "scaffold",
+    "cli",
+    "create-app",
+    "vite",
+    "frontend",
+    "framework"
+  ],
+  "author": "Levi Kamara Zwannah",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OpenScriptJs/modular-openscript.git",
+    "directory": "packages/create-openscript-app"
+  },
+  "bugs": {
+    "url": "https://github.com/OpenScriptJs/modular-openscript/issues"
+  },
+  "homepage": "https://github.com/OpenScriptJs/modular-openscript#readme",
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}

packages/create-openscript-app/templates/basic/.gitignore

@@ -0,0 +1,33 @@
+# Dependencies
+node_modules
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+
+# Build outputs
+dist
+dist-ssr
+*.local
+
+# Editor
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Environment
+.env
+.env.local
+.env.*.local

packages/create-openscript-app/templates/basic/README.md

@@ -0,0 +1,42 @@
+# {{PROJECT_NAME}}
+
+A new OpenScript project created with `create-ojs-app`.
+
+## Getting Started
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+
+# Build for production
+npm run build
+```
+
+## Project Structure
+
+```
+src/
+├── components/     # OpenScript components
+│   ├── App.js     # Root component
+│   └── Counter.js # Example counter component
+├── style.css      # Global styles
+└── main.js        # Application entry point
+```
+
+## Learn More
+
+- [OpenScript Documentation](https://github.com/yourusername/openscriptjs)
+- [OpenScript Examples](https://github.com/yourusername/openscriptjs/tree/main/examples)
+
+## Features
+
+- ⚡️ Fast development with Vite
+- 🎨 Component-based architecture
+- 📦 Reactive state management
+- 🔄 Built-in routing
+- 🎯 Event-driven communication
+
+Enjoy building with OpenScript! 🚀

packages/create-openscript-app/templates/basic/index.html

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

packages/create-openscript-app/templates/basic/src/components/AboutUs.js

@@ -0,0 +1,14 @@
+import {Component, app} from "modular-openscriptjs";
+
+const h = app("h");
+
+export default class AboutUs extends Component {
+    render(...args) {
+        return h.div(
+            { class: "about-us" },
+            h.h1("About Us"),
+            h.p("This is the about page"),
+            ...args
+        );
+    }
+}