Upgrading to version 6

The latest release of Edge contains a handful of breaking changes, some performance improvements and most importantly works only with ES modules. This guide covers the steps you must follow to upgrade to edge.js@6.

Upgrading packages

You can install the latest release from the npm packages registry. For now, the version 6 is tagged with @next tag.

npm i edge.js@next

The functionality of edge-supercharged plugin is now baked into Edge directly, hence you can uninstall this package and remove its usage.

npm uninstall edge-supercharged

If you were using edge-stacks, and edge-iconify, make sure to update these packages as well.

npm i edge-stacks@next
npm i edge-iconify@next

Compatibility plugin

If your projects are not ready for the breaking changes (except ESM migration), you can configure the migrate plugin that provides compatibility between version 5 and 6.

import edge from 'edge.js'
import { migrate } from 'edge.js/plugins/migrate'

edge.use(migrate)

Breaking changes

• All of the packages are now ESM only.
• Requires Node.js >= 18.16.0.
• Layouts and sections have been removed. We recommend using components instead. Configure compatibility plugin to continue using layouts.
• Changes to the Props API.
• Removed @set tag in favor of @let and @assign tags. Learn more.
• Changes to global helpers.

Changes to Props API

The components props have been changed completely, and methods like serialize and serializeExcept no longer exist. Instead, you have to use the toAttrs method.

/**
 * Serialize all attributes
 */
$props.serialize()
$props.toAttrs()

/**
 * Serialize all except the mentioned attributes
 */
$props.serializeExcept(['text'])
$props.except(['text']).toAttrs()

/**
 * Serialize only the mentioned attributes
 */
$props.serializeOnly(['class'])
$props.only(['class']).toAttrs()

/**
 * Merge custom attributes
 */
$props.serializeOnly(['class'], { type: 'text' })
$props.only(['class']).merge({ type: 'text' }).toAttrs()

Removing @set tag in favor of @let and @assign tags

The @set tag has been removed in the favor of new @let and the @assign tags. Their inner workings and syntax are both different from the set tag.

/**
 * Define new variable
 */
@set('username', 'virk')
@let(username = 'virk')

/**
 * Update existing variable
 */
@set('username', 'romain')
@assign(username = 'romain')

/**
 * Mutate object properties
 */
@set(user, 'username', 'romain')
@assign(user.username = 'romain')

Global helpers changes

• Remove e method in favor of html.escape.
• Remove stringify method in favor of js.stringify.
• Remove safe method in favor of html.safe.
• Remove raise method. It was never documented.

{{ e(post.content) }}
{{ html.escape(post.content) }}

{{ stringify(someJSONObject) }}
{{ js.stringify(someJSONObject) }}

{{ safe(post.content) }}
{{ html.safe(post.content) }}