asjs-express 1.3.0 → 1.4.0

package/README.md

@@ -28,6 +28,7 @@ The intention is simple: this should read like something a careful team would ac
 - Built-in client router with transitions, prefetch, and loading bar support
 - Async form enhancement for marked forms
 - Plugin and hook support for Express projects that need to grow over time
+- npx project scaffolding so a new ASJS app can be created with starter files in one command
 - Package-served assets, so you do not have to manually copy router files into your public folder
 
 ### Install
@@ -36,6 +37,37 @@ The intention is simple: this should read like something a careful team would ac
 npm install asjs-express
 ```
 
+### Create a new app with npx
+
+ASJS now includes a small project generator.
+If you want a React or Next.js-style bootstrap flow, you can create a fresh project folder with one command.
+
+```bash
+npx asjs-express my-app
+```
+
+That command creates a ready-to-run ASJS project with `app.js`, `views/layouts/main.asjs`, `views/home.asjs`, `package.json`, `.gitignore`, and a small README.
+
+You can also choose a slightly richer starter that already includes two routes and the newer helper API:
+
+```bash
+npx asjs-express create my-app --template starter
+```
+
+Useful flags:
+
+- `--template minimal`
+- `--template starter`
+- `--skip-install`
+- `--force`
+
+After generation:
+
+```bash
+cd my-app
+npm run dev
+```
+
 ### Quick start
 
 ```js
@@ -690,6 +722,7 @@ WebAS yüzeyi, bu iki geliştiricinin birlikte şekillendirdiği düzenli, açı
 - Geçiş, prefetch ve loading bar destekli istemci yönlendirmesi
 - İşaretli formlar için dahili async form akışı
 - Büyüyen Express projeleri için plugin ve hook desteği
+- Tek komutla başlangıç dosyaları oluşturan npx proje oluşturucu
 - Public klasöre dosya kopyalamadan paket içinden asset servisi
 
 ### Kurulum
@@ -698,6 +731,37 @@ WebAS yüzeyi, bu iki geliştiricinin birlikte şekillendirdiği düzenli, açı
 npm install asjs-express
 ```
 
+### npx ile yeni proje oluşturma
+
+ASJS artık küçük bir proje oluşturucu ile geliyor.
+React veya Next.js tarzı bir başlangıç akışı istiyorsan tek komutla yeni proje klasörü oluşturabilirsin.
+
+```bash
+npx asjs-express my-app
+```
+
+Bu komut çalışan bir ASJS projesi üretir. İçine `app.js`, `views/layouts/main.asjs`, `views/home.asjs`, `package.json`, `.gitignore` ve kısa bir README koyar.
+
+Biraz daha dolu bir başlangıç istersen iki route ve yeni helper API ile gelen starter şablonunu seçebilirsin:
+
+```bash
+npx asjs-express create my-app --template starter
+```
+
+Kullanışlı bayraklar:
+
+- `--template minimal`
+- `--template starter`
+- `--skip-install`
+- `--force`
+
+Üretimden sonra:
+
+```bash
+cd my-app
+npm run dev
+```
+
 ### Hızlı başlangıç
 
 ```js

