webspresso 0.0.2 → 0.0.4

package/README.md

@@ -10,6 +10,8 @@ A minimal, file-based SSR framework for Node.js with Nunjucks templating.
 - **Built-in i18n**: JSON-based translations with automatic locale detection
 - **Lifecycle Hooks**: Global and route-level hooks for request processing
 - **Template Helpers**: Laravel-inspired helper functions available in templates
+- **Plugin System**: Extensible architecture with version control and inter-plugin communication
+- **Built-in Plugins**: Sitemap generator, analytics integration (Google, Yandex, Bing)
 
 ## Installation
 
@@ -184,13 +186,267 @@ Creates and configures the Express app.
   - `true` or `undefined`: Use default secure configuration
   - `false`: Disable Helmet
   - `Object`: Custom Helmet configuration (merged with defaults)
+- `middlewares` (optional): Named middleware registry for routes
 
-**Default Helmet Configuration:**
-- CSP disabled in development, enabled in production
-- HSTS, XSS protection, frame guard, and other security headers enabled
-- Tailwind CSS inline styles allowed in CSP
+**Example with middlewares:**
 
-**Returns:** `{ app, nunjucksEnv }`
+```javascript
+const { createApp } = require('webspresso');
+
+const { app } = createApp({
+  pagesDir: './pages',
+  viewsDir: './views',
+  middlewares: {
+    auth: (req, res, next) => {
+      if (!req.session?.user) {
+        return res.redirect('/login');
+      }
+      next();
+    },
+    admin: (req, res, next) => {
+      if (req.session?.user?.role !== 'admin') {
+        return res.status(403).send('Forbidden');
+      }
+      next();
+    },
+    rateLimit: require('express-rate-limit')({ windowMs: 60000, max: 100 })
+  }
+});
+```
+
+Then use in route configs by name:
+
+```javascript
+// pages/admin/index.js
+module.exports = {
+  middleware: ['auth', 'admin'], // Use named middlewares
+  load(req, ctx) { ... }
+};
+
+// pages/api/data.get.js
+module.exports = {
+  middleware: ['auth', 'rateLimit'],
+  handler: (req, res) => res.json({ data: 'protected' })
+};
+```
+
+**Custom Error Pages:**
+
+```javascript
+const { createApp } = require('webspresso');
+
+const { app } = createApp({
+  pagesDir: './pages',
+  viewsDir: './views',
+  errorPages: {
+    // Option 1: Custom handler function
+    notFound: (req, res) => {
+      res.render('errors/404.njk', { url: req.url });
+    },
+    
+    // Option 2: Template path (rendered with Nunjucks)
+    serverError: 'errors/500.njk'
+  }
+});
+```
+
+Error templates receive these variables:
+- `404.njk`: `{ url, method }`
+- `500.njk`: `{ error, status, isDev }`
+
+**Asset Management:**
+
+Configure asset handling with versioning and manifest support:
+
+```javascript
+const { createApp } = require('webspresso');
+const path = require('path');
+
+const { app } = createApp({
+  pagesDir: './pages',
+  viewsDir: './views',
+  publicDir: './public',
+  assets: {
+    // Option 1: Simple versioning (cache busting)
+    version: '1.2.3',  // or process.env.APP_VERSION
+    
+    // Option 2: Manifest file (Vite, Webpack, etc.)
+    manifestPath: path.join(__dirname, 'public/.vite/manifest.json'),
+    
+    // URL prefix for assets
+    prefix: '/static'
+  }
+});
+```
+
+Use asset helpers in templates:
+
+```njk
+{# Using fsy helpers (auto-resolved) #}
+<link rel="stylesheet" href="{{ fsy.asset('/css/style.css') }}">
+
+{# Or generate full HTML tags #}
+{{ fsy.css('/css/style.css') | safe }}
+{{ fsy.js('/js/app.js', { defer: true, type: 'module' }) | safe }}
+{{ fsy.img('/images/logo.png', 'Site Logo', { class: 'logo', loading: 'lazy' }) | safe }}
+```
+
+Asset helpers available in `fsy`:
+- `asset(path)` - Returns versioned/manifest-resolved URL
+- `css(href, attrs)` - Generates `<link>` tag
+- `js(src, attrs)` - Generates `<script>` tag
+- `img(src, alt, attrs)` - Generates `<img>` tag
+
+**Manifest Support:**
+
+Works with Vite and Webpack manifest formats:
+
+```json
+// Vite manifest format (.vite/manifest.json)
+{
+  "css/style.css": { "file": "assets/style-abc123.css" },
+  "js/app.js": { "file": "assets/app-xyz789.js" }
+}
+
+// Webpack manifest format
+{
+  "/css/style.css": "/dist/style.abc123.css",
+  "/js/app.js": "/dist/app.xyz789.js"
+}
+```
+
+**Returns:** `{ app, nunjucksEnv, pluginManager }`
+
+## Plugin System
+
+Webspresso has a built-in plugin system with version control and dependency management.
+
+### Using Plugins
+
+```javascript
+const { createApp } = require('webspresso');
+const { sitemapPlugin, analyticsPlugin } = require('webspresso/plugins');
+
+const { app } = createApp({
+  pagesDir: './pages',
+  viewsDir: './views',
+  plugins: [
+    sitemapPlugin({
+      hostname: 'https://example.com',
+      exclude: ['/admin/*', '/api/*'],
+      i18n: true,
+      locales: ['en', 'tr']
+    }),
+    analyticsPlugin({
+      google: {
+        measurementId: 'G-XXXXXXXXXX',
+        verificationCode: 'xxxxx'
+      },
+      yandex: {
+        counterId: '12345678',
+        verificationCode: 'xxxxx'
+      },
+      bing: {
+        uetId: '12345678',
+        verificationCode: 'xxxxx'
+      }
+    })
+  ]
+});
+```
+
+### Built-in Plugins
+
+**Sitemap Plugin:**
+- Generates `/sitemap.xml` from routes automatically
+- Excludes dynamic routes and API endpoints
+- Supports i18n with hreflang tags
+- Generates `/robots.txt`
+
+**Analytics Plugin:**
+- Google Analytics (GA4) and Google Ads
+- Google Tag Manager
+- Yandex.Metrika
+- Microsoft/Bing UET
+- Facebook Pixel
+- Verification meta tags for all services
+
+Template helpers from analytics plugin:
+
+```njk
+<head>
+  {{ fsy.verificationTags() | safe }}
+  {{ fsy.analyticsHead() | safe }}
+</head>
+<body>
+  {{ fsy.analyticsBodyOpen() | safe }}
+  ...
+</body>
+```
+
+Individual helpers: `gtag()`, `gtm()`, `gtmNoscript()`, `yandexMetrika()`, `bingUET()`, `facebookPixel()`, `allAnalytics()`
+
+### Creating Custom Plugins
+
+```javascript
+const myPlugin = {
+  name: 'my-plugin',
+  version: '1.0.0',
+  
+  // Optional: depend on other plugins
+  dependencies: {
+    'analytics': '^1.0.0'
+  },
+  
+  // Optional: expose API for other plugins
+  api: {
+    getData() { return this.data; }
+  },
+  
+  // Called during registration
+  register(ctx) {
+    // Access Express app
+    ctx.app.use((req, res, next) => next());
+    
+    // Add template helpers
+    ctx.addHelper('myHelper', () => 'Hello!');
+    
+    // Add Nunjucks filters
+    ctx.addFilter('myFilter', (val) => val.toUpperCase());
+    
+    // Use other plugins
+    const analytics = ctx.usePlugin('analytics');
+  },
+  
+  // Called after all routes are mounted
+  onRoutesReady(ctx) {
+    // Access route metadata
+    console.log('Routes:', ctx.routes);
+    
+    // Add custom routes
+    ctx.addRoute('get', '/my-route', (req, res) => {
+      res.json({ hello: 'world' });
+    });
+  },
+  
+  // Called before server starts
+  onReady(ctx) {
+    console.log('Server ready!');
+  }
+};
+
+// Use as factory function for configuration
+function myPluginFactory(options = {}) {
+  return {
+    name: 'my-plugin',
+    version: '1.0.0',
+    _options: options,
+    register(ctx) {
+      // ctx.options contains the passed options
+    }
+  };
+}
+```
 
 ## File-Based Routing
 

