zuby 1.0.47 → 1.0.49

package/config.d.ts

@@ -48,3 +48,7 @@ export type ExecutePluginsParams = Omit<ZubyHookParams, 'command' | 'logger' | '
  * @param plugins
  */
 export declare const normalizePlugins: (plugins: (ZubyPlugin | ZubyPlugin[] | VitePluginOption | VitePluginOption[])[]) => Promise<(ZubyPlugin | VitePlugin)[]>;
+/**
+ * Returns random build ID.
+ */
+export declare const generateDefaultBuildId: () => string;

package/config.js

@@ -1,6 +1,7 @@
 import { PLUGIN_HOOKS, } from './types.js';
 import { BUILD_CHUNKS_MANIFEST, ZUBY_CONFIG_FILE } from './constants.js';
 import { existsSync } from 'fs';
+import { randomBytes } from 'crypto';
 import { bundleRequire } from 'bundle-require';
 import { createLogger } from './logger/index.js';
 // Plugins
@@ -11,6 +12,7 @@ import manifestPlugin from './plugins/manifestPlugin/index.js';
 import prerenderPlugin from './plugins/prerenderPlugin/index.js';
 import standaloneBuildPlugin from './plugins/dependenciesPlugin/index.js';
 import preloadPlugin from './plugins/preloadPlugin/index.js';
+import { TEMPLATES } from './templates/types.js';
 let zubyInternalConfig;
 /**
  * Returns the path to the ZubyConfig file.
@@ -56,8 +58,57 @@ export const getZubyInternalConfig = async (configFilePath, cache = true) => {
         return zubyInternalConfig;
     const zubyConfig = await getZubyConfig(configFilePath);
     zubyConfig.configFilePath = configFilePath;
+    zubyConfig.templateFiles = zubyConfig.templateFiles || [];
+    zubyConfig.headElements = zubyConfig.headElements || [];
     // Run config setup hook
-    await executePlugins(zubyConfig, PLUGIN_HOOKS.ZubyConfigSetup);
+    await executePlugins(zubyConfig, PLUGIN_HOOKS.ZubyConfigSetup, {
+        addEntryTemplate: (filename) => zubyConfig.templateFiles?.push({
+            filename,
+            path: '/:path*',
+            templateType: TEMPLATES.entry,
+        }),
+        addAppTemplate: (filename, path = '/:path*') => zubyConfig.templateFiles?.push({
+            filename,
+            path,
+            templateType: TEMPLATES.app,
+        }),
+        addLayoutTemplate: (filename, path = '/:path*') => zubyConfig.templateFiles?.push({
+            filename,
+            path,
+            templateType: TEMPLATES.layout,
+        }),
+        addInnerLayoutTemplate: (filename, path = '/:path*') => zubyConfig.templateFiles?.push({
+            filename,
+            path,
+            templateType: TEMPLATES.innerLayout,
+        }),
+        addPageTemplate: (filename, path = '/:path*') => zubyConfig.templateFiles?.push({
+            filename,
+            path,
+            templateType: TEMPLATES.page,
+        }),
+        addErrorTemplate: (filename, path = '/:path*') => zubyConfig.templateFiles?.push({
+            filename,
+            path,
+            templateType: TEMPLATES.error,
+        }),
+        addLoaderTemplate: (filename, path = '/:path*') => zubyConfig.templateFiles?.push({
+            filename,
+            path,
+            templateType: TEMPLATES.loader,
+        }),
+        addPage: (filename, path = '/:path*') => zubyConfig.templateFiles?.push({
+            filename,
+            path,
+            templateType: TEMPLATES.page,
+        }),
+        addHandler: (filename, path = '/:path*') => zubyConfig.templateFiles?.push({
+            filename,
+            path,
+            templateType: TEMPLATES.handler,
+        }),
+        addToHead: (element) => zubyConfig.headElements?.push(element),
+    });
     validateConfig(zubyConfig);
     zubyInternalConfig = await mergeDefaultConfig(zubyConfig);
     // Run config done hook
@@ -103,6 +154,13 @@ export const mergeDefaultConfig = async (config) => {
     config.minifyCSS = config.minifyCSS ?? true;
     config.minifyHTML = config.minifyHTML ?? true;
     config.minifyJS = config.minifyJS ?? true;
+    // Build ID generator
+    config.generateBuildId = config.generateBuildId ?? generateDefaultBuildId;
+    // Global props
+    config.props = config.props ?? {};
+    config.serverProps = config.serverProps ?? {};
+    // Head elements
+    config.headElements = config.headElements ?? [];
     // Add logger
     config.customLogger =
         config.customLogger ??
@@ -134,6 +192,7 @@ export const mergeDefaultConfig = async (config) => {
     return {
         ...config,
         templateExtensions: ['js', 'jsx', 'ts', 'tsx'],
+        buildId: await config.generateBuildId(),
     };
 };
 /**
@@ -206,3 +265,9 @@ export const normalizePlugins = async (plugins) => {
         // Remove false, undefined, null values
         .filter(plugin => !!plugin);
 };
+/**
+ * Returns random build ID.
+ */
+export const generateDefaultBuildId = () => {
+    return randomBytes(8).toString('hex');
+};

