@cocreate/server-side-render 1.14.1 → 1.14.3
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.
- package/.github/workflows/automated.yml +1 -1
- package/CHANGELOG.md +7 -0
- package/README.md +133 -44
- package/package.json +12 -10
- package/release.config.js +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,10 @@
|
|
|
1
|
+
## [1.14.2](https://github.com/CoCreate-app/CoCreate-server-side-render/compare/v1.14.1...v1.14.2) (2026-07-19)
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
### Bug Fixes
|
|
5
|
+
|
|
6
|
+
* set default branch to main ([6f9123d](https://github.com/CoCreate-app/CoCreate-server-side-render/commit/6f9123dbdeb63a87fa65954b18ef985dac02ba78))
|
|
7
|
+
|
|
1
8
|
## [1.14.1](https://github.com/CoCreate-app/CoCreate-server-side-render/compare/v1.14.0...v1.14.1) (2026-07-17)
|
|
2
9
|
|
|
3
10
|
|
package/README.md
CHANGED
|
@@ -1,81 +1,170 @@
|
|
|
1
1
|
# CoCreate-server-side-render
|
|
2
2
|
|
|
3
|
-
A
|
|
3
|
+
A high-performance, stateless, and functional server-side rendering (SSR) engine for JavaScript applications. It parses HTML markup structures dynamically, resolves nested sub-file templates or raw database document attributes recursively, prevents infinite circular loop paths, and dynamically handles contextual overrides for translations, theme variations, and metadata layout configurations.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
5
|
+
---
|
|
8
6
|
|
|
7
|
+
## Table of Contents
|
|
9
8
|
|
|
10
|
-
|
|
9
|
+
* [Features](#features)
|
|
10
|
+
* [Installation](#installation)
|
|
11
|
+
* [Usage](#usage)
|
|
12
|
+
* [How it Works](#how-it-works)
|
|
13
|
+
* [HTML Schema & Selectors](#html-schema--selectors)
|
|
14
|
+
* [Announcements](#announcements)
|
|
15
|
+
* [Roadmap](#roadmap)
|
|
16
|
+
* [How to Contribute](#how-to-contribute)
|
|
17
|
+
* [About](#about)
|
|
18
|
+
* [License](#license)
|
|
11
19
|
|
|
12
|
-
|
|
20
|
+
---
|
|
13
21
|
|
|
14
|
-
|
|
22
|
+
## Features
|
|
15
23
|
|
|
16
|
-
|
|
24
|
+
* **Stateless Recursive Engine:** Processes complex DOM layouts recursively via standard parameters, remaining entirely decoupled from active thread states.
|
|
25
|
+
* **Dual-Matrix Resolution:** Simultaneously matches, fetches, and hooks HTML target layouts from secondary files (`src`) and structured database rows (`array`/`object`) in a single pass.
|
|
26
|
+
* **Infinite Loop Protection:** Tracks active ingestion routes inside structural resolution loops, instantly throwing explicit error exceptions before cyclical references cause crashes.
|
|
27
|
+
* **Intelligent Metadata Harvesting:** Extracts deep `<head>`, `<title>`, canonical `<link>`, and targeting `<meta>` records from individual content components and patches them into the primary document frame.
|
|
28
|
+
* **On-the-Fly Localization:** Maps custom multi-regional translations to target components using structural element dictionaries, while generating explicit alternative international web connections (`hreflang`).
|
|
29
|
+
* **Global ID Tokenization:** Scans compiled output buffers post-render to tokenize all standard `ObjectId()` template markers with live database identifiers.
|
|
17
30
|
|
|
18
|
-
|
|
19
|
-
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## Installation
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
npm install @cocreate/server-side-render
|
|
20
37
|
```
|
|
21
38
|
|
|
22
|
-
|
|
23
|
-
|
|
39
|
+
> [!NOTE]
|
|
40
|
+
> All core underlying dependencies (including DOM parsing utilities like `node-html-parser`) are managed natively and installed automatically.
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## Usage
|
|
45
|
+
|
|
46
|
+
### JavaScript API
|
|
47
|
+
|
|
48
|
+
Inject your rendering context parameters directly into the exported stateless asynchronous `HTML` entry hook:
|
|
49
|
+
|
|
50
|
+
```javascript
|
|
51
|
+
import { HTML } from '@cocreate/server-side-render';
|
|
52
|
+
|
|
53
|
+
const templateContext = {
|
|
54
|
+
src: `
|
|
55
|
+
<html>
|
|
56
|
+
<head>
|
|
57
|
+
<title>Primary Viewport</title>
|
|
58
|
+
</head>
|
|
59
|
+
<body>
|
|
60
|
+
<!-- External File Component Placement -->
|
|
61
|
+
<div src="/components/navbar.html"></div>
|
|
62
|
+
|
|
63
|
+
<!-- Database-Driven Reactive Field Injection -->
|
|
64
|
+
<h1 array="posts" object="64b9a32e18f21bc56789abcd" key="title">Loading Title...</h1>
|
|
65
|
+
</body>
|
|
66
|
+
</html>
|
|
67
|
+
`,
|
|
68
|
+
pathname: "/pages/dashboard.html",
|
|
69
|
+
organization_id: "current-organization-id-string"
|
|
70
|
+
};
|
|
71
|
+
|
|
72
|
+
const fullHtmlResponse = await HTML({
|
|
73
|
+
file: templateContext,
|
|
74
|
+
organization: { languages: ['en', 'es', 'de'] },
|
|
75
|
+
urlObject: new URL('https://mydomain.com/pages/dashboard.html'),
|
|
76
|
+
lang: 'en',
|
|
77
|
+
theme: 'dark',
|
|
78
|
+
crud: yourCrudDatabaseInstance // Handles internal document requests
|
|
79
|
+
});
|
|
80
|
+
|
|
81
|
+
console.log(fullHtmlResponse);
|
|
24
82
|
```
|
|
25
83
|
|
|
26
|
-
|
|
84
|
+
---
|
|
27
85
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
86
|
+
## How it Works
|
|
87
|
+
|
|
88
|
+
1. **DOM Structuring:** Converts raw template string streams into a lightweight traversable server-side virtual DOM structure using ultra-fast parser adapters.
|
|
89
|
+
2. **Target Scoping:** Identifies structural elements requiring injection by parsing the document body against the layout rule match set: `[array], [src]:not(...)`.
|
|
90
|
+
3. **File Dependency Splicing:** Prioritizes structural layouts matching active path variables (`src`) by looking up data records via an optional custom `resolveFile` handler or matching records via the active `crud` data controller.
|
|
91
|
+
4. **Data Attribute Evaluation:** Evaluates active object definitions (`array`, `object`, `key`), retrieves data entries through cached communication tunnels, and loads data contents straight into target content layouts.
|
|
92
|
+
5. **Head Compilation:** Extracts individual layout variables discovered inside nested sub-views, and compares properties against parent parameters to replace or append structural SEO elements like tags, styles, and descriptions.
|
|
93
|
+
6. **Post-Processing Transformations:** Sets localization properties, establishes page theme hooks (`data-bs-theme`, `color-scheme`), and normalizes text markers matching `ObjectId()` with fresh production parameters.
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## HTML Schema & Selectors
|
|
31
98
|
|
|
32
|
-
|
|
99
|
+
The module monitors specific markup conditions to differentiate between standard layout fragments and active component models.
|
|
33
100
|
|
|
34
|
-
|
|
35
|
-
|
|
101
|
+
### Target Engine Rules
|
|
102
|
+
|
|
103
|
+
The template processor continuously evaluates elements that match the following selector footprint:
|
|
104
|
+
|
|
105
|
+
```css
|
|
106
|
+
[array], [src]:not(script, img, iframe, audio, video, source, track, input, embed, frame)
|
|
36
107
|
```
|
|
37
108
|
|
|
38
|
-
|
|
109
|
+
### Skipped & Ignored Elements
|
|
110
|
+
|
|
111
|
+
To preserve natural browser actions and prevent unintended payload generation, certain element layouts are isolated from data or stream processing:
|
|
112
|
+
|
|
113
|
+
| Constraint Group | Targets Blocked / Skipped |
|
|
114
|
+
| --- | --- |
|
|
115
|
+
| **Data Skip (`IGNORE_ELEMENTS`)** | `FORM`, `INPUT`, `TEXTAREA`, `SELECT`, `LINK`, `IFRAME`, `COCREATE-SELECT` |
|
|
116
|
+
| **Source Skip (`SKIP_SRC_ELEMENTS`)** | `SCRIPT`, `IMG`, `IFRAME`, `AUDIO`, `VIDEO`, `SOURCE`, `TRACK`, `INPUT`, `EMBED`, `FRAME` |
|
|
117
|
+
| **Contextual Parent Guards** | Any element placed inside `.template`, `[template]`, `template`, `[render]`, `[render-query]`, `[component]`, `[plugin]`, or `[actions]` containers. |
|
|
118
|
+
|
|
119
|
+
### Attribute Configurations
|
|
120
|
+
|
|
121
|
+
| Attribute Key | Expected Value | Output Result Behavior |
|
|
122
|
+
| --- | --- | --- |
|
|
123
|
+
| `src` | `String` (File URL Path) | Triggers nested HTML template fragment fetch operations and tree inclusion. |
|
|
124
|
+
| `array` | `String` (Collection ID) | Specifies the target database collection name for document resolution. |
|
|
125
|
+
| `object` | `String` (Hex/ID) | Explicitly targets an individual row ID inside the collection map. |
|
|
126
|
+
| `key` | `String` (Object Path) | Selects a specific database attribute key value to inject into the element's content. |
|
|
127
|
+
| `filter` | `JSON String` | Passes explicit lookup query metrics directly into the operational database read pass. |
|
|
128
|
+
| `value-type` | `"outerHTML"` | Instructs the parser to completely drop the outer wrapper node when replacing contents. |
|
|
129
|
+
| `render-error` | *Presence Flag* | Forces the view to render markup contents even if target status headers return error codes (≥ 400). |
|
|
39
130
|
|
|
40
|
-
|
|
41
|
-
- [Announcements](#announcements)
|
|
42
|
-
- [Roadmap](#roadmap)
|
|
43
|
-
- [How to Contribute](#how-to-contribute)
|
|
44
|
-
- [About](#about)
|
|
45
|
-
- [License](#license)
|
|
131
|
+
---
|
|
46
132
|
|
|
47
|
-
|
|
133
|
+
## Announcements
|
|
48
134
|
|
|
49
|
-
|
|
135
|
+
All updates, architecture changes, and performance optimization details are documented in our `CHANGELOG.md` and the [CoCreate Server Side Render GitHub Releases](https://github.com/CoCreate-app/CoCreate-server-side-render/releases) page.
|
|
50
136
|
|
|
51
|
-
|
|
137
|
+
---
|
|
52
138
|
|
|
53
|
-
|
|
139
|
+
## Roadmap
|
|
54
140
|
|
|
55
|
-
|
|
141
|
+
If you are interested in the future direction of this project, please take a look at our open issues and pull requests on the repository. We welcome community input on scaling caching strategies and extending streaming chunk processors.
|
|
56
142
|
|
|
57
|
-
|
|
143
|
+
---
|
|
58
144
|
|
|
59
|
-
|
|
145
|
+
## How to Contribute
|
|
60
146
|
|
|
61
|
-
|
|
147
|
+
We encourage contribution to our libraries (you might even score some nifty swag), please see our [CONTRIBUTING.md](https://github.com/CoCreate-app/CoCreate-server-side-render/blob/master/CONTRIBUTING.md) guide for details. If you encounter any bugs or wish to make feature requests, please submit an issue on our [GitHub Issues](https://github.com/CoCreate-app/CoCreate-server-side-render/issues) tracker. We want this library to be community-driven, and CoCreate led. We need your help to realize this goal.
|
|
62
148
|
|
|
63
|
-
|
|
149
|
+
For broader system configurations and API guides, please visit our [CoCreate Server Side Render Documentation](https://cocreatejs.com/docs/server-side-render).
|
|
64
150
|
|
|
65
|
-
|
|
151
|
+
---
|
|
66
152
|
|
|
67
|
-
|
|
153
|
+
## About
|
|
68
154
|
|
|
69
|
-
|
|
155
|
+
`@cocreate/server-side-render` is designed, built, and supported by the CoCreate Developer Experience Team.
|
|
70
156
|
|
|
71
|
-
|
|
157
|
+
> [!NOTE]
|
|
158
|
+
> Please contact the Developer Experience Team via [GitHub Discussions](https://github.com/CoCreate-app/CoCreate-server-side-render/discussions) or join our Discord channel for any architecture or deployment queries.
|
|
72
159
|
|
|
73
|
-
|
|
160
|
+
`@cocreate/server-side-render` is maintained and funded by CoCreate. The names and logos for CoCreate are trademarks of CoCreate, LLC.
|
|
74
161
|
|
|
75
|
-
|
|
162
|
+
---
|
|
76
163
|
|
|
77
|
-
|
|
164
|
+
## License
|
|
78
165
|
|
|
79
|
-
|
|
166
|
+
This software is dual-licensed under the GNU Affero General Public License version 3 (AGPLv3) and a commercial license.
|
|
80
167
|
|
|
81
|
-
|
|
168
|
+
* **Open Source Use:** For open-source projects and non-commercial use, this software is available under the AGPLv3. For the full license text, see the LICENSE file.
|
|
169
|
+
* **Commercial Use:** For-profit companies and individuals intending to use this software for commercial purposes must obtain a commercial license. The commercial license is available when you sign up for an API key on our website.
|
|
170
|
+
```
|
package/package.json
CHANGED
|
@@ -1,16 +1,18 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cocreate/server-side-render",
|
|
3
|
-
"version": "1.14.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "1.14.3",
|
|
4
|
+
"description": "High-performance, stateless server-side rendering (SSR) engine with recursive HTML template parsing, multi-source data resolution, and automated circular dependency protection.",
|
|
5
5
|
"keywords": [
|
|
6
|
-
"server-side-
|
|
7
|
-
"
|
|
8
|
-
"
|
|
9
|
-
"
|
|
10
|
-
"
|
|
11
|
-
"
|
|
12
|
-
"
|
|
13
|
-
"
|
|
6
|
+
"server-side-rendering",
|
|
7
|
+
"ssr-engine",
|
|
8
|
+
"html-parsing",
|
|
9
|
+
"recursive-rendering",
|
|
10
|
+
"stateless-utility",
|
|
11
|
+
"template-interpolation",
|
|
12
|
+
"metadata-merging",
|
|
13
|
+
"circular-dependency-prevention",
|
|
14
|
+
"i18n-ssr",
|
|
15
|
+
"cocreate-module"
|
|
14
16
|
],
|
|
15
17
|
"publishConfig": {
|
|
16
18
|
"access": "public"
|