marko 5.17.9 → 5.18.2

package/docs/cloudflare-workers.md

@@ -0,0 +1,34 @@
+# Marko + Cloudflare Workers
+
+See the [the cloudflare sample](https://github.com/marko-js/examples/tree/master/examples/vite-cloudflare)
+project for a working example.
+
+## Usage
+
+When using Marko with [Cloudflare Workers](https://workers.cloudflare.com/) you need to make sure that Marko is loaded with a `worker` [export condition](https://nodejs.org/api/packages.html#conditional-exports). Most bundlers support the ability to define export conditions.
+
+After that point the `template.stream` will now return a worker compatible [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream).
+
+You can then simply respond with the returned stream.
+
+```js
+import template from "./index.marko";
+
+addEventListener("fetch", event => {
+  event.respondWith(handleRequest(event.request));
+});
+
+async function handleRequest(request) {
+  return new Response(template.stream(), {
+    headers: {
+      status: 200,
+      headers: { "content-type": "text/html;charset=UTF-8" }
+    }
+  });
+}
+```
+
+### BYOB (Bring your own bundler)
+
+For the large portion of Marko's API a bundler is required. The example code above assumes that Marko templates can be loaded in your environment.
+Marko supports a number of bundlers, [take a look through our supported bundlers](#bundler-integrations) and pick what works best for you.

package/docs/custom-tags.md

@@ -184,3 +184,18 @@ The [`<macro>`](./core-tags.md#macro) tag allows you to create custom tags in th
 <welcome-message name="Patrick"/>
 <welcome-message name="Austin"/>
 ```
+
+# From Variables
+
+If no other tag would be discovered Marko will check for an in scope variable that matches the tag name.
+
+```marko
+import SomeTag from "./somewhere.marko"
+
+$ const { renderBody } = input;
+$ const MyTag = input.href ? "a" : "button";
+
+<SomeTag/>
+<MyTag/>
+<renderBody/>
+```

package/docs/events.md

@@ -124,7 +124,7 @@ The above code listens to native `change` events from the `<input>` element, and
 
 ```marko
 <form>
-  <email-input name="email" on-email-change(...)/>
+  <email-input name="email" on-email-change("...")/>
 </form>
 ```
 

package/docs/express.md

@@ -1,38 +1,40 @@
-# Express + Marko
+# Marko + Express
 
-See the [marko-express](https://github.com/marko-js/examples/tree/master/examples/lasso-express) sample
+## Quick Start
+
+```terminal
+npm init marko -- --template vite-express
+```
+
+See the [the express sample](https://github.com/marko-js/examples/tree/master/examples/vite-express)
 project for a working example.
 
-## Installation
+## From Scratch
 
-Need to install mark as well as the express-related marko package:
+First install Marko and the express related dependencies:
 
-```
-npm install express --save
-npm install marko --save
-npm install @marko/express --save
+```terminal
+npm install marko @marko/express express --save
 ```
 
-## Skip the view engine
+### Skip the view engine
 
-The built in view engine for express may be asynchronous, but it doesn't support streaming (check out [Rediscovering Progressive HTML Rendering](http://www.ebaytechblog.com/2014/12/08/async-fragments-rediscovering-progressive-html-rendering-with-marko/) to see why this is so important). So instead we'll [bypass the view engine](https://strongloop.com/strongblog/bypassing-express-view-rendering-for-speed-and-modularity/).
+The built in view engine for express may be asynchronous, but it doesn't support streaming (check out [Rediscovering Progressive HTML Rendering](http://www.ebaytechblog.com/2014/12/08/async-fragments-rediscovering-progressive-html-rendering-with-marko/) to see why this is so important). So instead we'll [bypass the view engine](https://strongloop.com/strongblog/bypassing-express-view-rendering-for-speed-and-modularity/) and use [`@marko/express`](https://github.com/marko-js/express/).
 
-## Usage
+### Usage
 
-Marko provides a package (`@marko/express`) to add a `res.marko` method to the express response object. This function works much like `res.render`, but doesn't impose the restrictions of the express view engine and allows you to take full advantage of Marko's streaming and modular approach to templates.
+The [`@marko/express`](https://github.com/marko-js/express/) adds a `res.marko` method to the express response object. This function works much like `res.render`, but doesn't impose the restrictions of the express view engine and allows you to take full advantage of Marko's streaming and modular approach to templates.
 
 By using `res.marko` you'll automatically have access to `req`, `res`, `app`, `app.locals`, and `res.locals` from within your Marko template and custom tags. These values are added to `out.global`.
 
 ```javascript
-require("@marko/compiler/register"); // Allow Node.js to require and load `.marko` files
+import express from "express";
+import markoPlugin from "@marko/express";
+import template from "./template.marko";
 
-var express = require("express");
-var markoExpress = require("@marko/express");
-var template = require("./template");
+const app = express();
 
-var app = express();
-
-app.use(markoExpress()); //enable res.marko(template, data)
+app.use(markoPlugin()); //enable res.marko(template, data)
 
 app.get("/", function (req, res) {
   res.marko(template, {
@@ -44,3 +46,8 @@ app.get("/", function (req, res) {
 
 app.listen(8080);
 ```
+
+### BYOB (Bring your own bundler)
+
+For the large portion of Marko's API a bundler is required. The example code above assumes that Marko templates can be loaded in your environment.
+Marko supports a number of bundlers, [take a look through our supported bundlers](#bundler-integrations) and pick what works best for you.

package/docs/fastify.md

@@ -1,37 +1,47 @@
-# Fastify + Marko
+# Marko + Fastify
 
-See the [lasso-fastify](https://github.com/marko-js/examples/tree/master/examples/lasso-fastify) sample
-project for a fully-working example.
+## Quick Start
 
-## Installation
+```terminal
+npm init marko -- --template vite-fastify
+```
+
+See the [the fastify sample](https://github.com/marko-js/examples/tree/master/examples/vite-fastify)
+project for a working example.
+
+## From Scratch
 
-```bash
-npm install fastify --save
-npm install point-of-view --save
-npm install marko --save
+First install Marko and the fastify related dependencies:
+
+```terminal
+npm install marko @marko/fastify fastify --save
 ```
 
-## Usage
+### Usage
 
-```js
-const fastify = require("fastify")();
+The [`@marko/fastify`](https://github.com/marko-js/fastify/) adds a `reply.marko` decorator to the `reply` object. This function allows us to pass in a Marko template and supports Marko's streaming and modular approach to templates.
 
-fastify.register(require("point-of-view"), {
-  engine: {
-    marko: require("marko")
-  }
-});
+By using `reply.marko` you'll automatically have access to `app.locals`, and `reply.locals` from within your Marko template and custom tags. These values are added to `out.global`.
 
-fastify.get("/", (req, reply) => {
-  reply.view("/index.marko", {
-    name: "Frank",
-    count: 30,
-    colors: ["red", "green", "blue"]
-  });
-});
+```javascript
+import fastify from "fastify";
+import markoPlugin from "@marko/fastify";
+import Template from "./template.marko";
 
-fastify.listen(8080, err => {
-  if (err) throw err;
-  console.log(`Server listening on ${fastify.server.address().port}`);
+const app = fastify();
+
+app.register(markoPlugin);
+
+app.get("/", (request, reply) => {
+  // Streams Marko template into the response.
+  // Forwards errors into fa error handler.
+  reply.marko(Template, { hello: "world" });
 });
+
+await fastify.listen(3000);
 ```
+
+### BYOB (Bring your own bundler)
+
+For the large portion of Marko's API a bundler is required. The example code above assumes that Marko templates can be loaded in your environment.
+Marko supports a number of bundlers, [take a look through our supported bundlers](#bundler-integrations) and pick what works best for you.

package/docs/http.md

@@ -1,27 +1,19 @@
 # Marko + HTTP Server
 
-See the [marko-http](https://github.com/marko-js/examples/tree/master/examples/http) sample
+See the [the http sample](https://github.com/marko-js/examples/tree/master/examples/vite-http)
 project for a working example.
 
-## Installation
-
-```bash
-npm install marko --save
-```
-
 ## Usage
 
 ```js
-require("@marko/compiler/register");
-
-const http = require("http");
-const server = http.createServer();
+import http from "http";
+import template from "./index.marko";
 
 const port = 8080;
-const indexTemplate = require("./index.marko");
+const server = http.createServer();
 
 server.on("request", (req, res) => {
-  indexTemplate.render(
+  template.render(
     {
       name: "Frank",
       count: 30,
@@ -35,3 +27,8 @@ server.listen(port, () => {
   console.log(`Successfully started server on port ${port}`);
 });
 ```
+
+### BYOB (Bring your own bundler)
+
+For the large portion of Marko's API a bundler is required. The example code above assumes that Marko templates can be loaded in your environment.
+Marko supports a number of bundlers, [take a look through our supported bundlers](#bundler-integrations) and pick what works best for you.

package/docs/koa.md

@@ -1,23 +1,22 @@
-# Koa + Marko
+# Marko + Koa
 
-See [the `marko-koa` sample project](https://github.com/marko-js/examples/tree/master/examples/lasso-koa) for a fully-working example.
+See the [the koa sample](https://github.com/marko-js/examples/tree/master/examples/vite-koa)
+project for a working example.
 
 ## Installation
 
-```sh
+```terminal
 npm install koa marko --save
 ```
 
 ## Usage
 
 ```javascript
-require("@marko/compiler/register");
+import Koa from "koa";
+import template from "./index.marko";
 
-const Koa = require("koa");
 const app = new Koa();
 
-const template = require("./index.marko");
-
 app.use((ctx, next) => {
   ctx.type = "html";
   ctx.body = template.stream({
@@ -30,33 +29,7 @@ app.use((ctx, next) => {
 app.listen(8080);
 ```
 
-You may also easily add `gzip` streaming support without additional dependencies:
-
-```javascript
-require("@marko/compiler/register");
-const zlib = require("zlib");
-
-const Koa = require("koa");
-const app = new Koa();
-
-const template = require("./index.marko");
-
-app.use((ctx, next) => {
-  ctx.type = "html";
-  ctx.body = template.stream({
-    name: "Frank",
-    count: 30,
-    colors: ["red", "green", "blue"]
-  });
-
-  ctx.vary("Accept-Encoding");
-  if (ctx.acceptsEncodings("gzip")) {
-    ctx.set("Content-Encoding", "gzip");
-    ctx.body = ctx.body.pipe(
-      zlib.createGzip({ flush: zlib.constants.Z_PARTIAL_FLUSH })
-    );
-  }
-});
+### BYOB (Bring your own bundler)
 
-app.listen(8080);
-```
+For the large portion of Marko's API a bundler is required. The example code above assumes that Marko templates can be loaded in your environment.
+Marko supports a number of bundlers, [take a look through our supported bundlers](#bundler-integrations) and pick what works best for you.

package/docs/marko-vs-react.md

@@ -737,28 +737,23 @@ the server or in the browser. For example, given the following template:
 
 #### Compiled for the server:
 
-```marko
+```js
 var marko_template = require("marko/html").t(__filename),
-    marko_helpers = require("marko/runtime/html/helpers"),
-    marko_escapeXml = marko_helpers.x;
+  marko_helpers = require("marko/runtime/html/helpers"),
+  marko_escapeXml = marko_helpers.x;
 
 function render(input, out) {
-  out.w("<div>Hello " +
-    marko_escapeXml(input.name) +
-    "!</div>");
+  out.w("<div>Hello " + marko_escapeXml(input.name) + "!</div>");
 }
 ```
 
 #### Compiled for the browser:
 
-```marko
+```js
 var marko_template = require("marko/vdom").t(__filename);
 
 function render(input, out) {
-  out.e("DIV", null, 3)
-    .t("Hello ")
-    .t(input.name)
-    .t("!");
+  out.e("DIV", null, 3).t("Hello ").t(input.name).t("!");
 }
 ```
 

package/docs/rollup.md

@@ -1,22 +1,16 @@
 # Marko + Rollup
 
-The [@marko/rollup](https://github.com/marko-js/rollup) transform can be used in conjunction with [rollup](https://github.com/rollup/rollup) to automatically compile Marko templates that are required by other modules.
+# Installation
 
-<!-- The [rollup](https://github.com/marko-js/examples/tree/master/examples/rollup) sample app demonstrates how to use Marko with Rollup. Run `npx @marko/create --template rollup` to use this sample as a starting point for a new app. -->
-
-## Manual Installation
-
-```bash
-npm install rollup @rollup/plugin-commonjs @rollup/plugin-node-resolve @marko/rollup --save-dev
+```console
+npm install @marko/rollup rollup @rollup/plugin-node-resolve @rollup/plugin-commonjs -D
 ```
 
-## Configuration
+# Basic example config
 
-The following is the minimal recommend configuration to use Rollup with Marko:
+**Note: The Marko runtime is authored in commonjs, this means the `@rollup/plugin-commonjs` is required!**
 
-_rollup.config.js_
-
-```js
+```javascript
 import nodeResolve from "@rollup/plugin-node-resolve";
 import commonjs from "@rollup/plugin-commonjs";
 import marko from "@marko/rollup";
@@ -24,12 +18,12 @@ import marko from "@marko/rollup";
 export default {
   ...,
   plugins: [
-    marko(),
+    marko.browser(),
     nodeResolve({
       browser: true,
       extensions: [".js", ".marko"]
     }),
-    // NOTE: Marko 4 compiles to commonjs, this plugin is also required.
+    // NOTE: The Marko runtime uses commonjs so this plugin is also required.
     commonjs({
       extensions: [".js", ".marko"]
     }),
@@ -41,12 +35,166 @@ export default {
 };
 ```
 
-## Usage
+Likewise, if bundling the components for the server use `marko.server()` as the plugin.
+
+# Linked config
+
+If you use _both_ the `server` and `browser` plugins (in a [multi rollup config setup](https://rollupjs.org/guide/en/#configuration-files:~:text=export%20an%20array)) `@marko/rollup` will go into a _linked_ mode.
+In the linked mode you will have access to the [`<rollup>` tag](#rollup-tag) on the server, and the browser config
+will automatically have the [`input`](https://rollupjs.org/guide/en/#input) option set.
+
+```javascript
+export default [{
+  // Config object for bundling server assets.
+  input: "src/your-server-entry.js",
+  plugins: [
+    marko.server()
+    ...
+  ]
+}, {
+  // Config object for bundling browser assets.
+  plugins: [
+    marko.browser()
+    ...
+  ]
+}];
+```
+
+## `<rollup>` tag
+
+In a [linked setup](#linked-config) you have access to the `<rollup>` tag which will provide two [tag parameters](https://markojs.com/docs/syntax/#parameters) that allow you to write out the asset links for your server rendered app.
+
+The first parameter `entry` is the generated `input` name that the server plugin gave to the browser compiler.
+You can use it to find the corresponding entry chunk from rollups build.
+
+The second parameter `output` is an array of `AssetInfo | ChunkInfo` objects with most of the same properties returned from rollup's [`generateBundle` hook](https://rollupjs.org/guide/en/#generatebundle). Some properties have been stripped, notably `code` and `map` since they would be too large to inline directly. A `size` property is also available for all chunks to allow you to be able to filter out empty chunks, or inline chunks of certain size.
+
+```marko
+<head>
+  <rollup|entry, output|>
+    $ const entryChunk = output.find(chunk => chunk.name === entry);
+
+    <if(entryChunk.size /* skip scripts all together if empty js file */)>
+      <for|fileName| of=entryChunk.imports>
+        <link rel="modulepreload" href=fileName/>
+      </for>
+
+      <script async type="module" src=entryChunk.fileName/>
+    </if>
+  </rollup>
+</head>
+```
+
+Ultimately it is up to you to map the chunk data (sometimes referred to as a manifest) into the `<link>`'s and `<script>`'s rendered by your application.
+
+If your rollup browser config contains multiple `output` options, or you have multiple browser configs, all of the `chunks` for each `output` are passed into the `<rollup>` tag.
+
+For example if you have an `esm` and `iife` build:
+
+```javascript
+{
+  plugins: [
+    marko.browser()
+    ...
+  ],
+  output: [
+    { dir: 'dist/iife', format: 'iife' },
+    { dir: 'dist/esm', format: 'esm' }
+  ]
+}
+```
+
+we could access the assets from both builds:
 
-```bash
-# Development:
-rollup -c rollup.config.js
+```marko
+<head>
+  <rollup|entry, iifeOutput, esmOutput|>
+    $ const iifeEntryChunk = iifeOutput.find(chunk => chunk.name === entry);
+    $ const esmEntryChunk = esmOutput.find(chunk => chunk.name === entry);
 
-# Production:
-NODE_ENV=production rollup -c rollup.config.js
+    <script async type="module" src=esmEntryChunk.fileName/>
+    <script nomodule src=iifeEntryChunk.fileName></script>
+  </rollup>
+</head>
+```
+
+and _boom_ you now have a [`module/nomodule` setup](https://philipwalton.com/articles/using-native-javascript-modules-in-production-today/).
+
+# Top level components
+
+Marko was designed to send as little JavaScript to the browser as possible. One of the ways we do this is by automatically determining which templates in your app should be shipped to the browser. When rendering a template on the server, it is only necessary to bundle the styles and interactive components rendered by that template.
+
+To send the minimal amount of Marko templates to the browser you can provide a Marko template directly as the `input`.
+This will also automatically invoke code to initialize the components in the browser, so there is no need to call
+`template.render` yourself in the browser.
+
+> Note: if you are using _linked_ plugins then the server plugin will automatically tell the browser compiler which Marko templates to load.
+
+```js
+export default {
+  input: "./my-marko-page.marko",
+  plugins: [
+    marko.browser(),
+    ...
+  ],
+  ...
+}
+```
+
+## Options
+
+Both the `server` and `browser` plugins can receive the same options.
+
+### options.babelConfig
+
+You can manually override the Babel configuration used by passing a `babelConfig` object to the `@marko/rollup` plugin. By default Babels regular [config file resolution](https://babeljs.io/docs/en/config-files) will be used.
+
+```javascript
+marko.browser({
+  babelConfig: {
+    presets: ["@babel/preset-env"]
+  }
+});
+```
+
+### options.runtimeId
+
+In some cases you may want to embed multiple isolated copies of Marko on the page. Since Marko relies on some `window` properties to initialize this can cause issues. For example, by default Marko will read the server rendered hydration code from `window.$components`. In Marko you can change these `window` properties by rendering with `{ $global: { runtimeId: "MY_MARKO_RUNTIME_ID" } }` as input on the server side.
+
+This plugin exposes a `runtimeId` option produces output that automatically sets `$global.runtimeId` on the server side and initializes properly in the browser.
+
+```js
+const runtimeId = "MY_MARKO_RUNTIME_ID";
+// Make sure the `runtimeId` is the same across all of your plugins!
+marko.server({ runtimeId });
+marko.browser({ runtimeId });
+```
+
+### options.serialize
+
+This option is only available for the `browser` plugin. It allows you to transform the list of chunks serialzed in a [_linked config_](#linked-config) to include whatever you like.
+For example if you _did_ want to include the `code` property from the rollup chunk, to say inline some content, the following would work:
+
+```js
+marko.browser({
+  serialize(output) {
+    return output.map(chunk =>
+      chunk.type === "asset"
+        ? {
+            type: "asset",
+            fileName: chunk.fileName
+          }
+        : {
+            type: "chunk",
+            name: chunk.name,
+            isEntry: chunk.isEntry,
+            fileName: chunk.fileName,
+            code:
+              chunk.code.replace(/^\s+$/, "").length < 1024
+                ? chunk.code
+                : undefined // only inline small code chunks
+          }
+    );
+  }
+});
 ```

package/docs/structure.json

@@ -10,7 +10,8 @@
       "Styles",
       "Events",
       "Body content",
-      "Marko 5 upgrade"
+      "Marko 5 upgrade",
+      "Troubleshooting Streaming"
     ]
   },
   {
@@ -30,11 +31,11 @@
   },
   {
     "title": "Bundler Integrations",
-    "docs": ["Webpack", "Rollup", "Lasso"]
+    "docs": ["Vite", "Webpack", "Rollup", "Lasso"]
   },
   {
     "title": "Server Integrations",
-    "docs": ["Express", "Koa", "HTTP", "Fastify"]
+    "docs": ["Cloudflare Workers", "Express", "Fastify", "Koa", "HTTP"]
   },
   {
     "title": "Tooling",

package/docs/syntax.md

@@ -358,6 +358,16 @@ _HTML Output:_
 <button>Click me!</button>
 ```
 
+As a shorthand if there is a variable in scope and [no other matching tag is discovered](#how-tags-are-discovered) the wrapping `${}` is unnecessary.
+
+For example the following are equivalent:
+
+```marko
+$ const MyTag = href ? 'a' : 'button';
+<${MyTag}/>
+<MyTag/>
+```
+
 > **ProTip:**
 > If you find that you have a wrapper element that is conditional, but whose body should always be rendered then you can use a null dynamic tag. For example, to only render a wrapping `<a>` tag if there is a valid URL then you could do the following:
 >

package/docs/troubleshooting-streaming.md

@@ -0,0 +1,62 @@
+# Troubleshooting HTTP Streams
+
+[The way Marko streams HTML](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Transfer-Encoding) is old and well-supported, but default configurations and assumptions by other software can foil it. This page describes some known culprits that may buffer your Node server’s output HTTP streams.
+
+## Reverse proxies/load balancers
+
+- Turn off proxy buffering, or if you can’t, set the proxy buffer sizes to be reasonably small.
+
+- Make sure the “upstream” HTTP version is 1.1 or higher; HTTP/1.0 and lower do not support streaming.
+
+- Some software doesn’t support HTTP/2 or higher “upstream” connections at all or very well — if your Node server uses HTTP/2, you may need to downgrade.
+
+- Automatic gzip/brotli compression may have their buffer sizes set too high; you can tune their buffers to be smaller for faster streaming in exchange for slightly worse compression.
+
+- Check if “upstream” connections are `keep-alive`: overhead from closing and reopening connections may delay responses.
+
+### NGiNX
+
+Most of NGiNX’s relevant parameters are inside [its builtin `http_proxy` module](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering):
+
+```nginx
+proxy_http_version 1.1; # 1.0 by default
+proxy_buffering off; # on by default
+```
+
+### Apache
+
+Apache’s default configuration works fine with streaming, but your host may have it configured differently. The relevant Apache configuration is inside [its `mod_proxy` and `mod_proxy_*` modules](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html) and their [associated environment variables](https://httpd.apache.org/docs/2.4/env.html).
+
+## CDNs
+
+Content Delivery Networks (CDNs) consider efficient streaming one of their best features, but it may be off by default or if certain features are enabled.
+
+- For Fastly or another provider that uses VCL configuration, check [if backend responses have `beresp.do_stream = true` set](https://developer.fastly.com/reference/vcl/variables/backend-response/beresp-do-stream/).
+
+- 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
+  <network:http.buffer-response-v2>off</network:http.buffer-response-v2>
+  ```
+
+## Node.js itself
+
+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");
+
+const markoTemplate = require("./something.marko");
+
+http
+  .createServer(function (request, response) {
+    response.writeHead(200, { "content-type": "text/html;charset=utf-8" });
+    const templateStream = markoTemplate.stream({});
+    const gzipStream = zlib.createGzip({
+      flush: zlib.constants.Z_PARTIAL_FLUSH
+    });
+    templateStream.pipe(outputStream).pipe(response);
+  })
+  .listen(80);
+```

package/docs/vite.md

@@ -0,0 +1,86 @@
+# Marko + Vite
+
+# Installation
+
+```console
+npm install @marko/vite vite
+```
+
+# Example config
+
+```javascript
+import { defineConfig } from "vite";
+import marko from "@marko/vite";
+export default defineConfig({
+  plugins: [marko()]
+});
+```
+
+# Linked Mode
+
+By default this plugin operates in `linked` mode (you can disabled this by passing [`linked: false` as an option](#optionslinked)). In `linked` mode the plugin automatically discovers all of the entry `.marko` files while compiling the server, and tells `Vite` which modules to load in the browser.
+
+With this you _do not_ create `.html` files for `Vite`, it's Marko all the way down!
+Scripts, styles and other content that _would have_ been injected into the `.html` files is instead automatically injected into your `.marko` templates.
+
+In this mode you must use the [Vite SSR API](https://vitejs.dev/guide/ssr.html#setting-up-the-dev-server).
+
+Here's an example using `express`.
+
+```js
+import { createServer } from "vite";
+
+const app = express();
+let loadTemplate;
+
+if (process.env.NODE_ENV === "production") {
+  // Use Vite's built asset in prod mode.
+  loadTemplate = () => import("./dist");
+} else {
+  // Hookup the vite dev server.
+  const vite = await createViteServer({
+    server: { middlewareMode: true }
+  });
+
+  app.use(vite.middlewares);
+  loadTemplate = () => vite.ssrLoadModule("./template.marko");
+}
+
+app.get("/", async (req, res) => {
+  const template = (await loadTemplate()).default;
+  // When the template is loaded, it will automaticall have `vite` assets inlined.
+  template.render({ hello: "world" }, res);
+);
+
+app.listen(3000);
+```
+
+> For a more real world setup check out our [vite express](https://github.com/marko-js/examples/tree/master/examples/vite-express) example app.
+
+# Options
+
+### options.babelConfig
+
+You can manually override Marko's Babel configuration by passing a `babelConfig` object to the `@marko/vite` plugin. By default Babel's regular [config file resolution](https://babeljs.io/docs/en/config-files) will be used.
+
+```javascript
+marko({
+  babelConfig: {
+    presets: ["@babel/preset-env"]
+  }
+});
+```
+
+### options.runtimeId
+
+In some cases you may want to embed multiple isolated copies of Marko on the page. Since Marko relies on some `window` properties to initialize this can cause issues. For example, by default Marko will read the server rendered hydration code from `window.$components`. In Marko you can change these `window` properties by rendering with `{ $global: { runtimeId: "MY_MARKO_RUNTIME_ID" } }` as input on the server side.
+
+This plugin exposes a `runtimeId` option produces output that automatically sets `$global.runtimeId` on the server side and initializes properly in the browser.
+
+```js
+marko({ runtimeId: "MY_MARKO_RUNTIME_ID" });
+```
+
+### options.linked
+
+Set this to `false` to opt out of [linked mode](#linked-mode). When this is false, the plugin will only handle resolving and transforming `.marko` files.

package/docs/webpack.md

@@ -1,144 +1,205 @@
 # Marko + Webpack
 
-The [@marko/webpack/loader](https://github.com/marko-js/webpack) loader for [Webpack](https://webpack.github.io/) will automatically compile all imported Marko templates during bundling. In addition, it will automatically bundle any template dependencies (including required CSS).
+# Installation
 
-> **ProTip**: Want to see it in action? Check out the [`marko-webpack`](https://github.com/marko-js/examples/tree/master/examples/webpack-express) demo repository. Or run `npx @marko/create --template webpack-express` to use this sample as a starting point for a new app.
+> `@marko/webpack` >= 7 Only supports Marko 5+.
+> For Marko 4 support use `@marko/webpack@6`.
 
-## Installation
-
-```
-npm install marko
-npm install webpack @marko/webpack --save-dev
+```console
+npm install @marko/webpack
 ```
 
-## Client rendering
+### Loader: `@marko/webpack/loader`
 
-Let's say we have a simple view that we want to render in the browser: `hello.marko`
+The loader portion of this module can be used standalone and simply transforms your Marko templates into the appropriate JavaScript depending on your webpack target.
 
-_hello.marko_
+You can override the output by adding a `target` option to the loader of `target: "server" | "browser"`.
 
-```marko
-<h1>Hello ${input.name}</h1>
-```
+### Plugin: `@marko/webpack/plugin`
 
-First, let's create a `client.js` that requires the view and renders it to the body:
+The plugin actually creates two separate webpack plugins, the `browser` plugin and the `server` plugin.
 
-_client.js_
+These are intended to be used in a isomorphic [webpack multi compiler](https://github.com/webpack/webpack/tree/master/examples/multi-compiler) where you are bundling both the server and the browser. The way it works is that the server plugin is going to analyze the top level Marko components in your server and automatically communicate with the browser compiler to retrieve the assets for that template.
 
-```js
-import MyTemplate from "./hello.marko";
+This plugin also analyzes the top level Marko templates and determines if it is possible for them to rerender (currently the heuristic is simply does the component have an associated `class` or `component.js`). The plugin will automatically skip sending down any unnecessary top level templates to the browser.
 
-MyTemplate.renderSync({ name: "Marko" }).appendTo(document.body);
-```
+The end result is that you setup a multi compiler (as shown below) and you can simply import Marko templates, and all assets are automatically generated and inlined into an optimized server response. No need to keep track of a webpack manifest yourself!
+
+### Tag: `<webpack-assets>`
 
-Now, let's configure `webpack` to compile the `client.js` file and use `@marko/webpack/loader` for any `*.marko` files:
+The `<webpack-assets>` tag can be used along with the plugin in a multi-compiler setup. This tag allows you to inject `<script>`/`<style>` tags into a server-rendered template for the assets of an entry in the client compiler.
 
-_webpack.config.js_
+#### Example Usage
+
+```marko
+<webpack-assets entry="tracking"/>
+```
+
+#### Example Config
 
 ```js
-module.exports = {
-  entry: "./client.js",
-  output: {
-    path: __dirname,
-    filename: "static/bundle.js"
+// ...
+export default [
+  {
+    entry: "./server.js",
+    plugins: [markoPlugin.server]
+    // ...
   },
-  resolve: {
-    extensions: [".js", ".marko"]
+  {
+    // ...
+    entry: {
+      tracking: "./tracking.js"
+    },
+    plugins: [markoPlugin.browser]
+  }
+];
+```
+
+# Example
+
+```javascript
+import MarkoPlugin from "@marko/webpack/plugin";
+
+const markoPlugin = new MarkoPlugin();
+
+export default [
+  {
+    entry: "./server.js",
+    module: {
+      rules: [
+        {
+          test: /\.marko$/,
+          loader: "@marko/webpack/loader"
+        }
+      ]
+    },
+    plugins: [markoPlugin.server]
   },
-  module: {
+  {
     rules: [
       {
         test: /\.marko$/,
         loader: "@marko/webpack/loader"
+      },
+      // If using `style` blocks with Marko you must use an appropriate loader
+      {
+        test: /\.css$/,
+        use: ["style-loader", "css-loader"]
       }
-    ]
+    ],
+    plugins: [markoPlugin.browser]
   }
-};
+];
 ```
 
-Run `webpack` from your terminal and you'll have a new `static/bundle.js` file created. Reference that from an html file and you're good to go.
+## Babel options (Marko 5+)
+
+If you are using Marko 5 with this plugin you can manually override the Babel configuration used by passing a `babelConfig` object along side the `@marko/webpack/loader`. By default Babels regular [config file resolution](https://babeljs.io/docs/en/config-files) will be used.
+
+```javascript
+export default {
+    module: {
+      rules: [
+        {
+          test: /\.marko$/,
+          loader: "@marko/webpack/loader",
+          options: {
+            babelConfig: {
+              presets: [
+                ["@babel/preset-env", { node: "current" }]
+              ]
+            }
+          }
+        }
+      ]
+    }
+  },
+```
 
-_index.html_
+## Multiple client side compilers
 
-```html
-<!DOCTYPE html>
-<html>
-  <body>
-    <script src="static/bundle.js"></script>
-  </body>
-</html>
-```
+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).
 
-Load up that page in your browser and you should see `Hello Marko` staring back at you.
+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.
 
-## Using CSS pre-processors
+For example with the webpack i18n plugin you might have a config like the following:
 
-If you're using inline css with pre-processors, you must configure the appropriate loader.
+```js
+import MarkoPlugin from "@marko/webpack/plugin";
+import I18nPlugin from "i18n-webpack-plugin";
 
-_pretty.marko_
+const languages = {
+  en: null,
+  de: require("./de.json")
+};
 
-```marko
-style.less {
-    .pretty {
-        color:@pretty-color;
-    }
-}
+const markoPlugin = new MarkoPlugin();
+
+export default [
+  {
+    name: "Server",
+    entry: "./server.js",
+    module: {
+      rules: [
+        {
+          test: /\.marko$/,
+          loader: "@marko/webpack/loader"
+        }
+      ]
+    },
+    plugins: [markoPlugin.server]
+  },
+  ...Object.keys(languages).map(language => ({
+    name: `Browser-${language}`,
+    rules: [
+      {
+        test: /\.marko$/,
+        loader: "@marko/webpack/loader"
+      },
+      // If using `style` blocks with Marko you must use an appropriate loader
+      {
+        test: /\.css$/,
+        use: ["style-loader", "css-loader"]
+      }
+    ],
+    plugins: [new I18nPlugin(languages[language]), markoPlugin.browser]
+  }))
+];
+```
+
+With the above config you can render your top level Marko template server side with a `$global.buildName`, like so:
 
-<div.pretty/>
+```javascript
+template.render({ $global: { buildName: "Browser-de" } });
 ```
 
-_webpack.config.js_
+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:
 
-```js
-//...
-module: {
-  rules: [
-    //...
-    {
-      test: /\.less$/, // matches style.less { ... } from our template
-      use: ["style-loader", "css-loader", "less-loader"]
-    }
-    //...
-  ];
-}
-//...
+```javascript
+template.render({ $global: { buildName: `Browser-${req.language}` } });
 ```
 
-## Extracting CSS
+Note: If a bundle with the provided name does not exist an error will be thrown.
 
-It is recommended to configure the [`MiniCSSExtractPlugin`](https://webpack.js.org/plugins/mini-css-extract-plugin) so that you get a separate css bundle rather than it being included in the JavaScript bundle.
+## Multiple copies of Marko
 
-```
-npm install mini-css-extract-plugin --save-dev
-```
+In some cases you may want to embed multiple isolated copies of Marko on the page. Since Marko relies on some `window` properties to initialize this can cause issues. For example, by default Marko will read the server rendered hydration code from `window.$components`. In Marko you can change these `window` properties by rendering with `{ $global: { runtimeId: "MY_MARKO_RUNTIME_ID" } }` as input on the server side.
 
-_webpack.config.js_
+This plugin exposes a `runtimeId` option produces output that automatically sets `$global.runtimeId` on the server side and initializes properly in the browser.
+The `runtimeId` will default to the [`uniqueName` option](https://webpack.js.org/configuration/output/#outputuniquename) from the server compiler in the webpack config.
 
 ```js
-const CSSExtractPlugin = require("mini-css-extract-plugin");
+import MarkoPlugin from "@marko/webpack/plugin";
 
-module.exports = {
-  entry: "./client.js",
-  resolve: {
-    extensions: [".js", ".marko"]
-  },
-  module: {
-    rules: [
-      {
-        test: /\.marko$/,
-        loader: "@marko/webpack/loader"
-      },
-      {
-        test: /\.(less|css)$/,
-        use: [CSSExtractPlugin.loader, "css-loader", "less-loader"]
-      }
-    ]
-  },
-  plugins: [
-    // Write out CSS bundle to its own file:
-    new CSSExtractPlugin({
-      filename: "[name].css"
-    })
-  ]
-};
+const markoPlugin = new MarkoPlugin({
+  runtimeId: "MY_MARKO_RUNTIME_ID" // default to webpack `output.uniqueName` option.
+});
 ```
+
+Note: This option will also override the default values for the `jsonpFunction`, `chunkCallbackName` and `hotUpdateFunction` webpack `output` options, which all use global variables, to be prefixed with the `runtimeId`.
+
+## Dynamic public paths
+
+When using the plugin, the server will automatically sync the runtime [`__webpack_public_path__`](https://webpack.js.org/guides/public-path/#on-the-fly) with the browser.
+This means that you only need to setup the dynamic public path on the server side.

package/package.json

@@ -1,11 +1,11 @@
 {
     "name": "marko",
-    "version": "5.17.9",
+    "version": "5.18.2",
     "license": "MIT",
     "description": "UI Components + streaming, async, high performance, HTML templating for Node.js and the browser.",
     "dependencies": {
-        "@marko/compiler": "^5.17.6",
-        "@marko/translator-default": "^5.17.9",
+        "@marko/compiler": "^5.18.2",
+        "@marko/translator-default": "^5.18.2",
         "app-module-path": "^2.2.0",
         "argly": "^1.2.0",
         "browser-refresh-client": "1.1.4",
@@ -72,5 +72,5 @@
         "index.js",
         "node-require.js"
     ],
-    "gitHead": "85a4f9922542327b122a94174302f272d2974fb8"
+    "gitHead": "65999cf2accd091c1455705b94b91ca1ed64203f"
 }