package/index.js

@@ -12,7 +12,19 @@ const {
   createTranslator,
   detectLocale
 } = require('./src/file-router');
-const { createHelpers, utils } = require('./src/helpers');
+const { 
+  createHelpers, 
+  utils, 
+  AssetManager, 
+  configureAssets, 
+  getAssetManager 
+} = require('./src/helpers');
+const {
+  PluginManager,
+  createPluginManager,
+  getPluginManager,
+  resetPluginManager
+} = require('./src/plugin-manager');
 
 module.exports = {
   // Main API
@@ -29,6 +41,17 @@ module.exports = {
   
   // Template helpers
   createHelpers,
-  utils
+  utils,
+  
+  // Asset management
+  AssetManager,
+  configureAssets,
+  getAssetManager,
+  
+  // Plugin system
+  PluginManager,
+  createPluginManager,
+  getPluginManager,
+  resetPluginManager
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webspresso",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Minimal, production-ready SSR framework for Node.js with file-based routing, Nunjucks templating, built-in i18n, and CLI tooling",
   "main": "index.js",
   "bin": {

package/src/file-router.js

@@ -272,16 +272,50 @@ function detectLocale(req) {
   return process.env.DEFAULT_LOCALE || 'en';
 }
 
+/**
+ * Resolve middleware from config - supports both functions and named strings
+ * @param {Array} middlewareConfig - Array of middleware functions or names
+ * @param {Object} middlewareRegistry - Named middleware registry
+ * @returns {Array} Array of resolved middleware functions
+ */
+function resolveMiddlewares(middlewareConfig, middlewareRegistry = {}) {
+  if (!middlewareConfig || !Array.isArray(middlewareConfig)) {
+    return [];
+  }
+  
+  return middlewareConfig.map((mw, index) => {
+    if (typeof mw === 'function') {
+      return mw;
+    }
+    
+    if (typeof mw === 'string') {
+      const resolved = middlewareRegistry[mw];
+      if (!resolved) {
+        throw new Error(`Middleware "${mw}" not found in registry. Available: ${Object.keys(middlewareRegistry).join(', ') || 'none'}`);
+      }
+      if (typeof resolved !== 'function') {
+        throw new Error(`Middleware "${mw}" must be a function`);
+      }
+      return resolved;
+    }
+    
+    throw new Error(`Invalid middleware at index ${index}: must be a function or string name`);
+  });
+}
+
 /**
  * Mount all pages as routes on the Express app
  * @param {Object} app - Express app
  * @param {Object} options - Options
  * @param {string} options.pagesDir - Pages directory path
  * @param {Object} options.nunjucks - Nunjucks environment
+ * @param {Object} options.middlewares - Named middleware registry
+ * @param {Object} options.pluginManager - Plugin manager instance
  * @param {boolean} options.silent - Suppress console output
+ * @returns {Array} Route metadata for plugins
  */
 function mountPages(app, options) {
-  const { pagesDir, nunjucks, silent = false } = options;
+  const { pagesDir, nunjucks, middlewares = {}, pluginManager = null, silent = false } = options;
   const isDev = process.env.NODE_ENV !== 'production';
   const log = silent ? () => {} : console.log.bind(console);
   
@@ -353,6 +387,7 @@ function mountPages(app, options) {
   for (const route of sortRoutes(apiRoutes)) {
     const handler = require(route.fullPath);
     const handlerFn = typeof handler === 'function' ? handler : handler.default || handler.handler;
+    const routeMiddleware = handler.middleware;
     
     if (typeof handlerFn !== 'function') {
       console.warn(`API route ${route.file} does not export a function`);
@@ -372,6 +407,20 @@ function mountPages(app, options) {
           ? currentHandler 
           : currentHandler.default || currentHandler.handler;
         
+        // Run middleware if defined
+        const mwConfig = isDev ? currentHandler.middleware : routeMiddleware;
+        if (mwConfig) {
+          const resolvedMw = resolveMiddlewares(mwConfig, middlewares);
+          for (const mw of resolvedMw) {
+            await new Promise((resolve, reject) => {
+              mw(req, res, (err) => {
+                if (err) reject(err);
+                else resolve();
+              });
+            });
+          }
+        }
+        
         await fn(req, res, next);
       } catch (err) {
         console.error(`API error ${route.routePath}:`, err);
@@ -397,7 +446,10 @@ function mountPages(app, options) {
         const config = loadRouteConfig(route.configPath, isDev);
         const routeHooks = config?.hooks || {};
         
-        // Create context
+        // Create context with plugin helpers merged
+        const baseHelpers = createHelpers({ req, res, locale });
+        const pluginHelpers = pluginManager ? pluginManager.getHelpers() : {};
+        
         const ctx = {
           req,
           res,
@@ -413,7 +465,7 @@ function mountPages(app, options) {
             indexable: true,
             canonical: null
           },
-          fsy: createHelpers({ req, res, locale })
+          fsy: { ...baseHelpers, ...pluginHelpers }
         };
         
         // Execute hooks: onRequest
@@ -429,8 +481,9 @@ function mountPages(app, options) {
         await executeHook(routeHooks, 'beforeMiddleware', ctx);
         
         // Run route middleware
-        if (config?.middleware && Array.isArray(config.middleware)) {
-          for (const mw of config.middleware) {
+        if (config?.middleware) {
+          const resolvedMiddlewares = resolveMiddlewares(config.middleware, middlewares);
+          for (const mw of resolvedMiddlewares) {
             await new Promise((resolve, reject) => {
               mw(req, res, (err) => {
                 if (err) reject(err);
@@ -506,6 +559,26 @@ function mountPages(app, options) {
     
     log(`  GET ${route.routePath} -> ${route.file}`);
   }
+  
+  // Return route metadata for plugins
+  const routeMetadata = [
+    ...ssrRoutes.map(r => ({
+      type: 'ssr',
+      method: 'get',
+      pattern: r.routePath,
+      file: r.file,
+      isDynamic: r.routePath.includes(':') || r.routePath.includes('*')
+    })),
+    ...apiRoutes.map(r => ({
+      type: 'api',
+      method: r.method,
+      pattern: r.routePath,
+      file: r.file,
+      isDynamic: r.routePath.includes(':') || r.routePath.includes('*')
+    }))
+  ];
+  
+  return routeMetadata;
 }
 
 module.exports = {
@@ -515,6 +588,7 @@ module.exports = {
   scanDirectory,
   loadI18n,
   createTranslator,
-  detectLocale
+  detectLocale,
+  resolveMiddlewares
 };
 

package/src/helpers.js

@@ -4,6 +4,167 @@
  */
 
 const querystring = require('querystring');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Asset Manager - handles asset paths, versioning, and manifest
+ */
+class AssetManager {
+  constructor(options = {}) {
+    this.publicDir = options.publicDir || 'public';
+    this.manifestPath = options.manifestPath || null;
+    this.manifest = null;
+    this.version = options.version || null;
+    this.prefix = options.prefix || '';
+    
+    // Load manifest if path provided
+    if (this.manifestPath) {
+      this.loadManifest();
+    }
+  }
+  
+  /**
+   * Load asset manifest file (Vite, Webpack, etc.)
+   */
+  loadManifest() {
+    try {
+      const fullPath = path.resolve(this.manifestPath);
+      if (fs.existsSync(fullPath)) {
+        const content = fs.readFileSync(fullPath, 'utf-8');
+        this.manifest = JSON.parse(content);
+      }
+    } catch (err) {
+      console.warn('Failed to load asset manifest:', err.message);
+      this.manifest = null;
+    }
+  }
+  
+  /**
+   * Resolve asset path from manifest or add version
+   * @param {string} assetPath - Asset path
+   * @returns {string}
+   */
+  resolve(assetPath) {
+    // Remove leading slash for manifest lookup
+    const lookupPath = assetPath.replace(/^\//, '');
+    
+    // Check manifest first
+    if (this.manifest) {
+      // Vite manifest format
+      if (this.manifest[lookupPath]) {
+        const entry = this.manifest[lookupPath];
+        const resolved = typeof entry === 'string' ? entry : entry.file;
+        return this.prefix + '/' + resolved;
+      }
+      
+      // Webpack manifest format (direct mapping)
+      if (this.manifest[assetPath]) {
+        return this.prefix + this.manifest[assetPath];
+      }
+    }
+    
+    // Add version query string if provided
+    let finalPath = assetPath.startsWith('/') ? assetPath : '/' + assetPath;
+    finalPath = this.prefix + finalPath;
+    
+    if (this.version) {
+      const separator = finalPath.includes('?') ? '&' : '?';
+      finalPath += `${separator}v=${this.version}`;
+    }
+    
+    return finalPath;
+  }
+  
+  /**
+   * Get asset URL
+   */
+  asset(assetPath) {
+    return this.resolve(assetPath);
+  }
+  
+  /**
+   * Generate CSS link tag
+   */
+  css(href, attributes = {}) {
+    const resolvedHref = this.resolve(href);
+    const attrs = this.buildAttributes({
+      rel: 'stylesheet',
+      href: resolvedHref,
+      ...attributes
+    });
+    return `<link ${attrs}>`;
+  }
+  
+  /**
+   * Generate JS script tag
+   */
+  js(src, attributes = {}) {
+    const resolvedSrc = this.resolve(src);
+    const attrs = this.buildAttributes({
+      src: resolvedSrc,
+      ...attributes
+    });
+    return `<script ${attrs}></script>`;
+  }
+  
+  /**
+   * Generate image tag
+   */
+  img(src, alt = '', attributes = {}) {
+    const resolvedSrc = this.resolve(src);
+    const attrs = this.buildAttributes({
+      src: resolvedSrc,
+      alt,
+      ...attributes
+    });
+    return `<img ${attrs}>`;
+  }
+  
+  /**
+   * Build HTML attributes string
+   */
+  buildAttributes(attrs) {
+    return Object.entries(attrs)
+      .filter(([_, v]) => v !== undefined && v !== null && v !== false)
+      .map(([k, v]) => v === true ? k : `${k}="${this.escapeHtml(String(v))}"`)
+      .join(' ');
+  }
+  
+  /**
+   * Escape HTML special characters
+   */
+  escapeHtml(str) {
+    return str
+      .replace(/&/g, '&amp;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#39;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;');
+  }
+}
+
+// Global asset manager instance
+let globalAssetManager = null;
+
+/**
+ * Configure global asset manager
+ * @param {Object} options - Asset manager options
+ */
+function configureAssets(options = {}) {
+  globalAssetManager = new AssetManager(options);
+  return globalAssetManager;
+}
+
+/**
+ * Get or create asset manager
+ */
+function getAssetManager() {
+  if (!globalAssetManager) {
+    globalAssetManager = new AssetManager();
+  }
+  return globalAssetManager;
+}
 
 /**
  * Create the fsy helper object bound to the current request context
@@ -217,6 +378,47 @@ function createHelpers(ctx) {
         return regex.test(currentPath);
       }
       return false;
+    },
+
+    // Asset helpers
+    /**
+     * Get asset URL with versioning/manifest support
+     * @param {string} assetPath - Asset path
+     * @returns {string}
+     */
+    asset(assetPath) {
+      return getAssetManager().asset(assetPath);
+    },
+
+    /**
+     * Generate CSS link tag
+     * @param {string} href - CSS file path
+     * @param {Object} attrs - Additional attributes
+     * @returns {string}
+     */
+    css(href, attrs = {}) {
+      return getAssetManager().css(href, attrs);
+    },
+
+    /**
+     * Generate JS script tag
+     * @param {string} src - JS file path
+     * @param {Object} attrs - Additional attributes
+     * @returns {string}
+     */
+    js(src, attrs = {}) {
+      return getAssetManager().js(src, attrs);
+    },
+
+    /**
+     * Generate image tag
+     * @param {string} src - Image file path
+     * @param {string} alt - Alt text
+     * @param {Object} attrs - Additional attributes
+     * @returns {string}
+     */
+    img(src, alt = '', attrs = {}) {
+      return getAssetManager().img(src, alt, attrs);
     }
   };
 }
@@ -270,6 +472,9 @@ const utils = {
 
 module.exports = {
   createHelpers,
-  utils
+  utils,
+  AssetManager,
+  configureAssets,
+  getAssetManager
 };