[](https://npmjs.com/package/pinecone-router)
[](https://bundlephobia.com/result?p=pinecone-router@7.5.0)
[](./CHANGELOG.md)
[](https://github.com/pinecone-router/router/tree/7.5.0)
[](https://ko-fi.com/rehhouari)
# Pinecone Router
A small, easy to use, and feature-packed router for Alpine.js.
```html
```
## Features:
- :smile: Easy and familiar syntax well integrated with Alpine.js.
- :gear: [Handler functions](#x-handler) allow you to run functions on for each
route.
- :beginner: [Inline](#inline-templates) and [external](#x-template)
templates to display content.
- :sparkles: 3 Magic helpers to easily access
router data.
- 
Full Typescript support.
- :link: Automatic [click handling](#bypass-click-handling) and
[loading events](#events--loading).
- :hash: [Hash routing](#settings) support.
**Demo**: [Pinecone example](https://pinecone-router.pages.dev/),
[(source code)](./example/).
## Installation
This projects follow the [Semantic Versioning](https://semver.org/) gui=delines.
> [!IMPORTANT]
> Check the [CHANGELOG](./CHANGELOG.md) before major updates.
> [!NOTE]
> If you're upgrading from v6, also see the more compact
> [Upgrade Guide](./upgrade_to_v7.md).
### CDN
Include the following `
```
### NPM
```
npm install pinecone-router
```
```javascript
import PineconeRouter from 'pinecone-router'
import Alpine from 'alpinejs'
Alpine.plugin(PineconeRouter)
Alpine.start()
```
### Browser Module
```javascript
import PineconeRouter from 'https://cdn.jsdelivr.net/npm/pinecone-router@7.5.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()
```
## Usage
### [Demo & Usage Example](https://pinecone-router.pages.dev/)
## `x-route`
Declare routes by creating a template tag with the `x-route` directive.
```html
```
> [!NOTE]
> Alternatively you can
> [use Javascript to add routes](#add--remove-routes-programmatically)
> [!NOTE]
> Read more: [`notfound` route](#notfound-route), [Named routes](#named-routes)
### Route matching
#### Segments types
- **Literal** (`/literal`): Matches `/literal` but not `/something-else`
- **Named** (`/:name`): Matches `/john` or `/123` but not `/john/doe` or `/`
- **Optional** (`/:name?`): Matches `/profile` or `/profile/john` but
not `/profile/john/settings`
- **Rest** (`/users/:rest+`): Matches `/users/john` or `/users/john/settings`
but not `/users` (matches one or more)
- **Wildcard** (`/:path*`): Matches `/files`, `/files/docs`,
`/files/docs/report.pdf` (matches zero or more)
- **Suffix** (`/movies/:title.mp4`): Matches `/movies/avatar.mp4` but not
`/movies/avatar.mov` or `/movies/avatar`
- **Suffix Pattern** (`/movies/:title.(mp4|mov)`): Matches `/movies/avatar.mp4`
or `/movies/avatar.mov` but not `/movies/avatar.avi` or `/movies/avatar`
> [!IMPORTANT]
> Trailing slashes are normalized (both `/about` and `/about/` work the same)
>
> Matching is case-insensitive
#### Accessing params
You can access the params' values with:
- `$params` magic helper: `$params.paramName` from Alpine.js components.
- `context.params.paramName` from inside handlers.
- [`PineconeRouter.context.params`](#pineconerouter-object) from elsewhere
in JS.
## `x-template`
`x-template` allows you to display content everytime the _route changes_.
### Inline templates
By adding an empty `x-template` attribute to a route template element,
Pinecone Router will render its children when the route is matched.
```html
Hello World!
Works with multiple children as well
```
In this example it will inserts the child elements into the document the same
way `x-if` does: _after the `template` tag_.
#### Modifiers
- **`.target`**: `.target.app` will render the inline template inside
the element with the `app` ID:
```html
Hello World!
```
> [!TIP]
> Default Target ID can be set globally in [Settings](#settings).
### External templates
`x-template` also allows you to specify one or more external template files
to be fetched from a URL.
```html
```
In this example it will fetch the html files and inserts them in the document
the same way `x-if` does: after the appropriate `template` tags.
#### Modifiers
- **`.preload`**: Fetches the templates after the first page load at
`low` priority, without waiting for the route to be matched.
- **`.target`**: Takes an ID paramater for example `.target.app` will render
the template inside the element with the `app` ID
- **`.interpolate`**: Enable named route params in template urls.
```html
```
> [!NOTE]
> Templates's content are cached by PineconeRouter in a variable when loaded,
> and are automatically cleared on browser page reload.
> [!NOTE]
> When fetching a template fails, it adispatches a
> [`pinecone:fetch-error`](#events--loading) event to `document`.
> [!TIP]
> Modifiers can be used simulateneously: `x-template.preload.target.app`
> For obvious reasons, `.preload` cannot be used with `.interpolate`.
> [!TIP]
> Preload can be used globally in [Settings](#settings).
> [!TIP]
> Default Target ID can be set globally in [Settings](#settings).
### Embeded Scripts
Templates can have their own script elements, which will run when the route is
matched.
`/template.html`:
```html
```
> [!IMPORTANT]
> Templates does _not_ re-render when the path/params changes on the same route.
> `init()` will run only once until the user visits another route then comes
> back.
> [!TIP]
> To run a function when params change, use `x-effect` or `$watch`:
```html
```
#### `x-run` directive
Embedded scripts can be made to run conditionally and/or only once through the
`x-run` directive.
##### `x-run.once`
This will run the script only once per route, even if the route is visited
again.
This could be helpful for library initialization etc.
```html
```
`PineconeRouter.settings()` returns the current settings.
### Settings object
```ts
export interface Settings {
/**
* enable hash routing
* @default false: boolean
*/
hash: boolean
/**
* The base path of the site, for example /blog.
* @default `/`
*/
basePath: string
/**
* Set an optional ID for where the templates will render by default.
* This can be overridden by the .target modifier.
* @default undefined
*/
targetID?: string
/**
* Set to false if you don't want to intercept link clicks by default.
* @default true
*/
handleClicks: boolean
/**
* Handlers that will run on every route.
* @default []
*/
globalHandlers: Handler[]
/**
* Set to true to preload all templates.
* @default false
* */
preload: boolean
/**
* The options object to be passed to fetch requests (second argument)
* excluding `priority` which is set by the router.
*/
fetchOptions: RequestInit
/**
* Set to false to disable calling history.pushState().
* This means that the url wont change when navigating.
* @default true
*/
pushState: boolean
}
```
Read more: [Base Path](#base-path)
## Route object
```ts
export interface Route {
/**
* The regex pattern used to match the route.
* @internal
*/
readonly pattern: RegExp
/**
* The raw route path
*/
readonly path: string
/**
* The name of the route
*/
readonly name: string
match(path: string): undefined | { [key: string]: string }
handlers: Handler[]
templates: string[]
}
export interface RouteOptions {
handlers?: Route['handlers']
interpolate?: boolean
templates?: string[]
targetID?: string
preload?: boolean
name?: string
}
```
## Navigation History
Besides updating the browser history, Pinecone Router also has its own
independent navigation [history object](#navigationhistory-object), keeping
track of path visits, and allowing you to do `back()` and `forward()`
operations without relying on the browser API.
The way it works is by recording all paths visited, excluding:
- **Duplicates**; meaning if you're on '/home' and you click a link that goes
to '/home', it wont affect the history.
- **Redirects**: if you're on `/home` and you visit `/profile/old` which has a
handler that redirects you to` /profile/new`, it will not add `/profile/old`
to the history, only /profile/new.
If you click a link after using `back()`, meaning the `history.index`
is not `history.entries.length-1`, it will remove all elements
from `entries` starting
from the `history.index` to the end, then appends the current path.
### NavigationHistory object
To access the NavigationHistory object you can use
- The `$history` magic helper.
- [PineconeRouter.history](#pineconerouter-object).
```ts
export interface NavigationHistory {
/**
* The current history index
*/
index: number
/**
* The list of history entries
*/
entries: string[]
/**
* Check if the router can navigate backward
* @returns {boolean} true if the router can go back
*/
canGoBack: () => boolean
/**
* Go back to the previous route in the navigation history
*/
back: () => void
/**
* Check if the router can navigate forward
*
* @returns {boolean} true if the router can go forward
*/
canGoForward: () => boolean
/**
* Go to the next route in the navigation history
*/
forward: () => void
/**
* Navigate to a specific position in the navigation history
*
* @param index The index of the navigation position to navigate to
* @returns void
*/
to: (index: number) => void
}
```
> [!TIP]
> Use [`PineconeRouter.canGoBack()`](#pineconerouter-object) or
> [`PineconeRouter.canGoForward()`](#pineconerouter-object) to check if the
> operation is possible, for example to disable the appropriate buttons.
## Others
### `notfound` route
By default when PineconeRouter initializes, a default `notfound` route
is created with the handler:
```js
;(ctx) => console.error(new ReferenceError(ROUTE_NOT_FOUND(ctx.path)))
```
You can create a new `template` element using `x-route="notfound"`
with`x-template` and or `x-handler` to add templates and replace the defaul
handler.
You can also update the `notfound` route [programmatically](#adding-a-template),
using [`PineconeRouter.add`](#pineconerouter-object), to which `notfound` is
the only expection that wont throw an error due to an exisitng route.
### Named routes
You can add an optional name to the route which can be helpful in certain
situations:
- With x-route:
```html
```
- With JS:
```js
PineconeRouter.add('/test', { name: 'name' })
```
- Access inside handlers:
```js
function handler(context, controller) {
console.log('route name:', context.route.name) // route name: name
}
```
> [!NOTE]
> If there was no route name suplied, it will fallback to the route's path.
>
> Names don't have to be unique.
### Base Path
After setting a [`Settings.basePath`](#settings), it will automatically added to
`x-route` & `x-template` paths, `PineconeRouter.add()`, and to very navigation
request, be it link clicks or `navigate()` calls.
This means if you set the `basePath` to `/parent`, you can now just write:
- `x-route="/about"` rather than `x-route="/parent/about"`.
- `x-template="/views/home.html"` rather than
`x-template="/parent/views/home.html"`.
- `$router.navigate('/about')` rather than `$router.navigate('/parent/about')`
> [!NOTE]
> When using hash routing, basePath will only be added to templates urls.
> Which makes sense because hash routing don't care about the pathname
> only the hash.
### Bypass click handling
By default Pinecone Router intercept all clicks on anchor elements with
[valid attribues](./src/links.ts).
Adding a `native` / `data-native` attribute to a link will prevent Pinecone
Router from handling it:
```html
This will be handled by the browser
```
### Disable click handling globally
You can set [`Settings.handleClicks`](#settings) to false to disable
automatically handling links by the router, unless an `x-link` attribute is
set on the anchor element.
When disabeld:
```html
This will reload the page
This won't reload the page
```
### Events / Loading
| name | recipient | when it is dispatched |
| ------------------------ | --------- | ----------------------------------- |
| **pinecone:start** | document | loading starts |
| **pinecone:end** | document | loading ends |
| **pinecone:fetch-error** | document | fetching of external templates fail |
Usage from Alpine.js:
```html
```
> [!TIP]
> You can easily use [nProgress](http://ricostacruz.com/nprogress) with
> `x-template`:
```js
document.addEventListener('pinecone:start', () => NProgress.start())
document.addEventListener('pinecone:end', () => NProgress.done())
document.addEventListener('pinecone:fetch-error', (err) => console.error(err))
```
> [!TIP]
> You can also use [$router.loading](#pineconerouter-object) to check the
> loading state reactively.
### Add & Remove Routes Programmatically
you can add routes & remove them anytime programmatically using Javascript.
#### Adding a route
```js
window.PineconeRouter.add(path, options)
```
- path: string, the route's path.
- options: RouteOptions, array of route options:
See [RouteOptions](#route-object)
Note that by adding handlers this way you wont have access to the `this` of the
alpine.js component if the handler is part of one.
#### Adding a template
You must add a local targetID in options or set a global one in
[Settings](#settings):
```html
```
> [!NOTE]
> As of version 7.4.0, the templates added through this method will be added
> automatically as template elements with an x-template directive and appended
> to the end of the body tag. this means they will function the same way as
> those added in the declarative way. ie. they will be hidden automatically
> when switching to another route.
> [!NOTE]
> if no targetID is provided through settings or route options, the template
> will be rendered at the bottom of the body tag, after the created template
> tag
#### Removing a route
[`PineconeRouter.remove(path)`](#pineconerouter-object)
**Navigating from Javascript**:
To navigate to another page from javascript you can use:
[`PineconeRouter.navigate(path)`](#pineconerouter-object)
## Compatibility
| Version | Alpine.js Version |
| ------- | ----------------- |
| ^v2.x | v3 |
| v1.x | v2 |
## Contributing:
Please refer to [CONTRIBUTING.md](/CONTRIBUTING.md)
## Credits
[regexparam](https://github.com/lukeed/regexparam) for new route matching logic
[@shaun/alpinejs-router](https://github.com/shaunlee/alpinejs-router) for
the new x-if inspired [template logic](./src/templates.ts)
Click handling intially method from
[page.js](https://github.com/visionmedia/page.js/blob/master/index.js#L345).
## Acknowledgment
[@KevinBatdorf](https://twitter.com/KevinBatdorf) for many ideas and early
feedback!
[Let's code a client side router for your frameworkless SPA](https://medium.com/swlh/lets-code-a-client-side-router-for-your-no-framework-spa-19da93105e10)
teaching client-side routing basic concepts.
[@shaun/alpinejs-router](https://github.com/shaunlee/alpinejs-router/) for
being a reference of how things can be done differently.
Last but not least, everyone opening issues,discussions, and pull requests
with bug reports and feature requests!
## License
Copyright (c) 2021-2025 Rafik El Hadi Houari and contributors
Licensed under the MIT license, see [LICENSE.md](LICENSE.md) for details.
Pinecone Router Logo by Rafik El Hadi Houari is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.
> Code from [Page.js](https://github.com/visionmedia/page.js#license) is licensed under the MIT License.
> Copyright (c) 2012 TJ Holowaychuk
> Code from [@shaun/alpinejs-router](https://github.com/shaunlee/alpinejs-router/) is licensed under the MIT License.
> Copyright (c) 2022 Shaun Li
> Code from [regexparam](https://github.com/lukeed/regexparam) is licensed is licensed under the MIT License.
> Copyright (c) Luke Edwards