marko 5.21.2 → 5.21.5

package/docs/rendering.md

@@ -1,11 +1,11 @@
 # Rendering
 
-To render a Marko view, you need to `require` it.
+To render a Marko view, you need to `import` it.
 
 _example.js_
 
 ```js
-var fancyButton = require("./components/fancy-button");
+import FancyButton from "./components/fancy-button.marko";
 ```
 
 > **Note:** If you are targeting node.js, you will need to enable the [require extension](./installing.md#require-marko-views) in order to require `.marko` files or you will need to precompile all of your templates using [Marko CLI](https://github.com/marko-js/cli). If you are targeting the browser, you will need to use a bundler like [`lasso`](./lasso.md), [`webpack`](./webpack.md) or [`rollup`](./rollup.md).
@@ -15,13 +15,13 @@ Once you have a view, you can pass input data and render it:
 _example.js_
 
 ```js
-var button = require("./components/fancy-button");
-var html = button.renderToString({ label: "Click me!" });
+import FancyButton from "./components/fancy-button.marko";
+const html = FancyButton.renderToString({ label: "Click me!" });
 
 console.log(html);
 ```
 
-The input data becomes available as `input` within a view, so if `fancy-button.marko` looked like this:
+The data passed to `renderToString` becomes available as `input` in the component, so if `fancy-button.marko` looked like this:
 
 _./components/fancy-button.marko_
 
@@ -51,8 +51,8 @@ Many of these methods return a [`RenderResult`](#renderresult) which is an objec
 Using `renderSync` forces the render to complete synchronously. If a tag attempts to run asynchronously, an error will be thrown.
 
 ```js
-var view = require("./view"); // Import `./view.marko`
-var result = view.renderSync({});
+import View from "./view.marko";
+var result = View.renderSync({});
 
 result.appendTo(document.body);
 ```
@@ -67,8 +67,8 @@ result.appendTo(document.body);
 The `render` method returns an async `out` which is used to generate HTML on the server or a virtual DOM in the browser. In either case, the async `out` has a `then` method that follows the Promises/A+ spec, so it can be used as if it were a Promise. This promise resolves to a [`RenderResult`](#renderresult).
 
 ```js
-var view = require("./view"); // Import `./view.marko`
-var resultPromise = view.render({});
+import View from "./view.marko";
+var resultPromise = View.render({});
 
 resultPromise.then(result => {
   result.appendTo(document.body);
@@ -85,9 +85,9 @@ resultPromise.then(result => {
 | return value   | `AsyncStream`/`AsyncVDOMBuilder` | the async `out` render target                  |
 
 ```js
-var view = require("./view"); // Import `./view.marko`
+import View from "./view.marko";
 
-view.render({}, (err, result) => {
+View.render({}, (err, result) => {
   result.appendTo(document.body);
 });
 ```
@@ -103,12 +103,12 @@ view.render({}, (err, result) => {
 The HTML output is written to the passed `stream`.
 
 ```js
-var http = require("http");
-var view = require("./view"); // Import `./view.marko`
+import http from "http";
+import View from "./view.marko";
 
 http.createServer((req, res) => {
   res.setHeader("content-type", "text/html");
-  view.render({}, res);
+  View.render({}, res);
 });
 ```
 
@@ -123,10 +123,10 @@ http.createServer((req, res) => {
 The `render` method also allows passing an existing async `out`. If you do this, `render` will not automatically end the async `out` (this allows rendering a view in the middle of another view). If the async `out` won't be ended by other means, you are responsible for ending it.
 
 ```js
-var view = require("./view"); // Import `./view.marko`
-var out = view.createOut();
+import View from "./view.marko";
+var out = View.createOut();
 
-view.render({}, out);
+View.render({}, out);
 
 out.on("finish", () => {
   console.log(out.getOutput());
@@ -145,8 +145,8 @@ out.end();
 Returns an HTML string and forces the render to complete synchronously. If a tag attempts to run asynchronously, an error will be thrown.
 
 ```js
-var view = require("./view"); // Import `./view.marko`
-var html = view.renderToString({});
+import View from "./view.marko";
+var html = View.renderToString({});
 
 document.body.innerHTML = html;
 ```
@@ -162,25 +162,27 @@ document.body.innerHTML = html;
 An HTML string is passed to the callback.
 
 ```js
-var view = require("./view"); // Import `./view.marko`
+import View from "./view.marko";
 
-view.renderToString({}, (err, html) => {
+View.renderToString({}, (err, html) => {
   document.body.innerHTML = html;
 });
 ```
 
 ### `stream(input)`
 
-The `stream` method returns a node.js style stream of the output HTML. This method is available on the server, but is not available by default in the browser. If you need to use streams in the browser, you may `require('marko/stream')` as part of your client-side bundle.
+The `stream` method returns a Node.js-style stream of the output HTML.
 
 ```js
-var fs = require("fs");
-var view = require("./view"); // Import `./view.marko`
-var writeStream = fs.createWriteStream("output.html");
+import fs from "fs";
+import View from "./view.marko";
+const writeStream = fs.createWriteStream("output.html");
 
-view.stream({}).pipe(writeStream);
+View.stream({}).pipe(writeStream);
 ```
 
+This method is available on the server, but not available by default in the browser. If you need to use streams in the browser, you may `import 'marko/stream'` as part of your client-side bundle.
+
 ## RenderResult
 
 ### `getComponent()`
@@ -207,35 +209,42 @@ view.stream({}).pipe(writeStream);
 
 ## Global data
 
-If you need to make data available globally to all views that are rendered as the result of a call to one of the above render methods, you can pass the data as a `$global` property on the input data object. This object will be removed from `input` and merged into the `out.global` property.
+If you need to make data available to all rendered views, use the `$global` property on the input data object. This property will be removed from `input` and merged into the `out.global` property.
+
+Global values persist across renders.
 
 ```js
-view.render({
+View.render({
   $global: {
     flags: ["mobile"]
   }
 });
 ```
 
-To prevent sensitive data to be accidentally shipped to the browser, by default **none of the keys** in `out.global` is going to be sent to the browser. If you want the data to be serialized and ship to the frontend you need to specify it in `serializedGlobals` inside the `$global` object and they persist across re-renderings.
-The values need to be serializable.
+> **Warning:** Use `$global` with caution; it is visible in any component.
+
+### Sending global data to browsers
+
+⚠️ To prevent accidentally exposing sensitive data, by default **no keys** in `out.global` are sent to browsers. To serialize data to the frontend, name the desired properties in `$global.serializedGlobals`.
+
+Values must be serializable by [the `warp10` module](https://www.npmjs.com/package/warp10).
 
 ```js
+import Page from "./index.marko";
+
 app.get("/", (req, res) => {
   const ua = req.get("User-Agent");
-  const isIos = !!ua.match(/iPad|iPhone/);
-  const isAndroid = !!ua.match(/Android/);
 
-  require("./index.marko").render(
+  Page.render(
     {
       $global: {
-        isIos, // isPad is serialized and available on the server and the browser in out.global.isPad
-        isAndroid, // isAndroid is serialized and available on the server and the browser in out.global.isAndroid
-        req, // req is going to be available only server side and will not be serialized because in not present in serializedGlobals below
+        isIos: /iPad|iPhone/.test(ua), // Serialized and available on the server and browser as `out.global.isIos`
+        isAndroid: /Android/.test(ua), // Serialized and available on the server and browser as `out.global.isAndroid`
+        req, // Only available server-side and not serialized, because it’s not in `serializedGlobals`
 
         serializedGlobals: {
-          isIos: true, // Tell marko to serialize isIos above
-          isAndroid: true // Tell marko to serialize isAndroid above
+          isIos: true, // Tell Marko to serialize `isIos`
+          isAndroid: true // Tell Marko to serialize `isAndroid`
         }
       }
     },
@@ -244,6 +253,4 @@ app.get("/", (req, res) => {
 });
 ```
 
-Use `$global` with judgement. It is global and visible in any component.
-
-Check [this PR](https://github.com/marko-js/marko/pull/672) for more details.
+For details, check [#672: “Serialize only input and state on top-level server-rendered UI components”](https://github.com/marko-js/marko/pull/672).

package/docs/troubleshooting-streaming.md

@@ -35,7 +35,7 @@ Content Delivery Networks (CDNs) consider efficient streaming one of their best
 
 - Some [Akamai features designed to mitigate slow backends can ironically slow down fast chunked responses](https://community.akamai.com/customers/s/question/0D50f00006n975d/enabling-chunked-transfer-encoding-responses). Try toggling off Adaptive Acceleration, Ion, mPulse, Prefetch, and/or similar performance features. Also check for the following in the configuration:
 
-  ```html
+  ```xml
   <network:http.buffer-response-v2>off</network:http.buffer-response-v2>
   ```
 
@@ -44,15 +44,15 @@ Content Delivery Networks (CDNs) consider efficient streaming one of their best
 For extreme cases where [Node streams very small HTML chunks with its built-in compression modules](https://github.com/marko-js/marko/pull/1641), you may need to tweak the compressor stream settings. Here’s an example with `createGzip` and its `Z_PARTIAL_FLUSH` flag:
 
 ```js
-const http = require("http");
-const zlib = require("zlib");
+import http from "http";
+import zlib from "zlib";
 
-const markoTemplate = require("./something.marko");
+import MarkoTemplate from "./something.marko";
 
 http
   .createServer(function (request, response) {
     response.writeHead(200, { "content-type": "text/html;charset=utf-8" });
-    const templateStream = markoTemplate.stream({});
+    const templateStream = MarkoTemplate.stream({});
     const gzipStream = zlib.createGzip({
       flush: zlib.constants.Z_PARTIAL_FLUSH
     });

package/docs/webpack.md

@@ -116,21 +116,22 @@ export default {
   },
 ```
 
-## Multiple client side compilers
+## Multiple client-side compilers
 
-Sometimes you need to have multiple compilers for your client side bundles. For example with [`i18n`](https://github.com/webpack/webpack/tree/master/examples/i18n) or [even shipping dynamic runtime bundles to the browser](https://github.com/eBay/arc/tree/master/packages/arc-webpack).
+Sometimes you need multiple compilers for your client-side bundles. For example, with [`i18n`](https://github.com/webpack/webpack/tree/master/examples/i18n) or [even shipping dynamic runtime bundles to the browser](https://github.com/eBay/arc/tree/master/packages/arc-webpack).
 
-The Marko webpack browser plugin can be passed to multiple webpack compilers. At runtime you can provide a `$global.buildName` when rendering which will cause assets from the webpack compiler with that name to be included in the page.
+The `@marko/webpack` plugin’s `.browser` property can be passed to multiple Webpack compilers. While rendering at runtime, you can provide a `$global.buildName` property to choose which assets from the Webpack compiler are included in the page.
 
-For example with the webpack i18n plugin you might have a config like the following:
+For example, with the Webpack internationalization plugin, you might have a config like the following:
 
 ```js
 import MarkoPlugin from "@marko/webpack/plugin";
 import I18nPlugin from "i18n-webpack-plugin";
+import germanTranslations from "./de.json";
 
 const languages = {
   en: null,
-  de: require("./de.json")
+  de: germanTranslations
 };
 
 const markoPlugin = new MarkoPlugin();
@@ -167,20 +168,19 @@ export default [
 ];
 ```
 
-With the above config you can render your top level Marko template server side with a `$global.buildName`, like so:
+With the above config, you can render your top-level Marko template server-side with a `$global.buildName` like so:
 
 ```javascript
 template.render({ $global: { buildName: "Browser-de" } });
 ```
 
-This will automatically send assets for the German language.
-Of course in this case you'll want to conditionally send the appropriate assets given a users locale. This can be some simply, like so:
+That will automatically send German assets. However, what you _probably_ want instead of always serving German is conditionally sending appropriate assets for a user’s locale. This can be done like so:
 
 ```javascript
 template.render({ $global: { buildName: `Browser-${req.language}` } });
 ```
 
-Note: If a bundle with the provided name does not exist an error will be thrown.
+**Note:** If a bundle with the provided `buildName` does not exist, an error is thrown.
 
 ## Multiple copies of Marko
 

package/package.json

@@ -1,11 +1,11 @@
 {
     "name": "marko",
-    "version": "5.21.2",
+    "version": "5.21.5",
     "license": "MIT",
     "description": "UI Components + streaming, async, high performance, HTML templating for Node.js and the browser.",
     "dependencies": {
-        "@marko/compiler": "^5.21.1",
-        "@marko/translator-default": "^5.21.1",
+        "@marko/compiler": "^5.22.2",
+        "@marko/translator-default": "^5.21.3",
         "app-module-path": "^2.2.0",
         "argly": "^1.2.0",
         "browser-refresh-client": "1.1.4",

package/src/core-tags/core/await/reorderer-renderer.js

@@ -1,5 +1,8 @@
 "use strict";
 
+var escapeDoubleQuotes =
+  require("../../../runtime/html/helpers/escape-quotes").___escapeDoubleQuotes;
+
 module.exports = function (input, out) {
   // We cannot call beginSync() when using renderSync(). In this case we will
   // ignore the await-reorderer tag.
@@ -54,13 +57,30 @@ module.exports = function (input, out) {
             global._afRuntime = true;
           }
 
-          asyncOut.write(
-            '<div id="af' +
-              awaitInfo.id +
-              '" style="display:none">' +
-              result.toString() +
-              "</div>"
-          );
+          if (global.cspNonce) {
+            asyncOut.write(
+              '<style nonce="' +
+                escapeDoubleQuotes(global.cspNonce) +
+                '">' +
+                "#af" +
+                awaitInfo.id +
+                "{display:none;}" +
+                "</style>" +
+                '<div id="af' +
+                awaitInfo.id +
+                '">' +
+                result.toString() +
+                "</div>"
+            );
+          } else {
+            asyncOut.write(
+              '<div id="af' +
+                awaitInfo.id +
+                '" style="display:none">' +
+                result.toString() +
+                "</div>"
+            );
+          }
 
           asyncOut.script(
             "$af(" +

package/docs/server-side-rendering.md

@@ -1,144 +0,0 @@
-# Server-side rendering
-
-Marko allows any Marko template/UI component to be rendered on the server or in the browser. A page can be rendered to a `Writable` stream such as an HTTP response stream as shown below:
-
-```js
-var template = require("./template"); // Import ./template.marko
-
-module.exports = function (req, res) {
-  res.setHeader("Content-Type", "text/html; charset=utf-8");
-  template.render({ name: "Frank" }, res);
-};
-```
-
-Marko can also provide you with a `Readable` stream.
-
-```js
-var template = require("./template"); // Import ./template.marko
-
-module.exports = function (req) {
-  // Return a Readable stream for someone to do something with:
-  return template.stream({ name: "Frank" });
-};
-```
-
-> **ProTip:** Marko also provides server-side framework integrations:
->
-> - [express](./express.md)
-> - [koa](./koa.md)
-> - [fastify](./fastify.md)
-
-## UI Bootstrapping
-
-When a page is rendered on the server, additional code is added to the output HTML to allow the UI to instantly boot in the browser. This additional code allows UI components rendered on the server to be mounted in the browser automatically. For each _top-level_ UI component, Marko will serialize the component's data (including `input` and `state` and any properties added to the UI component instance) so that each top-level UI component can be re-rendered and mounted when the page loads in the browser. Only a "partial" re-render is done for each top-level UI component. That is, when doing the partial re-render in the browser, the DOM is not updated and no virtual DOM is actually produced.
-
-Marko encodes required information into attributes of rendered HTML elements and it also generates `<script>` tags that will cause UI components to be mounted. The code inside the `<script>` simply registers UI components and when the Marko runtime finally loads, all of the registered UI components will then be mounted. This allows the Marko runtime to be loaded at anytime without causing JavaScript errors.
-
-## Bootstrapping Components
-
-When a server-rendered page loads in the browser it's possible for marko to automatically detect UI components rendered on the server and create and mount them with the correct `state` and `input` in the browser.
-
-### Bootstrapping: Lasso
-
-If you are using [Lasso.js](https://github.com/lasso-js/lasso) then the bootstrapping will happen automatically as long as the JavaScript bundles for your page are included via the `<lasso-body>` tag. A typical HTML page structure will be the following:
-
-_routes/index/template.marko_
-
-```marko
-<!DOCTYPE html>
-<html lang="en">
-    <head>
-        <meta charset="UTF-8">
-        <title>Marko + Lasso</title>
-
-        <!-- CSS includes -->
-        <lasso-head/>
-    </head>
-    <body>
-        <!-- Top-level UI component: -->
-        <app/>
-
-        <!-- JS includes -->
-        <lasso-body/>
-    </body>
-</html>
-```
-
-> **ProTip:** We have provided some sample apps to help you get started with Marko + Lasso
->
-> - [marko-lasso](https://github.com/marko-js/examples/tree/master/examples/lasso-express)
-> - [ui-components-playground](https://github.com/marko-js/examples/tree/master/examples/ui-components-playground)
-
-### Bootstrapping: Non-Lasso
-
-If a JavaScript module bundler other than Lasso is being used then you will need to add some client-side code to bootstrap your application in the browser by doing the following:
-
-1.  Load/import/require all of the UI components that were rendered on the server (loading the top-level UI component is typically sufficient)
-2.  Call `require('marko/components').init()`
-
-For example, if `client.js` is the entry point for your client-side application:
-
-_routes/index/client.js_
-
-```js
-// Load the top-level UI component:
-require("./components/app/index");
-
-// Now that all of the JavaScript modules for the UI component have been
-// loaded and registered we can tell marko to bootstrap/initialize the app
-
-// Initialize and mount all of the server-rendered UI components:
-require("marko/components").init();
-```
-
-> **ProTip:** We have provided some sample apps to help you get started:
->
-> - [marko-webpack](https://github.com/marko-js/examples/tree/master/examples/webpack-express)
-
-# Serialization
-
-For each _top-level_ UI component, Marko will serialize the component's data (including `input` and `state` and any properties added to the UI component instance) down to the browser. You can control which data gets serialized by implementing [`toJSON`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) or by reassigning `this.input` in the UI component's `onInput(input, out)` lifecycle method as shown below:
-
-```javascript
-class {
-    onInput() {
-        // Do not serialize any input:
-        this.input = null;
-
-        // Serialize a new object instead of the provided input:
-        this.input = {
-            foo: 'bar'
-        };
-    }
-}
-```
-
-> NOTE: Marko does allow cycles in serialized objects and Duplicate objects will only be serialized once
-
-# Caveats
-
-There are some caveats associated with rendering a page on the server:
-
-- The UI component data for top-level UI components must be serializable:
-  - Only simple objects, numbers, strings, booleans, arrays and `Date` objects are serializable
-  - Functions are not serializable
-- Care should be taken to avoid having Marko serialize too much data
-- None of the data in `out.global` is serialized by default, but this can be changed as shown below
-
-## Serializing globals
-
-If there are specific properties on the `out.global` object that need to be serialized then they must be whitelisted when the top-level page is rendered on the server. For example, to have the `out.global.apiKey` and the `out.global.locale` properties serialized you would do the following:
-
-```js
-template.render(
-  {
-    $global: {
-      serializedGlobals: {
-        apiKey: true,
-        locale: true
-      }
-    }
-  },
-  res
-);
-```