Using Multiple Marko Versions

TL;DR

marko@6 is not backward compatible
marko@5 is forward compatible
In Marko 5, heuristics determine runtime version per-tag

Marko 5 uses the Class API, and current versions use the Tags API. Marko 6 is not backwards compatible, so if marko@6 is installed an application cannot use class components out of the box. Instead, Marko 5 is forward compatible. To use multiple versions of Marko together, ensure that Marko 5 is installed at the project root.

Marko 5 and 6 use runtimes which are interoperable but distinct. As such, the compiler determines which runtime to use based on a set of heuristics. Switching between the two runtimes should be avoided as often as possible, so it is preferable to ensure that Tags API components mostly reference other Tags API components.

Tags/Class API Heuristics

The Marko 5 compiler uses a set of heuristics to determine which runtime a template should be compiled to.

Note

These rules are listed in order of precedence, so once one is satisfied none of the others are checked.

Directory Name

In Marko 5 and below custom tags were auto-discovered from /components directories, but in Marko 6 they are discovered from /tags. Since /tags is new to Marko 6, .marko files under /tags must use the Tags API.

Comment Opt-In

Files can be explicitly marked to use a specific API with a /* use [api] */comment. Any comment type is acceptable, and the comment can be anywhere in the file.

// use class
<h1>Class API</h1>
// use class
h1 -- Class API

<!-- use tags -->
<h1>Tags API</h1>
<!-- use tags -->
h1 -- Tags API

Tip

These explicit opt-ins are only necessary if a .marko file isn't an auto-discovered tag and its contents are ambiguous (i. e. none of the following heuristics apply) so in practice they are rarely needed except for sometimes in Marko Run's +page.marko and +layout.marko.

Class API Syntax

If an otherwise ambiguous file contains any of the following syntax, it is detected as Class API (Marko 5):

A class {} block
A style {} block
Inline JS in a $ scriptlet;
An Attribute argument (<button onClick("handleClick")>)
An attribute modifier (:scoped or :no-update)
Any of these tags:
- <await-reorderer> <class> <include-html> <include-text> <init-components> <macro> <module-code> <while>

Tags API Syntax

If an otherwise ambiguous file contains any of the following syntax, it is detected as Tags API (Marko 6):

A tag variable (<div/var>)
The bind shorthand (:=)
Any of these tags:
- <const> <debug> <define> <id> <let> <lifecycle> <log> <return> <try>

<let/count=0>
<button onClick() { count++ }>
  ${count}
</button>
let/count=0
button onClick() { count++ } -- ${count}

Exclusive Tag Library

If a file is otherwise ambiguous but all tags found by the tag discovery mechanism are in a tags/ directory and no components/ directories are discovered, the file falls back into Tags API.

All ambiguous files here use the tags API, because there are no components/.

src/
  +page.marko // Tags API
  tags/
    some-tag.marko

Even one components/ directory will default all ambiguous files to prefer Class API if there are no // use tags comments or tag syntax heuristics.

src/
  components/
    some-component.marko
  some-page/
    +page.marko // Class API
    tags/
      another-tag.marko
  tags/
    some-tag.marko

Contributors

Helpful? You can thank these awesome people! You can also edit this doc if you see any issues or want to improve it.