Alias Sorting

The Alias Sorting plugin orders same-weight tags with readable before: and after: relationships. For example, tagPriority: 'before:script:analytics' places one script before a keyed analytics script.

Relative ordering

Numerical priorities become hard to maintain as your application grows:

• Numbers are arbitrary and their meaning isn't clear
• You need to know all existing priorities to insert a new tag
• Changing one priority might require updating many others

Aliases express the relationship between two tags directly. Keep chains in dependency order because the plugin resolves each alias in a single pass.

Setup

Add the plugin to your Unhead configuration:

import { createHead } from 'unhead/client'
import { AliasSortingPlugin } from 'unhead/plugins'

const head = createHead({
  plugins: [
    AliasSortingPlugin
  ]
})

Usage

Basic Ordering

Use before: or after: with the tag type and key:

useHead(unheadInstance, {
  // First script
  script: [{
    key: 'analytics',
    src: '/analytics.js'
  }],
})

useHead(unheadInstance, {
  // This will render before analytics.js
  script: [{
    src: '/critical.js',
    tagPriority: 'before:script:analytics'
  }]
})

<script src="/critical.js"></script>
<script src="/analytics.js" data-hid="analytics"></script>

Alias format

The format is: {before|after}:{tagName}:{key}

Targets normally use the tag type and an explicit key. For example:

• before:script:analytics: Place before the analytics script
• before:link:styles: Place before the styles link tag

Multiple Dependencies

You can order multiple tags relative to each other:

useHead(unheadInstance, {
  script: [
    {
      key: 'first',
      src: '/a.js'
    },
    {
      key: 'second',
      src: '/b.js',
      tagPriority: 'after:script:first'
    },
    {
      key: 'third',
      src: '/c.js',
      tagPriority: 'after:script:second'
    }
  ]
})

<script src="/a.js" data-hid="first"></script>
<script src="/b.js" data-hid="second"></script>
<script src="/c.js" data-hid="third"></script>

Weight boundaries

Aliases adjust registration order after Unhead has calculated each tag's weight. They do not recalculate the aliasing tag's weight during the current resolution. Use aliases between tags that already share a weight, such as two ordinary scripts or two stylesheets; use numeric or named priorities when a tag must move to another weight group.

Common Use Cases

Critical CSS first

Ensure critical CSS is loaded before other stylesheets:

useHead(unheadInstance, {
  link: [
    {
      key: 'main-css',
      rel: 'stylesheet',
      href: '/css/main.css'
    },
    {
      key: 'critical-css',
      rel: 'stylesheet',
      href: '/css/critical.css',
      tagPriority: 'before:link:main-css'
    }
  ]
})

Script tag order

Aliases control the order in which Unhead renders script tags:

useHead(unheadInstance, {
  script: [
    {
      key: 'jquery',
      src: '/js/jquery.js'
    },
    {
      key: 'plugin',
      src: '/js/jquery-plugin.js',
      tagPriority: 'after:script:jquery'
    },
    {
      key: 'app',
      src: '/js/app.js',
      tagPriority: 'after:script:plugin'
    }
  ]
})

This controls tag order, not execution order. Dynamically inserted scripts follow the browser's script loading model, so use module imports, promises, or explicit load events when one script depends on another. See the HTML script processing model.

Limits and conventions

• Use meaningful keys that describe the tag's purpose
• Keep dependency chains short
• Use numeric or named priorities to cross weight groups

Related

• Tag Positions: Control tag ordering