Merge pull request #778 from smapiot/develop

Release 1.9.0

Author: FlorianRappl

.github/workflows/size.yml

@@ -16,6 +16,7 @@ jobs:
         with:
           node-version: "20.12.2"
       - run: yarn install
+      - run: yarn install --ignore-scripts
       - name: Report changes
         run: node ./tools/size-reporter.mjs
         env:

CHANGELOG.md

@@ -1,5 +1,23 @@
 # Piral Changelog
 
+## 1.9.0 (tbd)
+
+- Fixed platform providers for `piral-ng` with Angular 20 in non-standalone form (#764)
+- Fixed debug mode deserialization in case of modifications from other security contexts (#775)
+- Removed `container` property from the `unhandled-error` event arguments (#777)
+- Improved dialog order in `piral-modals` (#773) by @pranav-hsg
+- Improved output when installation of packages fails (#759)
+- Improved error message when template resolution fails (#763)
+- Updated some dependencies such as `axios` (#765)
+- Updated `dets` to latest release
+- Updated `piral-cli-webpack5` to never output empty `main.css` files in pilets
+- Updated `piral-oidc` to use up-to-date `oidc-client-ts` instead of discontinued `oidc-client` library (#769)
+- Added support for Angular 20 in `piral-ng`
+- Added warning in `piral-cli` when shared dependencies are wrongly declared (#768)
+- Added support for Promise-based Webpack configuration files in `piral-cli-webpack5` (#774) by @grant-progress
+- Added `remoteTypesSource` to *piral.json* for specifying an URL for extra declarations
+- Added `remoteTypesTarget` to *pilet.json* for storing obtained extra declarations locally
+
 ## 1.8.5 (April 15, 2025)
 
 - Fixed generation of declarations during `pilet build` in the `piral-cli`

docs/concepts/T03-templates.md

@@ -33,7 +33,7 @@ Registry selection:
 
 A custom template is just an npm package that fulfills the following requirements:
 
-1. Expose a CommonJS module (`main` in the *package.json*)
+1. Expose a **CommonJS module** (`main` in the *package.json*)
 2. Have a `default` export being a function specified below
 3. Have `template` and either `pilet` (for pilets) or `piral` (for Piral instances) as keyword
 
@@ -84,3 +84,50 @@ interface ExecutionDetails {
 ```
 
 This way, the template packages are essentially factories to create virtual files which are then written out by the `piral-cli`.
+
+The easiest way to have a convenient codebase and adhere to the CommonJS output is to use a bundler such as `esbuild`. For instance, the following code (stored in *src/index.js*) would not work directly:
+
+```js
+import { createPiletTemplateFactory } from '@smapiot/template-utils';
+
+const root = resolve(__dirname, '..');
+
+export default createPiletTemplateFactory(root, () => [
+  {
+    languages: ['js', 'ts'],
+    name: 'foo.txt',
+    target: '<src>/foo.txt',
+  },
+]);
+```
+
+Here, we use an ES module. To bring that conveniently and efficiently into a CommonJS module you can use the following *package.json*:
+
+```json
+{
+  "name": "@custom/template",
+  "version": "1.0.0",
+  "keywords": ["template", "pilet"],
+  "engines": {
+    "node": ">=16.0",
+    "piral": "1.x"
+  },
+  "templateOptions": {},
+  "author": "Your name",
+  "license": "MIT",
+  "main": "lib/index.js",
+  "files": [
+    "lib",
+    "src",
+    "templates"
+  ],
+  "scripts": {
+    "build": "esbuild src/index.js --bundle --outfile=./lib/index.js --platform=node"
+  },
+  "devDependencies": {
+    "@smapiot/template-utils": "^1.0.13"
+  }
+}
+```
+
+Importantly, you can run `npm run build` to convert the original ES module codebase to a single file stored in *lib/index.js*. This way, you do not need to declare runtime dependencies such as `@smapiot/template-utils` (they can remain a development-only dependency) and you obtain a legit CommonJS module.

docs/static/schemas/pilet-v0.json

@@ -28,6 +28,19 @@
       ],
       "description": "The default behavior for implicitly defined versions of shared dependencies."
     },
+    "remoteTypesTarget": {
+      "description": "The absolute or relative location of the file that is written with the remote types, if any. Default is './src/remote.d.ts'.",
+      "oneOf": [
+        {
+          "type": "boolean",
+          "description": "A truthy value indicates that the default value should be used. Otherwise, nothing is written."
+        },
+        {
+          "type": "string",
+          "description": "The absolute or relative location of the file with the remote types."
+        }
+      ]
+    },
     "piralInstances": {
       "type": "object",
       "description": "The app shells to be used for debugging the pilet. Each key defines the name of a Piral instance to be selectable.",
@@ -58,4 +71,4 @@
       }
     }
   }
-}
+}

docs/static/schemas/piral-v0.json

@@ -92,6 +92,10 @@
       ],
       "description": "Defines how the styles for the web components are transported. 'inline' puts them on the web components when rendering, 'sheet' includes a stylesheet when bundling, 'none' requires you to include them somewhere. By default, 'inline' is used."
     },
+    "remoteTypesSource": {
+      "type": "string",
+      "description": "The URL of the generated d.ts combining extra type information from all pilets."
+    },
     "shared": {
       "type": "array",
       "items": {

docs/tutorials/11-server-side-rendering.md

@@ -168,53 +168,6 @@ The diagram below shows this sequence.
 
 **Remark**: The replacement for the embedded data needs to be placed *before* the root module (in the example above `<script src="index.tsx"></script>`) is referenced.
 
-The embedded data is either the data from the pilet feed (this section) or the data from the feed including the pilets (see next section).
-
-## Embedding the Pilets
-
-Embedding the pilet feed may already be enough to provide improved startup performance. Nevertheless, especially for "cold starts", i.e., where no pilets have yet been seen or loaded, it can make sense to also deliver the pilets with the initial response.
-
-Following the approach described beforehand, we can extend the `sendIndex` function to also include the pilets.
-
-The only thing to add is the `getPilet` function in the provided options. This way, we can tell the SSR utility how to retrieve a pilet from its link.
-
-```ts
-import axios from 'axios';
-import { createApp } from '../common/app';
-
-const feedUrl = 'https://feed.piral.cloud/api/v1/pilet/sample';
-
-function readRemoteText(link: string) {
-  return axios.get(link).then(res => res.data);
-}
-
-async function readRemoteJson(link: string) {
-  const content = await readRemoteText(link);
-  return JSON.parse(content);
-}
-
-async function sendIndex(_: express.Request, res: express.Response) {
-  const app = createApp();
-  const content = await renderFromServer(app, {
-    getPilet(url) {
-      return readRemoteText(url);
-    },
-    async getPiletsMetadata() {
-      const res = await readRemoteJson(feedUrl);
-      return res.items;
-    },
-    fillTemplate(body, script) {
-      return indexHtml
-        .replace('<div id="app"></div>', `<div id="app">${body}</div>`)
-        .replace('<noscript id="data"></noscript>', script);
-    },
-  });
-  res.send(content);
-}
-```
-
-Generally, this approach gives us quite some flexibility. It allows us to use caching in addition to HTTP requests. It also allows us to embed a pilet feed directly on the server-side, potentially not requiring any feed seen outside.
-
 ## Conclusion
 
 SSR can be helpful to improve startup performance and user experience. The cost of optimizing the backend is, however, not negligible and should be considered, too. Providing the fastest response possible to pilet feed and general page requests could be already sufficient to ensure a great user experience.

docs/tutorials/15-share-dependencies.md

@@ -140,7 +140,7 @@ The rule of thumb for sharing the type declarations is: Everything exported top-
 
 ### Exported Modules
 
-To simplify the process illustrated in the previous two sections you can use a special key called `shared` in your *pilet.json*, e.g.:
+To simplify the process illustrated in the previous two sections you can use a special key called `shared` in your *piral.json*, e.g.:
 
 ```json
 {