package/context/index.d.ts

@@ -20,5 +20,9 @@ export declare class ZubyContext {
         locales: string[];
         defaultLocale: string;
     } | undefined;
+    get buildId(): string | undefined;
+    get props(): Record<string, any> | undefined;
+    get serverProps(): Record<string, any> | undefined;
+    get headElements(): string[] | undefined;
 }
 export declare const getContext: () => ZubyContext;

package/context/index.js

@@ -23,6 +23,18 @@ export class ZubyContext {
     get i18n() {
         return this.rawContext.i18n;
     }
+    get buildId() {
+        return this.rawContext.buildId;
+    }
+    get props() {
+        return this.rawContext.props;
+    }
+    get serverProps() {
+        return this.rawContext.serverProps;
+    }
+    get headElements() {
+        return this.rawContext.headElements;
+    }
 }
 const getRawContext = () => {
     return globalThis.ZubyRawContext;

package/context/types.d.ts

@@ -35,6 +35,10 @@ export interface ZubyRawContext {
      * @example 1.0.0
      */
     version?: string;
+    /**
+     * The build ID of the site.
+     */
+    buildId?: string;
     /**
      * The internalization config from ZubyConfig.
      * @example {
@@ -46,4 +50,21 @@ export interface ZubyRawContext {
         locales: string[];
         defaultLocale: string;
     };
+    /**
+     * The global props for the site
+     * that will be passed to all pages
+     * on both client and server side.
+     */
+    props?: Record<string, any>;
+    /**
+     * The global server props for the site
+     * that will be passed to all pages
+     * only on server side.
+     */
+    serverProps?: Record<string, any>;
+    /**
+     * Additional elements that should be added
+     * to the head of the page.
+     */
+    headElements?: string[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuby",
-  "version": "1.0.47",
+  "version": "1.0.49",
   "description": "Zuby.js is framework for building SPA apps using Vite",
   "type": "module",
   "main": "index.js",

package/pageContext/index.d.ts

@@ -10,6 +10,8 @@ export declare class ZubyPageContext {
     protected _headers: Headers;
     protected _cache: number;
     protected _props: Record<string, any>;
+    protected _serverProps: Record<string, any>;
+    protected _headElements: (string | (() => any))[];
     protected _zubyContext: ZubyContext;
     constructor(options: {
         url?: URL;
@@ -94,6 +96,24 @@ export declare class ZubyPageContext {
      */
     get props(): Record<string, any>;
     set props(value: Record<string, any>);
+    /**
+     * The server props that are available only in server-side
+     * environment and are not shared with the client.
+     * You can use this property to pass data from handler to layout template.
+     * Hint: You should not read them in page because the hydration would fail,
+     * but you can write them on page and read them in layout.
+     * @example { my: 'secret-value' }
+     */
+    get serverProps(): Record<string, any>;
+    set serverProps(value: Record<string, any>);
+    /**
+     * The global props from the ZubyConfig
+     */
+    get globalProps(): Record<string, any> | undefined;
+    /**
+     * The global server props from the ZubyConfig
+     */
+    get globalServerProps(): Record<string, any> | undefined;
     /**
      * The current status code that will be returned to the client.
      * This property has only effect in server-side.
@@ -172,4 +192,21 @@ export declare class ZubyPageContext {
      * was made by the Zuby.js pre-render build step.
      */
     get isPrerendering(): boolean;
+    /**
+     * The current build ID of the site.
+     * @example ecdf1a94cc9b4f4c
+     */
+    get buildId(): string | undefined;
+    /**
+     * Adds the given HTML string
+     * or Jsx Component to the head of the page
+     * when it's rendered on the server.
+     */
+    addToHead(element: string | (() => any)): void;
+    /**
+     * Returns array of all elements as string
+     * that should be added to the head of the page.
+     * @private
+     */
+    getHeadElements(): Promise<string[]>;
 }

package/pageContext/index.js

@@ -9,9 +9,11 @@ export class ZubyPageContext {
         this._clientAddress = options?.clientAddress;
         this._statusCode = options?.statusCode || 200;
         this._props = options?.props || {};
+        this._serverProps = {};
         this._cache = 0;
         this._headers = options?.headers || new Headers();
         this._zubyContext = options?.zubyContext || getContext();
+        this._headElements = [...(this._zubyContext.headElements || [])];
     }
     /**
      * The current URL of the page.
@@ -114,6 +116,35 @@ export class ZubyPageContext {
     set props(value) {
         this._props = value || {};
     }
+    /**
+     * The server props that are available only in server-side
+     * environment and are not shared with the client.
+     * You can use this property to pass data from handler to layout template.
+     * Hint: You should not read them in page because the hydration would fail,
+     * but you can write them on page and read them in layout.
+     * @example { my: 'secret-value' }
+     */
+    get serverProps() {
+        return {
+            ...(this._zubyContext.serverProps || {}),
+            ...(this._serverProps || {}),
+        };
+    }
+    set serverProps(value) {
+        this._serverProps = value || {};
+    }
+    /**
+     * The global props from the ZubyConfig
+     */
+    get globalProps() {
+        return this._zubyContext.props;
+    }
+    /**
+     * The global server props from the ZubyConfig
+     */
+    get globalServerProps() {
+        return this._zubyContext.serverProps;
+    }
     /**
      * The current status code that will be returned to the client.
      * This property has only effect in server-side.
@@ -225,4 +256,32 @@ export class ZubyPageContext {
     get isPrerendering() {
         return this._request?.headers?.get('user-agent') === 'zuby-prerender';
     }
+    /**
+     * The current build ID of the site.
+     * @example ecdf1a94cc9b4f4c
+     */
+    get buildId() {
+        return this._zubyContext.buildId;
+    }
+    /**
+     * Adds the given HTML string
+     * or Jsx Component to the head of the page
+     * when it's rendered on the server.
+     */
+    addToHead(element) {
+        this._headElements.push(element);
+    }
+    /**
+     * Returns array of all elements as string
+     * that should be added to the head of the page.
+     * @private
+     */
+    async getHeadElements() {
+        return Promise.all(this._headElements.map(element => {
+            if (typeof element === 'function') {
+                return this._zubyContext?.renderToString?.(element()) || '';
+            }
+            return element;
+        }));
+    }
 }

package/plugins/contextPlugin/index.js

@@ -25,7 +25,7 @@ export default function index() {
     };
 }
 export async function generateCompileTimeContextCode(ssr) {
-    const { site, i18n } = await getZubyInternalConfig();
+    const { site, i18n, buildId, props, serverProps, headElements } = await getZubyInternalConfig();
     const { version } = await getZubyPackageConfig();
     return `globalThis.ZubyRawContext = {
         ...(globalThis.ZubyRawContext || {}),
@@ -34,6 +34,10 @@ export async function generateCompileTimeContextCode(ssr) {
         site: '${site || ''}',
         generator: 'Zuby.js ${version}',
         version: '${version}',
+        buildId: '${buildId}',
+        props: ${JSON.stringify(props)},
+        serverProps: ${JSON.stringify(ssr ? serverProps : {})},
+        headElements: ${JSON.stringify(ssr ? headElements : [])},
         i18n: ${JSON.stringify(i18n)},
     };`;
 }

package/preload/index.js

@@ -1,4 +1,5 @@
 import { getContext } from '../context/index.js';
+import { PREALOD_MANIFEST } from '../constants.js';
 /**
  * The set of links that were already preloaded.
  */
@@ -59,7 +60,7 @@ export function preloadPage(href, onHandle = () => { }) {
         return;
     }
     window.requestIdleCallback(async () => {
-        await loadPreloadManifest();
+        const preloadManifest = await getPreloadManifest();
         // Preload assets such as scripts and styles
         const preloadAssets = preloadManifest?.[page.filename] || [];
         preloadAssets.forEach(href => preload(href));
@@ -78,10 +79,16 @@ function addPreloadEntry({ href, as }) {
     preloadLink.rel = 'preload';
     document.head.appendChild(preloadLink);
 }
-async function loadPreloadManifest() {
-    if (preloadManifest)
-        return;
-    preloadManifest = {};
-    const res = await fetch('/preload-manifest.json');
-    preloadManifest = await res.json();
+/**
+ * Returns preload manifest the way
+ * that ensures it is loaded only once.
+ */
+async function getPreloadManifest() {
+    return (preloadManifest =
+        preloadManifest ||
+            (async () => {
+                const { buildId } = getContext();
+                const res = await fetch(`/${PREALOD_MANIFEST}?${buildId}`);
+                return res.json();
+            })());
 }

package/server/index.js

@@ -2088,6 +2088,18 @@ var ZubyContext = class {
   get i18n() {
     return this.rawContext.i18n;
   }
+  get buildId() {
+    return this.rawContext.buildId;
+  }
+  get props() {
+    return this.rawContext.props;
+  }
+  get serverProps() {
+    return this.rawContext.serverProps;
+  }
+  get headElements() {
+    return this.rawContext.headElements;
+  }
 };
 var getRawContext = () => {
   return globalThis.ZubyRawContext;
@@ -2110,9 +2122,11 @@ var ZubyPageContext = class {
     this._clientAddress = options?.clientAddress;
     this._statusCode = options?.statusCode || 200;
     this._props = options?.props || {};
+    this._serverProps = {};
     this._cache = 0;
     this._headers = options?.headers || new Headers();
     this._zubyContext = options?.zubyContext || getContext();
+    this._headElements = [...this._zubyContext.headElements || []];
   }
   /**
    * The current URL of the page.
@@ -2215,6 +2229,35 @@ var ZubyPageContext = class {
   set props(value) {
     this._props = value || {};
   }
+  /**
+   * The server props that are available only in server-side
+   * environment and are not shared with the client.
+   * You can use this property to pass data from handler to layout template.
+   * Hint: You should not read them in page because the hydration would fail,
+   * but you can write them on page and read them in layout.
+   * @example { my: 'secret-value' }
+   */
+  get serverProps() {
+    return {
+      ...this._zubyContext.serverProps || {},
+      ...this._serverProps || {}
+    };
+  }
+  set serverProps(value) {
+    this._serverProps = value || {};
+  }
+  /**
+   * The global props from the ZubyConfig
+   */
+  get globalProps() {
+    return this._zubyContext.props;
+  }
+  /**
+   * The global server props from the ZubyConfig
+   */
+  get globalServerProps() {
+    return this._zubyContext.serverProps;
+  }
   /**
    * The current status code that will be returned to the client.
    * This property has only effect in server-side.
@@ -2326,6 +2369,36 @@ var ZubyPageContext = class {
   get isPrerendering() {
     return this._request?.headers?.get("user-agent") === "zuby-prerender";
   }
+  /**
+   * The current build ID of the site.
+   * @example ecdf1a94cc9b4f4c
+   */
+  get buildId() {
+    return this._zubyContext.buildId;
+  }
+  /**
+   * Adds the given HTML string
+   * or Jsx Component to the head of the page
+   * when it's rendered on the server.
+   */
+  addToHead(element) {
+    this._headElements.push(element);
+  }
+  /**
+   * Returns array of all elements as string
+   * that should be added to the head of the page.
+   * @private
+   */
+  async getHeadElements() {
+    return Promise.all(
+      this._headElements.map((element) => {
+        if (typeof element === "function") {
+          return this._zubyContext?.renderToString?.(element()) || "";
+        }
+        return element;
+      })
+    );
+  }
 };
 
 // src/server/zubyRenderer.ts
@@ -8711,6 +8784,8 @@ var ZubyRenderer = class {
     jsImports.forEach((imp) => {
       html = html.replace(/(<\/head>)/, `<script type="module" src="${imp}" defer></script>$1`);
     });
+    const headElements = await pageContext.getHeadElements();
+    html = html.replace(/(<\/head>)/, headElements.join("") + "$1");
     return this.injectHeaders(
       new Response(html, {
         status: pageContext.statusCode || 200,

package/server/zubyRenderer.js

@@ -149,6 +149,8 @@ export default class ZubyRenderer {
         jsImports.forEach((imp) => {
             html = html.replace(/(<\/head>)/, `<script type="module" src="${imp}" defer></script>$1`);
         });
+        const headElements = await pageContext.getHeadElements();
+        html = html.replace(/(<\/head>)/, headElements.join('') + '$1');
         return this.injectHeaders(new Response(html, {
             status: pageContext.statusCode || 200,
             headers: {

package/templates/index.d.ts

@@ -1,4 +1,4 @@
-import { Template, TemplateType } from './types.js';
+import { Template, TemplateFile, TemplateType } from './types.js';
 /**
  * Returns the array of pages with static path.
  */
@@ -42,6 +42,11 @@ export declare function getDefaultTemplate(filename: string, templateType: Templ
  * If i18n config is defined, the pages will be localized and duplicated for each locale.
  */
 export declare function getTemplates(cache?: boolean): Promise<Template[]>;
+/**
+ * Collects all template files from the pages directory and the templateFiles config
+ * and returns them as an array of TemplateFile objects.
+ */
+export declare function getTemplateFiles(): Promise<TemplateFile[]>;
 /**
  * Calculates the weight of each template
  * and sorts them from the least dynamic path to the most dynamic.

package/templates/index.js

@@ -103,26 +103,12 @@ export function getDefaultTemplate(filename, templateType) {
 export async function getTemplates(cache = true) {
     if (cache && templatesCache)
         return templatesCache;
-    const { srcDir, i18n, templateExtensions } = await getZubyInternalConfig();
-    const pagesDir = normalizePath(join(srcDir, 'pages'));
-    const files = await glob(`${pagesDir}/**/*.{${templateExtensions.join(',')}}`);
+    const { i18n } = await getZubyInternalConfig();
     const locales = (i18n?.locales || []).filter(locale => locale !== i18n?.defaultLocale);
-    const templates = files
-        .map(filename => {
-        // Normalize the path and slashes to unix style (needed for windows)
-        filename = normalizePath(filename);
+    const templateFiles = await getTemplateFiles();
+    const templates = templateFiles
+        .map(({ path, filename, templateType }) => {
         const fileNameWithoutExtension = basename(filename).replace(/\.(.+)$/, '');
-        const templateType = getTemplateType(filename);
-        // Remove the pagesDir prefix from the filename
-        // and transform it to a valid wouter path
-        let path = toPath(filename.replace(pagesDir, ''));
-        // Create matching path for base templates
-        if (Object.values(BASE_TEMPLATES).includes(templateType)) {
-            path = `${path}/:path*`.replace(/\/+/g, '/');
-        }
-        // Calculate the relative path from
-        // the ZubyRouter component file to the page file
-        filename = normalizePath(resolve(filename));
         return {
             filename,
             path,
@@ -148,6 +134,40 @@ export async function getTemplates(cache = true) {
     }));
     return (templatesCache = sortTemplates(templates));
 }
+/**
+ * Collects all template files from the pages directory and the templateFiles config
+ * and returns them as an array of TemplateFile objects.
+ */
+export async function getTemplateFiles() {
+    const { srcDir, templateExtensions, templateFiles } = await getZubyInternalConfig();
+    const pagesDir = normalizePath(join(srcDir, 'pages'));
+    const files = await glob(`${pagesDir}/**/*.{${templateExtensions.join(',')}}`);
+    const configTemplateFiles = templateFiles.map(({ templateType, filename, path }) => {
+        return {
+            filename: normalizePath(resolve(filename)),
+            path: toPath(path),
+            templateType,
+        };
+    });
+    const folderTemplateFiles = files.map(filename => {
+        // Normalize the path and slashes to unix style (needed for windows)
+        filename = normalizePath(filename);
+        const templateType = getTemplateType(filename);
+        // Remove the pagesDir prefix from the filename
+        // and transform it to a valid wouter path
+        let path = toPath(filename.replace(pagesDir, ''));
+        // Create matching path for base templates
+        if (Object.values(BASE_TEMPLATES).includes(templateType)) {
+            path = `${path}/:path*`.replace(/\/+/g, '/');
+        }
+        return {
+            filename: normalizePath(resolve(filename)),
+            path,
+            templateType,
+        };
+    });
+    return [...configTemplateFiles, ...folderTemplateFiles];
+}
 /**
  * Calculates the weight of each template
  * and sorts them from the least dynamic path to the most dynamic.

package/templates/types.d.ts

@@ -47,3 +47,8 @@ export declare const SYNC_TEMPLATES: {
     loader: string;
 };
 export type TemplateType = (typeof TEMPLATES)[keyof typeof TEMPLATES];
+export interface TemplateFile {
+    path: string;
+    filename: string;
+    templateType: TemplateType;
+}

package/templates/types.js

@@ -1,4 +1,3 @@
-// Pages
 export const PATH_TYPES = {
     static: 'static',
     dynamic: 'dynamic',

package/types.d.ts

@@ -2,7 +2,7 @@
 import type { UserConfig as ViteUserConfig, InlineConfig as ViteInlineConfig, PluginOption as VitePluginOption, Plugin as VitePlugin } from 'vite';
 import { ZubyLogger } from './logger/types.js';
 import ReadableStream = NodeJS.ReadableStream;
-import { PathParamsType, Template } from './templates/types.js';
+import { PathParamsType, Template, TemplateFile } from './templates/types.js';
 import ZubyDevServer from './server/zubyDevServer.js';
 export interface ZubyConfig {
     /**
@@ -122,6 +122,39 @@ export interface ZubyConfig {
      * @private
      */
     configFilePath?: string;
+    /**
+     * If you're building in multiple environments,
+     * you can use this option to generate consistent build IDs.
+     */
+    generateBuildId?: () => string | Promise<string>;
+    /**
+     * Template files that are used to
+     * create the templates during the build process.
+     * @private
+     */
+    templateFiles?: TemplateFile[];
+    /**
+     * The global props for the site
+     * that will be passed to all pages, handlers etc...
+     * on both client and server side.
+     * They can be retrieved using PageContext.globalProps method.
+     * @default {}
+     */
+    props?: Record<string, any>;
+    /**
+     * The global server props for the site
+     * that will be passed to all pages, handlers etc...
+     * only on server side.
+     * They can be retrieved using PageContext.globalServerProps method.
+     * @default {}
+     */
+    serverProps?: Record<string, any>;
+    /**
+     * Additional HTML elements
+     * that will be injected into the head of the page.
+     * @default []
+     */
+    headElements?: string[];
 }
 export interface ZubyInternalConfig extends Required<ZubyConfig> {
     /**
@@ -136,6 +169,10 @@ export interface ZubyInternalConfig extends Required<ZubyConfig> {
      * @default []
      */
     plugins: ZubyPlugin[];
+    /**
+     * The current build ID
+     */
+    buildId: string;
 }
 export interface BaseCommandOptions {
     /**
@@ -304,6 +341,15 @@ export interface ZubyPlugin extends VitePlugin {
 export interface ZubyConfigSetupHookParams {
     config: ZubyConfig;
     command: 'dev' | 'build';
+    addEntryTemplate: (entryFile: string) => void;
+    addAppTemplate: (appFile: string, path?: string) => void;
+    addLayoutTemplate: (layoutFile: string, path?: string) => void;
+    addInnerLayoutTemplate: (innerLayoutFile: string, path?: string) => void;
+    addErrorTemplate: (errorFile: string, path?: string) => void;
+    addLoaderTemplate: (loaderFile: string, path?: string) => void;
+    addPage: (pageFile: string, path?: string) => void;
+    addHandler: (handlerFile: string, path?: string) => void;
+    addToHead: (element: string) => void;
 }
 export interface ZubyConfigDoneHookParams extends ZubyConfigSetupHookParams {
     config: ZubyInternalConfig;