marko 5.37.1 → 6.0.0-3.4

package/docs/typescript.md

@@ -1,406 +0,0 @@
-# TypeScript in Marko
-
-> **Note:** Types are supported in Marko v5.22.7+ and Marko v4.24.6+
-
-Marko’s TypeScript support offers in-editor error checking, makes refactoring less scary, verifies that data matches expectations, and even helps with API design.
-
-Or maybe you just want more autocomplete in VSCode. That works too.
-
-## Enabling TypeScript in your Marko project
-
-There are two (non-exclusive) ways to add TypeScript to a Marko project:
-
-- **For sites and web apps**, you can place [a `tsconfig.json` file](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) at the project root:
-  <pre>
-  📁 components/
-  📁 node_modules/
-  <img src="./icons/marko.svg" width=16> index.marko
-  📦 package.json
-  <mark><img src="./icons/ts.svg" width=16> tsconfig.json</mark>
-  </pre>
-- **If you’re [publishing packages of Marko tags](https://markojs.com/docs/custom-tags/#publishing-tags-to-npm)**, add the following to [your `marko.json`](./marko-json.md):
-  ```json
-  "script-lang": "ts"
-  ```
-  This will automatically expose type-checking and autocomplete for the published tags.
-
-> **ProTip**: You can also use the `script-lang` method for sites and apps.
-
-## Typing a tag's `input`
-
-A `.marko` file will use any exported `Input` type for [that file’s `input` object](./class-components.md#input).
-
-This can be `export type Input` or `export interface Input`.
-
-### Example
-
-_PriceField.marko_
-
-```marko
-export interface Input {
-  currency: string;
-  amount: number;
-}
-
-<label>
-  Price in ${input.currency}:
-  <input type="number" value=input.amount min=0 step=0.01>
-</label>
-```
-
-You can also import, reuse, and extend `Input` interfaces from other `.marko` or `.ts` files:
-
-```marko
-import { Input as PriceInput } from "<PriceField>";
-import { ExtraTypes } from "lib/utils.ts";
-export type Input = PriceInput & ExtraTypes;
-```
-
-```marko
-import { Input as PriceInput } from "<PriceField>";
-export interface Input extends PriceInput {
-  discounted: boolean;
-  expiresAt: Date;
-};
-```
-
-### Generic `Input`s
-
-[Generic Types and Type Parameters](https://www.typescriptlang.org/docs/handbook/2/generics.html) on `Input` are recognized throughout the entire `.marko` template (excluding [static statements](./syntax.md#static-javascript)).
-
-For example, if you set up a component like this:
-
-_components/my-select.marko_
-
-```marko
-export interface Input<T> {
-  options: T[];
-  onSelect: (newVal: T) => unknown;
-}
-
-static function staticFn() {
-  // can NOT use `T` here
-}
-
-$ const instanceFn = (val: T) => {
-  // can use `T` here
-}
-
-// can use `as T` here
-<select on-input(evt => input.onSelect(options[evt.target.value] as T))>
-  <for|value, i| of=input.options>
-    <option value=i>${value}</option>
-  </for>
-</select>
-```
-
-…then your editor will figure out the types of inputs to that component:
-
-```marko
-<my-select options=[1,2,3] onSelect=val => {}/>
-                                 // ^^^ number
-
-<my-select options=["M","K","O"] onSelect=val => {}/>
-                                       // ^^^ string
-```
-
-## Built-in Marko Types
-
-Marko exposes [type definitions](https://github.com/marko-js/marko/blob/main/packages/marko/index.d.ts) you can reuse in [a TypeScript namespace](https://www.typescriptlang.org/docs/handbook/namespaces.html) called `Marko`:
-
-- **`Marko.Template<Input, Return>`**
-  - The type of a `.marko` file
-  - `typeof import("./template.marko")`
-- **`Marko.TemplateInput<Input>`**
-  - The object accepted by the render methods of a template. It includes the template's `Input` as well as `$global` values.
-- **`Marko.Body<Params, Return>`**
-  - The type of the [body content](./body-content.md) of a tag (`renderBody`)
-- **`Marko.Component<Input, State>`**
-  - The base class for a [class component](./class-components.md)
-- **`Marko.Renderable`**
-  - Values accepted by the [`<${dynamic}/>` tag](./syntax.md#dynamic-tagname)
-  - `string | Marko.Template | Marko.Body | { renderBody: Marko.Body}`
-- **`Marko.Out`**
-  - The render context with methods like `write`, `beginAsync`, etc.
-  - `ReturnType<template.render>`
-- **`Marko.Global`**
-  - The type of the object in `$global` and `out.global` that can be passed to a template's render methods as the `$global` property.
-- **`Marko.RenderResult`**
-  - The [result](./rendering.md#renderresult) of rendering a Marko template
-  - `ReturnType<template.renderSync>`
-  - `Awaited<ReturnType<template.render>>`
-- **`Marko.Emitter`**
-  - `EventEmitter` from `@types/node`
-- **`Marko.NativeTags`**
-  - `Marko.NativeTags`: An object containing all native tags and their types
-- **`Marko.Input<TagName>`** and **`Marko.Return<TagName>`**
-  - Helpers to extract the input and return types native tags (when a string is passed) or a custom tag.
-- **`Marko.BodyParameters<Body>`** and **`Marko.BodyReturnType<Body>`**
-  - Helpers to extract the parameters and return types from the specified `Marko.Body`
-- **`Marko.AttrTag<T>`**
-  - Used to represent types for [attributes tags](./body-content.md#named-body-content)
-  - A single attribute tag, with a `[Symbol.iterator]` to consume any repeated tags.
-
-### Typing `renderBody`
-
-The most commonly used type from the `Marko` namespace is `Marko.Body` which can be used to type `input.renderBody`:
-
-_child.marko_
-
-```marko
-export interface Input {
-  renderBody?: Marko.Body;
-}
-```
-
-Here, the following will be acceptable values:
-
-_index.marko_
-
-```marko
-<child/>
-<child>Text in render body</child>
-<child>
-  <div>Any combination of components</div>
-</child>
-```
-
-Passing other values (including components) will cause a type error:
-
-_index.marko_
-
-```marko
-import OtherTag from "<other-tag>";
-<child renderBody=OtherTag/>
-```
-
-### Typing Tag Parameters
-
-Tag parameters are passed to the `renderBody` by the child tag. For this reason, `Marko.Body` also allows typing of its parameters:
-
-_for-by-two.marko_
-
-```marko
-export interface Input {
-  to: number;
-  renderBody: Marko.Body<[number]>
-}
-
-<for|i| from=0 to=input.to by=2>
-  <${input.renderBody}(i)/>
-</for>
-```
-
-_index.marko_
-
-```marko
-<for-by-two|i| to=10>
-  <div>${i}</div>
-</for-by-two>
-```
-
-### Extending native tag types within a Marko tag
-
-The types for native tags are accessed via the global `Marko.Input` type. Here's an example of a component that extends the `button` html tag:
-
-_color-button.marko_
-
-```marko
-export interface Input extends Marko.Input<"button"> {
-  color: string;
-  renderBody?: Marko.Body;
-}
-
-$ const { color, renderBody, ...restOfInput } = input;
-
-<button style=`color: ${color}` ...restOfInput>
-  <${renderBody}/>
-</button>
-```
-
-### Registering a new native tag (eg for custom elements).
-
-```ts
-interface MyCustomElementAttributes {
-  // ...
-}
-
-declare global {
-  namespace Marko {
-    interface NativeTags {
-      // By adding this entry, you can now use `my-custom-element` as a native html tag.
-      "my-custom-element": MyCustomElementAttributes;
-    }
-  }
-}
-```
-
-### Registering new "global" HTML Attributes
-
-```ts
-declare global {
-  namespace Marko {
-    interface HTMLAttributes {
-      "my-non-standard-attribute"?: string; // Adds this attribute as available on all HTML tags.
-    }
-  }
-}
-```
-
-### Registering CSS Properties (eg for custom properties)
-
-```ts
-declare global {
-  namespace Marko {
-    namespace CSS {
-      interface Properties {
-        "--foo"?: string; // adds a support for a custom `--foo` css property.
-      }
-    }
-  }
-}
-```
-
-## TypeScript Syntax in `.marko`
-
-Any [JavaScript expression in Marko](./syntax.md#inline-javascript) can also be written as a TypeScript expression.
-
-### Tag Type Parameters
-
-```marko
-<child <T>|value: T|>
-  ...
-</child>
-```
-
-### Tag Type Arguments
-
-_components/child.marko_
-
-```marko
-export interface Input<T> {
-  value: T;
-}
-```
-
-_index.marko_
-
-```marko
-// number would be inferred in this case, but we can be explicit
-<child<number> value=1 />
-```
-
-### Method Shorthand Type Parameters
-
-```marko
-<child process<T>() { /* ... */ } />
-```
-
-### Attribute Type Assertions
-
-The types of attribute values can _usually_ be inferred. When needed, you can assert values to be more specific with [TypeScript’s `as` keyword](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#type-assertions):
-
-```marko
-<some-component
-  number=1 as const
-  names=[] as string[]
-/>
-```
-
-# JSDoc Support
-
-For existing projects that want to incrementally add type safety, adding full TypeScript support is a big leap. This is why Marko also includes full support for [incremental typing via JSDoc](https://www.typescriptlang.org/docs/handbook/intro-to-js-ts.html).
-
-## Setup
-
-You can enable type checking in an existing `.marko` file by adding a `// @ts-check` comment at the top:
-
-```js
-// @ts-check
-```
-
-If you want to enable type checking for all Marko & JavaScript files in a JavaScript project, you can switch to using a [`jsconfig.json`](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html#using-tsconfigjson-or-jsconfigjson). You can skip checking some files by adding a `// @ts-nocheck` comment to files.
-
-Once that has been enabled, you can start by typing the input with JSDoc. Here's an example component with typed `input`:
-
-```marko
-// @ts-check
-
-/**
- * @typedef {{
- *   firstName: string,
- *   lastName: string,
- * }} Input
- */
-
-<div>${firstName} ${lastName}</div>
-```
-
-## With a separate `component.js` file
-
-Many components in existing projects adhere to the following structure:
-
-<pre>
-📁 components/
-  📁 color-rotate-button/
-    <img src="./icons/marko.svg" width=16> index.marko
-    <img src="./icons/js.svg" width=16> component.js
-</pre>
-
-The `color-rotate-button` takes a list of colors and moves to the next one each time the button is clicked:
-
-```marko
-<color-rotate-button colors=["red", "blue", "yellow"]>
-  Next Color
-</color-rotate-button>
-```
-
-Here is an example of how this `color-rotate-button` component could be typed:
-
-_components/color-rotate-button/component.js_
-
-```js
-// @ts-check
-
-/**
- * @typedef {{
- *   colors: string[],
- *   renderBody: Marko.Renderable
- * }} Input
- * @typedef {{
- *   colorIndex: number
- * }} State
- * @extends {Marko.Component<Input, State>}
- */
-export default class extends Marko.Component {
-  onCreate() {
-    this.state = {
-      colorIndex: 0,
-    };
-  }
-
-  rotateColor() {
-    this.state.colorIndex =
-      (this.state.colorIndex + 1) % this.input.colors.length;
-  }
-}
-```
-
-_components/color-rotate-button/index.marko_
-
-```marko
-// @ts-check
-
-/* Input will be automatically imported from `component.js`! */
-
-<button
-  onClick('rotateColor')
-  style=`color: ${input.colors[state.colorIndex]}`>
-  <${input.renderBody}/>
-</button>
-```
-
-# CI Type Checking
-
-For type checking Marko files outside of your editor there is the ["@marko/type-check" cli](https://github.com/marko-js/language-server/tree/main/packages/type-check).
-Check out the CLI documentation for more information.

package/docs/vite.md

@@ -1,86 +0,0 @@
-# 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 createServer({
-    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 automatically 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,205 +0,0 @@
-# Marko + Webpack
-
-# Installation
-
-> `@marko/webpack` >= 7 Only supports Marko 5+.
-> For Marko 4 support use `@marko/webpack@6`.
-
-```console
-npm install @marko/webpack
-```
-
-### Loader: `@marko/webpack/loader`
-
-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.
-
-You can override the output by adding a `target` option to the loader of `target: "server" | "browser"`.
-
-### Plugin: `@marko/webpack/plugin`
-
-The plugin actually creates two separate webpack plugins, the `browser` plugin and the `server` plugin.
-
-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.
-
-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.
-
-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>`
-
-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.
-
-#### Example Usage
-
-```marko
-<webpack-assets entry="tracking"/>
-```
-
-#### Example Config
-
-```js
-// ...
-export default [
-  {
-    entry: "./server.js",
-    plugins: [markoPlugin.server],
-    // ...
-  },
-  {
-    // ...
-    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],
-  },
-  {
-    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],
-  },
-];
-```
-
-## 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" }]
-              ]
-            }
-          }
-        }
-      ]
-    }
-  },
-```
-
-## Multiple client-side compilers
-
-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` 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 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: germanTranslations,
-};
-
-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:
-
-```javascript
-template.render({ $global: { buildName: "Browser-de" } });
-```
-
-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 `buildName` does not exist, an error is thrown.
-
-## Multiple copies of Marko
-
-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.
-The `runtimeId` will default to the [`uniqueName` option](https://webpack.js.org/configuration/output/#outputuniquename) from the server compiler in the webpack config.
-
-```js
-import MarkoPlugin from "@marko/webpack/plugin";
-
-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.