Pinecone Router

By default, Pinecone Router creates a notfound route that logs a ReferenceError when a path is not matched. You can override this behavior in two ways:

1. Declaratively: Use a <template> element with x-route="notfound" combined with x-template or x-handler.
2. Programmatically: Use PineconeRouter.add('notfound', { ... }). Unlike other routes, adding to notfound will not throw an error if the route already exists.

<template x-route="notfound" x-template="/404.html"></template>

The PineconeRouter object is the central controller for the routing system. You can access it via several methods depending on your environment:

• Alpine.js components: Use the $router magic helper.
• JS Modules: Use window.PineconeRouter.
• Global JS: Use PineconeRouter.
• Alpine Global: Use Alpine.$router.

Once a route with named segments (e.g., /:name) is matched, you can access the parameter values in three ways:

1. In Alpine.js components: Use the $params magic helper (e.g., $params.name).
2. Inside route handlers: Use context.params.paramName.
3. In plain JavaScript: Use PineconeRouter.context.params.

Handlers in version 7.x have undergone several changes regarding context access and arguments:

• Context Access: Do not use context.navigate or context.redirect as these have been removed from the Context object. Instead, use this.$router.navigate() inside handlers to perform redirects.
• Argument Changes: Handlers now receive a second argument of type AbortController.
• Context Scope: Handlers must use the provided local context parameter. The global context ($router.context) is not updated until handlers finish executing.

You can integrate Pinecone Router into your project using three different methods depending on your build setup.

CDN

Include the script tag in your <head> before Alpine.js:

<script src="https://cdn.jsdelivr.net/npm/pinecone-router@7.6.0/dist/router.min.js"></script>

NPM

Install the package via npm:

npm install pinecone-router

Then, register it as an Alpine.js plugin:

import PineconeRouter from 'pinecone-router'
import Alpine from 'alpinejs'
Alpine.plugin(PineconeRouter)
Alpine.start()

Browser Module

Use ES modules directly in the browser:

import PineconeRouter from 'https://cdn.jsdelivr.net/npm/pinecone-router@7.6.0/dist/router.esm.js'
import Alpine from 'https://cdn.jsdelivr.net/npm/alpinejs@3.14.9/dist/module.esm.js'
Alpine.plugin(PineconeRouter)
Alpine.start()

Template usage in version 7.x has the following requirements:

• Inline Templates: You must now add an empty x-template directive to use inline templates.
• Structure: Templates now support multiple root elements and multiple <script> tags.

The router provides a loading property and dispatches DOM events to track navigation lifecycle:

• loading: A boolean indicating if a navigation is currently in progress.
• pinecone:start: Dispatched when loading becomes true.
• pinecone:end: Dispatched when loading becomes false.
• pinecone:handler-error: Dispatched as a CustomEvent when a route handler fails. The error details are contained in the detail property.

// Listen for loading start
document.addEventListener('pinecone:start', () => {
  console.log('Navigation started...');
});

// Listen for errors
document.addEventListener('pinecone:handler-error', (event) => {
  console.error('Handler failed:', event.detail);
});

Pinecone Router intercepts clicks on anchor elements by default. You can control this behavior:

Bypass a single link: Add the native or data-native attribute to an anchor tag to let the browser handle the click normally.

<a href="/foo" native>This will be handled by the browser</a>

Disable globally: Set Settings.handleClicks to false. When disabled, the router only handles links that explicitly have the x-link attribute.

<a href="/path">This will reload the page</a>
<a href="/path" x-link>This won't reload the page</a>