{"id":21373192,"url":"https://github.com/nasriyasoftware/hypercloud","last_synced_at":"2026-02-27T11:10:12.395Z","repository":{"id":243363751,"uuid":"764064008","full_name":"nasriyasoftware/HyperCloud","owner":"nasriyasoftware","description":"Nasriya HyperCloud is a lightweight Node.js HTTP2 server framework.","archived":false,"fork":false,"pushed_at":"2025-11-06T16:21:24.000Z","size":722,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-06T16:25:20.831Z","etag":null,"topics":["cloudflare","cron","cronjob","cronjob-scheduler","dns","duckdns","http","http-server","http2","http2-server","https","https-server"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@nasriya/hypercloud","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nasriyasoftware.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-02-27T12:18:22.000Z","updated_at":"2025-10-02T06:17:47.000Z","dependencies_parsed_at":"2024-06-08T11:07:11.831Z","dependency_job_id":"a0872403-8b03-4b91-8ec4-94c9a25c58ce","html_url":"https://github.com/nasriyasoftware/HyperCloud","commit_stats":null,"previous_names":["nasriyasoftware/hypercloud"],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/nasriyasoftware/HyperCloud","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nasriyasoftware%2FHyperCloud","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nasriyasoftware%2FHyperCloud/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nasriyasoftware%2FHyperCloud/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nasriyasoftware%2FHyperCloud/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nasriyasoftware","download_url":"https://codeload.github.com/nasriyasoftware/HyperCloud/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nasriyasoftware%2FHyperCloud/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29892065,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-27T09:48:51.284Z","status":"ssl_error","status_checked_at":"2026-02-27T09:48:43.992Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloudflare","cron","cronjob","cronjob-scheduler","dns","duckdns","http","http-server","http2","http2-server","https","https-server"],"created_at":"2024-11-22T08:26:18.545Z","updated_at":"2026-02-27T11:10:12.367Z","avatar_url":"https://github.com/nasriyasoftware.png","language":"TypeScript","readme":"\u003ca href=\"https://package.nasriya.net/hypercloud\"\u003e\u003cimg src=\"https://static.wixstatic.com/shapes/72ffe6_f9d8d6b66e7c495598327e3ab4712c81.svg\" width=\"350px\" alt=\"Nasriya HyperCloud\"\u003e\u003c/a\u003e\n\n[![NPM License](https://img.shields.io/npm/l/%40nasriya%2Fhypercloud?color=lightgreen)](https://github.com/nasriyasoftware/HyperCloud?tab=License-1-ov-file) ![NPM Version](https://img.shields.io/npm/v/%40nasriya%2Fhypercloud) ![NPM Unpacked Size](https://img.shields.io/npm/unpacked-size/%40nasriya%2Fhypercloud) ![Last Commit](https://img.shields.io/github/last-commit/nasriyasoftware/HyperCloud.svg) [![Status](https://img.shields.io/badge/Status-Stable-lightgreen.svg)](link-to-your-status-page)\n\n\n##### Visit us at [www.nasriya.net](https://nasriya.net).\n\nNasriya HyperCloud is a lightweight Node.js HTTP2 framework.\n\nMade with ❤️ in **Palestine** 🇵🇸\n___\n## Overview\nHyperCloud is a robust server-side rendering (SSR) framework designed to build and define components and pages efficiently. The framework supports multilingual pages, handles component rendering, and manages assets seamlessly, ensuring a smooth development experience.\n\n\u003e [!IMPORTANT]\n\u003e \n\u003e 🌟 **Support Our Open-Source Development!** 🌟\n\u003e We need your support to keep our projects going! If you find our work valuable, please consider contributing. Your support helps us continue to develop and maintain these tools.\n\u003e \n\u003e **[Click here to support us!](https://fund.nasriya.net/)**\n\u003e \n\u003e Every contribution, big or small, makes a difference. Thank you for your generosity and support!\n___\n\n## Key Features\n- **[HTTP2](https://en.wikipedia.org/wiki/HTTP/2)** Framework.\n- **Component-Based Architecture:** Define and build reusable components and pages with ease.\n- **[Multilingual Support](#languages):** Define localized content for your pages using locals for each language. The framework ensures the correct content is rendered based on the user's language preference.\n- **Automatic Asset Management:** Automatically include stylesheets, scripts, and meta tags from components and global settings in the rendered pages.\n- **Preserved Asset Order:** Maintain the order of assets as defined, ensuring predictable rendering.\n- **Secure Server** with **FREE** [SSL certificates](./examples/proxies.md#generate-ssl-certificates).\n- Built-In \u0026 Custom [Error Pages](#error-handling--pages).\n- Built-in (In-Memory) [Rate Limiter](#rate-limiter).\n- Built-in [Helmet](#helmet-protection) Protection.\n\n### Additional Features\n- **[File Upload Handling](#file-upload-handling)**: Manage file uploads with built-in support for configuring file size limits, handling different file types, and automatically cleaning up temporary files.\n- Works well with proxies.\n___\n## Status [![Status](https://img.shields.io/badge/Status-Stable-green.svg)](link-to-your-status-page)\nIf you encounter an issue or a bug, please [open an issue](https://github.com/nasriyasoftware/HyperCloud/issues).\n___\n## Quick Start Guide\nQuickly run a `HyperCloud` server in **5** easy steps.\n\n#### 1. Installation\n```shell\nnpm i @nasriya/hypercloud\n```\n\n#### 2. Importing\nImporting in **ESM** modules\n```js\nimport hypercloud from '@nasriya/hypercloud';\n```\n\nImporting in **CommonJS** modules\n```js\nconst hypercloud = require('@nasriya/hypercloud').default;\n```\n\n#### 3. Creating \u0026 Initializing a server\n```js\n// Create a new server\nconst server = hypercloud.Server();\n\n// (Optional) Set the main server so you can use it anywhere\nhypercloud.server = server;\n```\n**::** [Advanced Server Configurations](./examples/server-configurations.md) **::**\n\n#### 4. Defining routes\nFor now, you only have a server that serves a `404` page on any path, so let's define more routes now using the server's `Router`.\n\n```js\nconst router = server.Router();\n\n// Define a route for the homepage\nrouter.use('/', (request, response, next) =\u003e {\n    response.status(200).send({ data: '\u003ch1\u003eHello, WOrld!\u003c/h1\u003e' })\n})\n```\n\n**::** [Advanced Router Implementations](./examples/router-implementations.md) **::**\n\n\n#### 5. Start listening\nTo start listening for requests, simply call the `listen` method on the server.\n\n```js\nserver.listen();                  // Prints ⇨ HyperCloud Server is listening on port #80\n// OR\nserver.listen({ port: 5000 });    // Prints ⇨ HyperCloud Server is listening on port #5000\n```\n**::** [Advanced Listening Implementations](./examples/listening-configs.md) **::**\n\nCongratulations! Your server is now ready to handle requests.\n\n___\n## Features\nHyperCloud has more features and advanced configurations.\n\n#### Enable Debugging\nYou can enable debugging to get more details about operations and errors.\n```js\nhypercloud.verbose = true;\n```\n\n#### Rate Limiter\nProtect your websites against abusive usage by setting limits on how much users can access your site or consume your APIs. The rate limiter can help you prevent small [DDoS attacks](https://www.cloudflare.com/learning/ddos/what-is-a-ddos-attack/), but it's not meant for that purpose. We recommend using [Cloudflare](https://www.cloudflare.com/) to protect your resources from DDoS attacks.\n\nLearn how to setup a **Rate Limiter** [here](./examples/rate-limiter.md).\n\n#### Helmet Protection\nIn today's digital landscape, security is paramount. HyperCloud's built-in Helmet protection is designed to provide robust security measures, safeguarding your applications from a myriad of common web vulnerabilities. By integrating Helmet, HyperCloud ensures that your applications are shielded against threats such as cross-site scripting (XSS), clickjacking, and other malicious attacks. This advanced protection layer helps developers focus on building features and functionality, knowing that their applications are fortified with industry-leading security practices. With Helmet, HyperCloud takes a proactive approach to web security, offering peace of mind and enabling you to deliver secure, reliable applications to your users.\n\nTo enable **Helmet** protection:\n```js\nserver.helmet(); // This applies all the default configurations\n```\n\nLearn how to customize the **Helmet** [here](./examples/helmet.md).\n\n#### Proxy Servers\nIf your server is running behind a proxy server, you need to configure the `proxy` option of the server before initializing it.\n\nLearn how to setup your server behind a **Proxy Server** [here](./examples/proxies.md).\n\n#### Languages\nWe understand that some sites are multilingual. With **HyperCloud**, you can easily build multilingual sites.\n\n###### Supported Languages\nYou can set a list of languages that your server supports to properly handle *language-related* requests, like checking users' preferred language to serve them content in their language.\n\nHere's how to set a list of supported languages on your server:\n```js\nserver.languages.supported = ['en', 'ar', 'de'];\n```\n\n###### Default Language\nIf a user doesn't have a preferred language, the browser's language is selected then checked against the server's [supported languages](#supported-languages), if the browser's language isn't supported, the server's `default` language is used to render pages or serve other language-related content.\n\nTo set a default language:\n```js\nserver.languages.default = 'ar';\n```\n\n**Note:** The `default` language must be one of the [supported languages](#supported-languages) or an error will be thrown.\n\n#### HyperCloud Built-In User\nHyperCloud provides a built-in `HyperCloudUser` on each `request` and allows you to populate it using a [custom handler](./examples/request-user.md#user-handler), you can then access the `user` object from any route via the `request` object.\n\nThe built-in `user` object looks like this:\n```js\n// request.user\n{\n    id: string,\n    loggedIn: boolean,\n    role: 'Admin'|'Member'|'Visitor',\n    preferences: {\n        language: string,\n        locale: string,\n        currency: string,\n        colorScheme: 'Dark'|'Light'\n    }\n}\n```\nLearn how to populate the `request.user` object and work with it [here](./examples/request-user.md).\n\n#### Error Handling \u0026 Pages\n\n**HyperCloud** provides four built-in error pages out of the box, `401`, `403`, `404`, and `500`. You can render these pages from your code and customize them with your own text, or you can set custom handlers to run whenever you needed.\n\nTo render error pages, just call them from the `pages` module in the `response` object.\n\n```js\nrouter.use('*', (request, response, next) =\u003e {\n    // Render the 401 page.\n    response.pages.unauthorized();\n\n    // Render the 403 page.\n    response.pages.forbidden();\n\n    // Render the 404 page.\n    response.pages.notFound();\n\n    // Render the 500 page.\n    response.pages.serverError();\n})\n```\n\nLearn more about **Error Handling \u0026 Pages** [here](./examples/error-handling-and-pages.md).\n\n\n#### Requests Logging\nYou can add a logger to log incoming requests by setting a `logger` handler.\n\n```js\nserver.handlers.logger((request, response, next) =\u003e {\n    // Use the request to gather information and log them.\n    \n    next(); // make sure to call next\n})\n```\n\nYou can also use another logging packages like [Logify](https://www.npmjs.com/package/@nasriya/logify) to help you with logging.\n\n```js\nimport logify from '@nasriya/logify';\n\nserver.handlers.logger(logify.middlewares.hypercloud);\n```\n#### File Upload Handling\nThe framework includes a robust file upload handling module that supports various file types and sizes. It allows for flexible configuration of file size limits, dynamic directory management, and efficient memory usage through file streaming. This feature is designed to handle multipart form data, automatically manage temporary files, and integrate seamlessly with other server functionalities.\n\nHere's how:\n```ts\nrouter.post('/api/v1/uploads', async (request, response, next) =\u003e {\n    try {\n        // Process the form data and handle the files\n        await request.processFormData(response);\n\n        // Extract fields, files, and the cleanup function from the request body\n        const { fields, files, cleanup } = request.body as FormDataBody;\n\n        // Process the files and fields (e.g., store files, update database)\n        // ............................\n\n        // Clean up temporary files after processing\n        await cleanup();\n\n        // Return a response or proceed to the next middleware/handler\n        next();\n    } catch(error) {\n        response.status(500).json(error);\n    }    \n});\n```\nLearn more about **File Upload Handling** [here](./examples/uploads.md).\n\n#### Generating eTags\n[ETags](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) can significantly improve server performance. To generate `eTags` for your resources, use the following syntax:\n\n```js\nimport path from 'path';\n\nhypercloud.generateETags(path.resolve('./src/images'));\n```\n\nThe code will generate a unique `eTags.json` file in each sub-directory including the provided `root` directory.\n\nThe generated `eTags.json` file will be something like this:\n```json\n{\n    \"\u003cfilename.png\u003e\": \"\u003cfile_eTag\u003e\",\n    \"logo.svg\": \"the-hashed-content\"\n}\n```\n\n#### Server Side Rendering (SSR)\nYou can define multilingual-ready pages by specifying locals for each language. The content of the page changes based on the language.\n\n##### How it works\n\n1. Define your pages and components.\n2. Register the pages and components.\n   \n   ```js\n    // Register pages\n    server.rendering.pages.register('/path/to/your/pages/folder');\n\n    // Register components\n    server.rendering.components.register('/path/to/your/components/folder');\n   ```\n3. Render the pages\n   \n   ```js\n    router.get('/', (request, response, next) =\u003e {\n        response.render('home');\n    })\n   ```\n\nLearn how to **define components and pages** [here](./examples/server-side-rendering-ssr.md).\n___\n## Upcoming Features \u0026 Improvements\nNew features planned for the complete version:\n\n\u003cdetails\u003e\n\u003csummary\u003eSecurity Feature (Block connections by IP address or country)\u003c/summary\u003e\n\nAdd a feature to block connections from specific IP addresses or countries to enhance security.\n\n- **Implementation Strategy**:\n  - **User-Agent Parsing**: Use a library to parse the User-Agent string and extract platform details.\n  - **Integration**: Integrate this parsing logic into the request handling process.\n  - **Configuration**: Allow for enabling/disabling this feature based on user preference.\n\u003c/details\u003e\n\nIf you want to request a new feature feel free to reach out:\n- Email: developers@nasriya.net\n- LinkedIn: 🔗 [Ahmad Nasriya](https://www.linkedin.com/in/ahmadnasriya/)\n___\n## License\nPlease read the license from [here](https://github.com/nasriyasoftware/HyperCloud?tab=License-1-ov-file).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnasriyasoftware%2Fhypercloud","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnasriyasoftware%2Fhypercloud","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnasriyasoftware%2Fhypercloud/lists"}