Routing & Navigation

This guide explains the routing and navigation system using Swup in LamaPress.

Table of Contents

• Overview
• Swup Configuration
  • Link Selection
  • Containers
  • Caching
• Navigation Flow
  • Link Click
  • Page Loading
  • Content Replacement
• Router Methods
  • Page Lifecycle
  • Helper Functions
• Excluding Links
• Best Practices
  • 1. Use data-no-swup
  • 2. Handle External Links
  • 3. Clean Up on Navigation
• Related Documentation

---

Overview

LamaPress uses Swup for client-side routing, providing smooth page transitions without full page reloads. The Router class manages navigation, page lifecycle, and Swup integration.

Swup Configuration

Swup is configured in src/js/core/router/index.js:

this.swup = new Swup({
  containers: ['#page'],
  cache: true,
  linkSelector: 'a[href^="/"]',
  animateHistoryBrowsing: false,
  plugins: [
    // ... plugins
  ],
})

Link Selection

Links are selected automatically:

Included:

• Links to same origin (a[href^="${window.location.origin}"])
• Relative links (a[href^="/"])
• Hash links (a[href^="#"])

Excluded:

• Download links ([download])
• External links ([target="_blank"])
• Links with data-no-swup
• PDF links ([href$=".pdf"])

Containers

Content is replaced in:

containers: ['#page']

The #page element is replaced on navigation.

Caching

Caching is enabled by default:

cache: true

Pages are cached for faster subsequent navigation.

Navigation Flow

Link Click

When a link is clicked:

1. Swup intercepts click
2. Checks if link should be handled
3. Triggers link:click hook
4. PageTransition.transitionOut() is called
5. Navigation proceeds

Page Loading

During page load:

1. Swup fetches new page
2. Extracts content from #page container
3. Triggers content:replace hook
4. Router handles page lifecycle

Content Replacement

On content replace:

1. Previous page stored via setPreviousPage()
2. Route change event triggered
3. New page created via createNextPage()
4. Page enters via enterNextPage()

Router Methods

Page Lifecycle

Router manages page lifecycle:

leavePreviousPage()

• Leaves previous page
• Returns Promise

destroyPreviousPage()

• Destroys previous page and components

createNextPage(nextPage)

• Creates new Page instance
• Initializes components

enterNextPage()

• Enters new page
• Triggers component enter() methods

getPages()

• Returns { nextPage, previousPage } elements

Helper Functions

Use helper to get router methods:

import { getRouterMethods } from '@src/js/core/router'

const { leavePreviousPage, createNextPage, enterNextPage } = getRouterMethods()

Excluding Links

Exclude links from Swup:

Add data-no-swup attribute:

<a href="/external" data-no-swup>External Link</a>

Or use excluded selectors:

• [download]
• [target="_blank"]
• [href$=".pdf"]

Best Practices

1. Use data-no-swup

Exclude links that shouldn't use Swup:

<a href="/external" data-no-swup>External Link</a>
<a href="/file.pdf" data-no-swup>Download PDF</a>

2. Handle External Links

External links are automatically excluded, but you can be explicit:

<a href="https://example.com" target="_blank" rel="noopener">External</a>

3. Clean Up on Navigation

Components should clean up in destroy():

destroy = () => {
  this.timeline?.kill()
  this.element.removeEventListener('click', this.handleClick)
}

Related Documentation

• Page Transitions - Transition system
• JavaScript Architecture - JavaScript system
• Component JavaScript - Component lifecycle

---

Next Steps:

• Review Page Transitions for transition details
• Check JavaScript Architecture for system overview
• See Component JavaScript for component lifecycle