package/bin/create-asjs-app.js

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const packageJson = require('../package.json');
+
+const TEMPLATE_REGISTRY = {
+  minimal: {
+    label: 'Minimal starter',
+    directory: path.join(__dirname, '..', 'templates', 'minimal')
+  },
+  starter: {
+    label: 'Starter app',
+    directory: path.join(__dirname, '..', 'templates', 'starter')
+  }
+};
+
+function printHelp() {
+  console.log(`ASJS project creator\n\nUsage:\n  npx asjs-express my-app\n  npx asjs-express create my-app --template starter\n\nOptions:\n  --template <name>   Template to use: ${Object.keys(TEMPLATE_REGISTRY).join(', ')}\n  --skip-install      Do not run npm install automatically\n  --force             Allow writing into an existing directory\n  --help              Show this help message\n`);
+}
+
+function parseArgs(argv) {
+  const args = [...argv];
+  const options = {
+    force: false,
+    skipInstall: false,
+    template: 'minimal'
+  };
+  let target = '';
+
+  if (args[0] === 'create') {
+    args.shift();
+  }
+
+  while (args.length) {
+    const current = args.shift();
+
+    if (!current) {
+      continue;
+    }
+
+    if (current === '--help' || current === '-h') {
+      options.help = true;
+      continue;
+    }
+
+    if (current === '--skip-install') {
+      options.skipInstall = true;
+      continue;
+    }
+
+    if (current === '--force') {
+      options.force = true;
+      continue;
+    }
+
+    if (current === '--template') {
+      options.template = String(args.shift() || '').trim() || options.template;
+      continue;
+    }
+
+    if (current.startsWith('--template=')) {
+      options.template = current.split('=')[1] || options.template;
+      continue;
+    }
+
+    if (!target) {
+      target = current;
+    }
+  }
+
+  return {
+    options,
+    target
+  };
+}
+
+function sanitizePackageName(value) {
+  return String(value || 'asjs-app')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9-_]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'asjs-app';
+}
+
+function toDisplayName(value) {
+  return String(value || 'ASJS App')
+    .replace(/[-_]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .split(' ')
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ') || 'ASJS App';
+}
+
+function ensureTargetDirectory(targetDirectory, force) {
+  if (!fs.existsSync(targetDirectory)) {
+    fs.mkdirSync(targetDirectory, { recursive: true });
+    return;
+  }
+
+  const stats = fs.statSync(targetDirectory);
+  if (!stats.isDirectory()) {
+    throw new Error(`Target exists but is not a directory: ${targetDirectory}`);
+  }
+
+  const existingEntries = fs.readdirSync(targetDirectory);
+  if (existingEntries.length > 0 && !force) {
+    throw new Error(`Target directory is not empty: ${targetDirectory}\nUse --force if you want to write files into it.`);
+  }
+}
+
+function renderTemplate(content, variables) {
+  return content.replace(/__([A-Z0-9_]+)__/g, (match, token) => {
+    return Object.prototype.hasOwnProperty.call(variables, token) ? variables[token] : match;
+  });
+}
+
+function resolveOutputFileName(fileName) {
+  if (fileName === 'gitignore.tpl') {
+    return '.gitignore';
+  }
+
+  return fileName.endsWith('.tpl') ? fileName.slice(0, -4) : fileName;
+}
+
+function copyTemplateDirectory(sourceDirectory, targetDirectory, variables) {
+  const entries = fs.readdirSync(sourceDirectory, { withFileTypes: true });
+
+  entries.forEach((entry) => {
+    const sourcePath = path.join(sourceDirectory, entry.name);
+    const outputName = resolveOutputFileName(entry.name);
+    const targetPath = path.join(targetDirectory, outputName);
+
+    if (entry.isDirectory()) {
+      fs.mkdirSync(targetPath, { recursive: true });
+      copyTemplateDirectory(sourcePath, targetPath, variables);
+      return;
+    }
+
+    const content = fs.readFileSync(sourcePath, 'utf8');
+    const rendered = renderTemplate(content, variables);
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    fs.writeFileSync(targetPath, rendered, 'utf8');
+  });
+}
+
+function runInstall(targetDirectory) {
+  const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const result = spawnSync(npmCommand, ['install'], {
+    cwd: targetDirectory,
+    stdio: 'inherit'
+  });
+
+  return result.status === 0;
+}
+
+function main() {
+  const { options, target } = parseArgs(process.argv.slice(2));
+
+  if (options.help || !target) {
+    printHelp();
+    process.exit(options.help ? 0 : 1);
+  }
+
+  const template = TEMPLATE_REGISTRY[options.template];
+  if (!template) {
+    console.error(`Unknown template: ${options.template}`);
+    console.error(`Available templates: ${Object.keys(TEMPLATE_REGISTRY).join(', ')}`);
+    process.exit(1);
+  }
+
+  const targetDirectory = path.resolve(process.cwd(), target);
+  const packageName = sanitizePackageName(path.basename(targetDirectory));
+  const displayName = toDisplayName(packageName);
+  const expressVersion = packageJson.dependencies && packageJson.dependencies.express
+    ? packageJson.dependencies.express
+    : '^4.21.2';
+
+  const variables = {
+    APP_TITLE: displayName,
+    ASJS_VERSION: packageJson.version,
+    EXPRESS_VERSION: expressVersion,
+    PACKAGE_NAME: packageName,
+    PORT: '3000',
+    TEMPLATE_LABEL: template.label,
+    YEAR: String(new Date().getFullYear())
+  };
+
+  try {
+    ensureTargetDirectory(targetDirectory, options.force);
+    copyTemplateDirectory(template.directory, targetDirectory, variables);
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+
+  console.log(`\nCreated ${template.label} in ${targetDirectory}`);
+
+  if (!options.skipInstall) {
+    console.log('\nInstalling dependencies...');
+    const installed = runInstall(targetDirectory);
+
+    if (!installed) {
+      console.log('\nDependency install did not complete successfully. You can run it manually:');
+      console.log(`  cd ${path.basename(targetDirectory)}`);
+      console.log('  npm install');
+      process.exit(1);
+    }
+  }
+
+  console.log('\nNext steps:');
+  console.log(`  cd ${path.basename(targetDirectory)}`);
+  if (options.skipInstall) {
+    console.log('  npm install');
+  }
+  console.log('  npm run dev');
+}
+
+main();

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "asjs-express",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Lightweight Express view engine with EJS-like templates, layouts, async page rendering, form enhancement, and a built-in client router.",
   "main": "index.js",
+  "bin": {
+    "asjs-express": "./bin/create-asjs-app.js",
+    "create-asjs-app": "./bin/create-asjs-app.js"
+  },
   "author": {
     "name": "Acarfx",
     "url": "https://acarfx.com"
@@ -21,9 +25,11 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "bin",
     "index.js",
     "lib",
-    "README.md"
+    "README.md",
+    "templates"
   ],
   "scripts": {
     "start": "node example-express/app.js",
@@ -36,14 +42,17 @@
   "keywords": [
     "asjs",
     "component",
+    "cli",
     "ejs",
     "express",
     "express-view-engine",
     "forms",
     "layout",
     "prefetch",
+    "scaffold",
     "server-rendered",
     "ssr",
+    "starter-template",
     "template-engine",
     "view-engine",
     "spa-navigation"

package/templates/minimal/README.md.tpl

@@ -0,0 +1,12 @@
+# __APP_TITLE__
+
+This project was generated with `npx asjs-express`.
+
+## Run
+
+```bash
+npm install
+npm run dev
+```
+
+Open http://localhost:__PORT__

package/templates/minimal/app.js.tpl

@@ -0,0 +1,29 @@
+const express = require('express');
+const { setupAsjs } = require('asjs-express');
+
+const app = express();
+const port = process.env.PORT || __PORT__;
+
+const asjs = setupAsjs(app, {
+  rootDir: __dirname,
+  defaultLayout: 'layouts/main',
+  navItems: [
+    { href: '/', label: 'Home', activeMode: 'exact' }
+  ],
+  transitions: 'fade',
+  prefetch: true,
+  loadingBar: true
+});
+
+app.get('/', asjs.page('home', {
+  title: '__APP_TITLE__',
+  headline: '__APP_TITLE__ is ready.',
+  description: 'Header, router, loading bar, and SPA-ready page transitions are already connected.',
+  nextStep: 'Add a second route whenever you need it. ASJS will keep the same internal navigation flow.'
+}));
+
+app.use(asjs.errors());
+
+app.listen(port, () => {
+  console.log(`__APP_TITLE__ running at http://localhost:${port}`);
+});

package/templates/minimal/gitignore.tpl

@@ -0,0 +1,4 @@
+node_modules/
+.env
+.DS_Store
+npm-debug.log*

package/templates/minimal/package.json.tpl

@@ -0,0 +1,15 @@
+{
+  "name": "__PACKAGE_NAME__",
+  "version": "1.0.0",
+  "private": true,
+  "description": "ASJS minimal starter generated by npx asjs-express",
+  "main": "app.js",
+  "scripts": {
+    "dev": "node app.js",
+    "start": "node app.js"
+  },
+  "dependencies": {
+    "asjs-express": "^__ASJS_VERSION__",
+    "express": "__EXPRESS_VERSION__"
+  }
+}

package/templates/minimal/views/home.asjs.tpl

@@ -0,0 +1,5 @@
+<section style="max-width: 720px; margin: 40px auto; padding: 24px;">
+  <h1><%= headline %></h1>
+  <p><%= description %></p>
+  <p><%= nextStep %></p>
+</section>

package/templates/minimal/views/layouts/main.asjs.tpl

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title><%= title %></title>
+    <%- asjs.clientTags({ preload: true, theme: true }) %>
+  </head>
+  <body<%- asjs.bodyAttrs() %>>
+    <%- asjs.progressMarkup() %>
+    <%- asjs.header() %>
+    <main class="view-frame"<%- asjs.viewAttrs() %>>
+      <%- body %>
+    </main>
+  </body>
+</html>

package/templates/starter/README.md.tpl

@@ -0,0 +1,12 @@
+# __APP_TITLE__
+
+This project was generated with `npx asjs-express --template starter`.
+
+## Run
+
+```bash
+npm install
+npm run dev
+```
+
+Open http://localhost:__PORT__

package/templates/starter/app.js.tpl

@@ -0,0 +1,54 @@
+const express = require('express');
+const { setupAsjs } = require('asjs-express');
+
+const app = express();
+const port = process.env.PORT || __PORT__;
+
+const asjs = setupAsjs(app, {
+  rootDir: __dirname,
+  defaultLayout: 'layouts/main',
+  navItems: [
+    { href: '/', label: 'Home', activeMode: 'exact' },
+    { href: '/about', label: 'About', activeMode: 'exact' }
+  ],
+  transitions: 'fade',
+  prefetch: true,
+  loadingBar: true
+});
+
+const buildPage = asjs.createPageModel({
+  pageDescription: '__APP_TITLE__ starter created by ASJS.',
+  renderSummary: []
+});
+
+app.get('/', asjs.createPageRoute('home', {
+  buildPage,
+  renderState: {
+    delay: 120,
+    label: 'Home page ready',
+    narrative: 'ASJS prepared the page model before the HTML response reached the browser.'
+  }
+}, () => ({
+  title: '__APP_TITLE__',
+  heroTitle: 'Welcome to __APP_TITLE__.',
+  heroText: 'This starter already includes the built-in header, SPA navigation, and a render-state example.'
+})));
+
+app.get('/about', asjs.createPageRoute('about', {
+  buildPage,
+  renderState: {
+    delay: 140,
+    label: 'About page ready',
+    narrative: 'The second route uses the same layout and internal navigation flow.'
+  }
+}, () => ({
+  title: 'About | __APP_TITLE__',
+  heroTitle: 'The starter is ready to grow.',
+  heroText: 'Add new routes, layouts, forms, and partials without leaving the ASJS server-rendered flow.'
+})));
+
+app.use(asjs.errors());
+
+app.listen(port, () => {
+  console.log(`__APP_TITLE__ running at http://localhost:${port}`);
+});

package/templates/starter/gitignore.tpl

@@ -0,0 +1,4 @@
+node_modules/
+.env
+.DS_Store
+npm-debug.log*

package/templates/starter/package.json.tpl

@@ -0,0 +1,15 @@
+{
+  "name": "__PACKAGE_NAME__",
+  "version": "1.0.0",
+  "private": true,
+  "description": "ASJS starter app generated by npx asjs-express",
+  "main": "app.js",
+  "scripts": {
+    "dev": "node app.js",
+    "start": "node app.js"
+  },
+  "dependencies": {
+    "asjs-express": "^__ASJS_VERSION__",
+    "express": "__EXPRESS_VERSION__"
+  }
+}

package/templates/starter/views/about.asjs.tpl

@@ -0,0 +1,10 @@
+<section style="max-width: 760px; margin: 40px auto; padding: 24px;">
+  <span>Starter about</span>
+  <h1><%= heroTitle %></h1>
+  <p><%= heroText %></p>
+  <div style="margin-top: 20px;">
+    <% renderSummary.forEach((item) => { %>
+      <div><strong><%= item.label %>:</strong> <%= item.value %></div>
+    <% }) %>
+  </div>
+</section>

package/templates/starter/views/home.asjs.tpl

@@ -0,0 +1,10 @@
+<section style="max-width: 760px; margin: 40px auto; padding: 24px;">
+  <span>Starter home</span>
+  <h1><%= heroTitle %></h1>
+  <p><%= heroText %></p>
+  <div style="margin-top: 20px;">
+    <% renderSummary.forEach((item) => { %>
+      <div><strong><%= item.label %>:</strong> <%= item.value %></div>
+    <% }) %>
+  </div>
+</section>

package/templates/starter/views/layouts/main.asjs.tpl

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title><%= title %></title>
+    <%- asjs.clientTags({ preload: true, theme: true }) %>
+  </head>
+  <body<%- asjs.bodyAttrs() %>>
+    <%- asjs.progressMarkup() %>
+    <%- asjs.header() %>
+    <main class="view-frame"<%- asjs.viewAttrs() %>>
+      <%- body %>
+    </main>
+  </body>
+</html>