npm - webspresso - Versions diffs - 0.0.3 → 0.0.4 - Mend

webspresso 0.0.3 → 0.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -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
@@ -313,7 +315,138 @@ Works with Vite and Webpack manifest formats:
 }
 ```
-**Returns:** `{ app, nunjucksEnv }`
+**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 CHANGED Viewed

@@ -19,6 +19,12 @@ const {
   configureAssets,
   getAssetManager
 } = require('./src/helpers');
+const {
+  PluginManager,
+  createPluginManager,
+  getPluginManager,
+  resetPluginManager
+} = require('./src/plugin-manager');
 module.exports = {
   // Main API
@@ -40,6 +46,12 @@ module.exports = {
   // Asset management
   AssetManager,
   configureAssets,
-  getAssetManager
+  getAssetManager,
+  // Plugin system
+  PluginManager,
+  createPluginManager,
+  getPluginManager,
+  resetPluginManager
 };

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "webspresso",
-  "version": "0.0.3",
+  "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 CHANGED Viewed

@@ -310,10 +310,12 @@ function resolveMiddlewares(middlewareConfig, middlewareRegistry = {}) {
  * @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, middlewares = {}, 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);
@@ -444,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,
@@ -460,7 +465,7 @@ function mountPages(app, options) {
             indexable: true,
             canonical: null
           },
-          fsy: createHelpers({ req, res, locale })
+          fsy: { ...baseHelpers, ...pluginHelpers }
         };
         // Execute hooks: onRequest
@@ -554,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 = {

package/src/plugin-manager.js ADDED Viewed

@@ -0,0 +1,451 @@
+/**
+ * Webspresso Plugin Manager
+ * Handles plugin registration, lifecycle, dependencies, and inter-plugin communication
+ */
+/**
+ * Simple semver comparison utilities
+ * (Lightweight alternative to full semver package)
+ */
+const semver = {
+  /**
+   * Parse version string to components
+   */
+  parse(version) {
+    if (!version) return null;
+    const match = version.match(/^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/);
+    if (!match) return null;
+    return {
+      major: parseInt(match[1], 10),
+      minor: parseInt(match[2], 10),
+      patch: parseInt(match[3], 10),
+      prerelease: match[4] || null
+    };
+  },
+  /**
+   * Compare two versions
+   * Returns: -1 if a < b, 0 if a == b, 1 if a > b
+   */
+  compare(a, b) {
+    const va = this.parse(a);
+    const vb = this.parse(b);
+    if (!va || !vb) return 0;
+    if (va.major !== vb.major) return va.major > vb.major ? 1 : -1;
+    if (va.minor !== vb.minor) return va.minor > vb.minor ? 1 : -1;
+    if (va.patch !== vb.patch) return va.patch > vb.patch ? 1 : -1;
+    return 0;
+  },
+  /**
+   * Check if version satisfies a range
+   * Supports: ^1.0.0, ~1.0.0, >=1.0.0, >1.0.0, <=1.0.0, <1.0.0, 1.0.0, *
+   */
+  satisfies(version, range) {
+    if (!range || range === '*') return true;
+    const v = this.parse(version);
+    if (!v) return false;
+    // Handle caret (^) - compatible with major version
+    if (range.startsWith('^')) {
+      const r = this.parse(range.slice(1));
+      if (!r) return false;
+      if (v.major !== r.major) return false;
+      if (v.major === 0) {
+        // For 0.x.x, minor must match
+        if (v.minor !== r.minor) return false;
+        return v.patch >= r.patch;
+      }
+      return this.compare(version, range.slice(1)) >= 0;
+    }
+    // Handle tilde (~) - compatible with minor version
+    if (range.startsWith('~')) {
+      const r = this.parse(range.slice(1));
+      if (!r) return false;
+      return v.major === r.major && v.minor === r.minor && v.patch >= r.patch;
+    }
+    // Handle >=
+    if (range.startsWith('>=')) {
+      return this.compare(version, range.slice(2)) >= 0;
+    }
+    // Handle >
+    if (range.startsWith('>') && !range.startsWith('>=')) {
+      return this.compare(version, range.slice(1)) > 0;
+    }
+    // Handle <=
+    if (range.startsWith('<=')) {
+      return this.compare(version, range.slice(2)) <= 0;
+    }
+    // Handle <
+    if (range.startsWith('<') && !range.startsWith('<=')) {
+      return this.compare(version, range.slice(1)) < 0;
+    }
+    // Exact match
+    return this.compare(version, range) === 0;
+  }
+};
+/**
+ * Simple glob/minimatch pattern matching
+ */
+function matchPattern(path, pattern) {
+  if (pattern === '*' || pattern === '**') return true;
+  // Convert glob to regex
+  const regexPattern = pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')  // Escape special regex chars
+    .replace(/\*\*/g, '{{GLOBSTAR}}')       // Temp placeholder for **
+    .replace(/\*/g, '[^/]*')                // * matches anything except /
+    .replace(/\{\{GLOBSTAR\}\}/g, '.*')     // ** matches everything
+    .replace(/\?/g, '.');                   // ? matches single char
+  const regex = new RegExp(`^${regexPattern}$`);
+  return regex.test(path);
+}
+/**
+ * Plugin Manager Class
+ */
+class PluginManager {
+  constructor() {
+    this.plugins = new Map();           // name -> plugin instance
+    this.pluginAPIs = new Map();        // name -> exposed API
+    this.registeredHelpers = new Map(); // name -> helper function
+    this.registeredFilters = new Map(); // name -> filter function
+    this.routes = [];                   // Collected route metadata
+    this.customRoutes = [];             // Routes added by plugins
+    this.app = null;
+    this.nunjucksEnv = null;
+  }
+  /**
+   * Register plugins with the manager
+   * @param {Array} plugins - Array of plugin definitions or factory functions
+   * @param {Object} context - Context object { app, nunjucksEnv, options }
+   */
+  async register(plugins, context) {
+    if (!plugins || !Array.isArray(plugins)) return;
+    this.app = context.app;
+    this.nunjucksEnv = context.nunjucksEnv;
+    // Normalize plugins (handle factory functions)
+    const normalizedPlugins = plugins.map(p => {
+      if (typeof p === 'function') {
+        // Already a factory that was called
+        return p;
+      }
+      return p;
+    });
+    // Validate and sort by dependencies
+    const sorted = this._resolveDependencyOrder(normalizedPlugins);
+    // Register each plugin in order
+    for (const plugin of sorted) {
+      await this._registerPlugin(plugin, context);
+    }
+  }
+  /**
+   * Resolve dependency order using topological sort
+   */
+  _resolveDependencyOrder(plugins) {
+    const graph = new Map();
+    const pluginMap = new Map();
+    // Build graph
+    for (const plugin of plugins) {
+      if (!plugin.name) {
+        throw new Error('Plugin must have a name');
+      }
+      if (pluginMap.has(plugin.name)) {
+        throw new Error(`Duplicate plugin name: ${plugin.name}`);
+      }
+      pluginMap.set(plugin.name, plugin);
+      graph.set(plugin.name, new Set(Object.keys(plugin.dependencies || {})));
+    }
+    // Topological sort (Kahn's algorithm)
+    const sorted = [];
+    const noIncoming = [];
+    // Find nodes with no dependencies
+    for (const [name, deps] of graph) {
+      // Filter to only include dependencies that are in our plugin list
+      const relevantDeps = new Set([...deps].filter(d => pluginMap.has(d)));
+      graph.set(name, relevantDeps);
+      if (relevantDeps.size === 0) {
+        noIncoming.push(name);
+      }
+    }
+    while (noIncoming.length > 0) {
+      const name = noIncoming.shift();
+      sorted.push(pluginMap.get(name));
+      // Remove this node from all dependencies
+      for (const [n, deps] of graph) {
+        if (deps.has(name)) {
+          deps.delete(name);
+          if (deps.size === 0 && !sorted.find(p => p.name === n)) {
+            noIncoming.push(n);
+          }
+        }
+      }
+    }
+    // Check for cycles
+    if (sorted.length !== plugins.length) {
+      const remaining = plugins.filter(p => !sorted.includes(p)).map(p => p.name);
+      throw new Error(`Circular dependency detected in plugins: ${remaining.join(', ')}`);
+    }
+    return sorted;
+  }
+  /**
+   * Register a single plugin
+   */
+  async _registerPlugin(plugin, context) {
+    // Validate dependencies
+    this._validateDependencies(plugin);
+    // Create plugin context
+    const ctx = this._createPluginContext(plugin, context);
+    // Store plugin
+    this.plugins.set(plugin.name, plugin);
+    // Store API if provided
+    if (plugin.api) {
+      // Bind API methods to plugin instance
+      const boundAPI = {};
+      for (const [key, value] of Object.entries(plugin.api)) {
+        boundAPI[key] = typeof value === 'function' ? value.bind(plugin) : value;
+      }
+      this.pluginAPIs.set(plugin.name, boundAPI);
+    }
+    // Call register hook
+    if (typeof plugin.register === 'function') {
+      await plugin.register(ctx);
+    }
+    // Apply registered helpers to nunjucks
+    this._applyHelpersAndFilters();
+  }
+  /**
+   * Validate plugin dependencies
+   */
+  _validateDependencies(plugin) {
+    if (!plugin.dependencies) return;
+    for (const [depName, versionRange] of Object.entries(plugin.dependencies)) {
+      const dep = this.plugins.get(depName);
+      if (!dep) {
+        throw new Error(
+          `Plugin "${plugin.name}" requires "${depName}" but it's not loaded`
+        );
+      }
+      if (dep.version && !semver.satisfies(dep.version, versionRange)) {
+        throw new Error(
+          `Plugin "${plugin.name}" requires "${depName}@${versionRange}" ` +
+          `but found v${dep.version}`
+        );
+      }
+    }
+  }
+  /**
+   * Create context object for plugin
+   */
+  _createPluginContext(plugin, context) {
+    const self = this;
+    return {
+      app: context.app,
+      options: plugin._options || {},
+      nunjucksEnv: context.nunjucksEnv,
+      /**
+       * Get another plugin's API
+       */
+      usePlugin(name) {
+        return self.pluginAPIs.get(name) || null;
+      },
+      /**
+       * Add a template helper (available as fsy.helperName())
+       */
+      addHelper(name, fn) {
+        self.registeredHelpers.set(name, fn);
+      },
+      /**
+       * Add a Nunjucks filter
+       */
+      addFilter(name, fn) {
+        self.registeredFilters.set(name, fn);
+      },
+      /**
+       * Add a custom route
+       */
+      addRoute(method, path, ...handlers) {
+        self.customRoutes.push({ method: method.toLowerCase(), path, handlers });
+      },
+      /**
+       * Get all registered routes (available after onRoutesReady)
+       */
+      get routes() {
+        return self.routes;
+      }
+    };
+  }
+  /**
+   * Apply registered helpers and filters to Nunjucks
+   */
+  _applyHelpersAndFilters() {
+    if (!this.nunjucksEnv) return;
+    // Add filters
+    for (const [name, fn] of this.registeredFilters) {
+      this.nunjucksEnv.addFilter(name, fn);
+    }
+  }
+  /**
+   * Get all registered helpers (to be merged with fsy)
+   */
+  getHelpers() {
+    const helpers = {};
+    for (const [name, fn] of this.registeredHelpers) {
+      helpers[name] = fn;
+    }
+    return helpers;
+  }
+  /**
+   * Set route metadata (called by file-router after mounting)
+   */
+  setRoutes(routes) {
+    this.routes = routes;
+  }
+  /**
+   * Mount custom routes added by plugins
+   */
+  mountCustomRoutes() {
+    for (const { method, path, handlers } of this.customRoutes) {
+      if (this.app && this.app[method]) {
+        this.app[method](path, ...handlers);
+      }
+    }
+  }
+  /**
+   * Call onRoutesReady hook on all plugins
+   */
+  async onRoutesReady(context) {
+    for (const [name, plugin] of this.plugins) {
+      if (typeof plugin.onRoutesReady === 'function') {
+        const ctx = this._createPluginContext(plugin, context);
+        await plugin.onRoutesReady(ctx);
+      }
+    }
+    // Mount any routes added during onRoutesReady
+    this.mountCustomRoutes();
+  }
+  /**
+   * Call onReady hook on all plugins
+   */
+  async onReady(context) {
+    for (const [name, plugin] of this.plugins) {
+      if (typeof plugin.onReady === 'function') {
+        const ctx = this._createPluginContext(plugin, context);
+        await plugin.onReady(ctx);
+      }
+    }
+  }
+  /**
+   * Get a plugin by name
+   */
+  getPlugin(name) {
+    return this.plugins.get(name);
+  }
+  /**
+   * Get a plugin's API by name
+   */
+  getPluginAPI(name) {
+    return this.pluginAPIs.get(name);
+  }
+  /**
+   * Check if a plugin is registered
+   */
+  hasPlugin(name) {
+    return this.plugins.has(name);
+  }
+  /**
+   * Get all registered plugin names
+   */
+  getPluginNames() {
+    return Array.from(this.plugins.keys());
+  }
+}
+// Singleton instance for global access
+let globalPluginManager = null;
+/**
+ * Get or create the global plugin manager
+ */
+function getPluginManager() {
+  if (!globalPluginManager) {
+    globalPluginManager = new PluginManager();
+  }
+  return globalPluginManager;
+}
+/**
+ * Create a new plugin manager (for testing)
+ */
+function createPluginManager() {
+  return new PluginManager();
+}
+/**
+ * Reset the global plugin manager (for testing)
+ */
+function resetPluginManager() {
+  globalPluginManager = null;
+}
+module.exports = {
+  PluginManager,
+  getPluginManager,
+  createPluginManager,
+  resetPluginManager,
+  semver,
+  matchPattern
+};

package/src/server.js CHANGED Viewed

@@ -9,6 +9,7 @@ const nunjucks = require('nunjucks');
 const { mountPages } = require('./file-router');
 const { configureAssets } = require('./helpers');
+const { createPluginManager } = require('./plugin-manager');
 /**
  * Get default Helmet configuration
@@ -117,6 +118,7 @@ function default500Html(err, isDev) {
  * @param {boolean} options.logging - Enable request logging (default: isDev)
  * @param {Object|boolean} options.helmet - Helmet configuration (default: auto-configured, false to disable)
  * @param {Object} options.middlewares - Named middleware registry for route configs
+ * @param {Array} options.plugins - Array of plugin definitions
  * @param {Object} options.assets - Asset manager configuration
  * @param {string} options.assets.manifestPath - Path to asset manifest file (Vite, Webpack)
  * @param {string} options.assets.version - Asset version for cache busting
@@ -124,7 +126,7 @@ function default500Html(err, isDev) {
  * @param {Object} options.errorPages - Custom error page handlers
  * @param {Function|string} options.errorPages.notFound - Custom 404 handler or template path
  * @param {Function|string} options.errorPages.serverError - Custom 500 handler or template path
- * @returns {Object} { app, nunjucksEnv }
+ * @returns {Object} { app, nunjucksEnv, pluginManager }
  */
 function createApp(options = {}) {
   const NODE_ENV = process.env.NODE_ENV || 'development';
@@ -138,10 +140,14 @@ function createApp(options = {}) {
     logging = isDev && !isTest,
     helmet: helmetConfig,
     middlewares = {},
+    plugins = [],
     assets: assetsConfig = {},
     errorPages = {}
   } = options;
+  // Create plugin manager
+  const pluginManager = createPluginManager();
   // Configure asset manager
   configureAssets({
     publicDir: publicDir || 'public',
@@ -213,6 +219,10 @@ function createApp(options = {}) {
     return d.toString();
   });
+  // Register plugins (synchronous part)
+  const pluginContext = { app, nunjucksEnv, options };
+  pluginManager.register(plugins, pluginContext);
   // Request logging middleware
   if (logging) {
     app.use((req, res, next) => {
@@ -229,13 +239,37 @@ function createApp(options = {}) {
   if (!isTest) {
     console.log('\nMounting routes:');
   }
-  mountPages(app, {
+  const routeMetadata = mountPages(app, {
     pagesDir,
     nunjucks: nunjucksEnv,
     middlewares,
+    pluginManager,
     silent: isTest
   });
+  // Set route metadata in plugin manager
+  pluginManager.setRoutes(routeMetadata);
+  // Call onRoutesReady hook synchronously (plugins should not be async in this phase)
+  // and mount any custom routes added by plugins
+  for (const [name, plugin] of pluginManager.plugins) {
+    if (typeof plugin.onRoutesReady === 'function') {
+      const ctx = {
+        app,
+        nunjucksEnv,
+        options,
+        routes: pluginManager.routes,
+        usePlugin: (n) => pluginManager.getPluginAPI(n),
+        addHelper: (n, fn) => pluginManager.registeredHelpers.set(n, fn),
+        addFilter: (n, fn) => pluginManager.registeredFilters.set(n, fn),
+        addRoute: (method, path, ...handlers) => {
+          app[method.toLowerCase()](path, ...handlers);
+        }
+      };
+      plugin.onRoutesReady(ctx);
+    }
+  }
   // 404 handler
   app.use((req, res) => {
     res.status(404);
@@ -302,7 +336,7 @@ function createApp(options = {}) {
     }
   });
-  return { app, nunjucksEnv };
+  return { app, nunjucksEnv, pluginManager };
 }
 // Export for use as library