π A self-hostable personal dashboard built for you. Includes status-checking, widgets, themes, icon packs, a UI editor and tons more!
Vue awesomedashboarddockerhomelabhomepagemitnodejsorganizationproductivitypwaself-hostedstartpagevue
β¨ Adds alias functionality, to jump strait to app from URL path
Alicia Sykesaa02393ec702
diff --git a/docs/configuring.md b/docs/configuring.mdindex 29427262..5dc28671 100644--- a/docs/configuring.md+++ b/docs/configuring.md@@ -270,6 +270,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)****`icon`** | `string` | _Optional_ | The icon for a given item. Can be a font-awesome icon, favicon, remote URL or local URL. See [`item.icon`](#sectionicon-and-sectionitemicon)**`target`** | `string` | _Optional_ | The opening method for when the item is clicked, either `newtab`, `sametab`, `modal`, `workspace`, `clipboard`, `top` or `parent`. Where `newtab` will open the link in a new tab, `sametab` will open it in the current tab, and `modal` will open a pop-up modal, `workspace` will open in the Workspace view and `clipboard` will copy the URL to system clipboard (but not launch app). Defaults to `newtab`**`hotkey`** | `number` | _Optional_ | Give frequently opened applications a numeric hotkey, between `0 - 9`. You can then just press that key to launch that application.+**`alias`** | `string` | _Optional_ | A short lowercase word which, when visited as a path on your dashboard (e.g. `/some-app`), redirects straight to this item's URL. See [URL Aliases](/docs/searching.md#url-aliases)**`tags`** | `string[]` | _Optional_ | A list of tags, which can be used for improved search**`statusCheck`** | `boolean` | _Optional_ | When set to `true`, Dashy will ping the URL associated with the current service, and display its status as a dot next to the item. The value here will override `appConfig.statusCheck` so you can turn off or on checks for a given service. Defaults to `appConfig.statusCheck`, falls back to `false`**`statusCheckUrl`** | `string` | _Optional_ | If you've enabled `statusCheck`, and want to use a different URL to what is defined under the item, then specify it herediff --git a/docs/searching.md b/docs/searching.mdindex 7dd10e5d..f055c437 100644--- a/docs/searching.md+++ b/docs/searching.md@@ -14,7 +14,7 @@ You can launch a elected app by hitting <kbd>Enter</kbd>. This will open the app## Tags-By default, when searching items are filtered by the `title`, (as well as the `url`, `provider` and `description`). If you need to find results based on text which isn't included in these attributes, then you can add `tags` to a given item.+By default, when searching items are filtered by the `title`, (as well as the `url`, `provider`, `description` and `alias`). If you need to find results based on text which isn't included in these attributes, then you can add `tags` to a given item.```yamlitems:@@ -65,6 +65,28 @@ For apps that you use regularly, you can set a custom keybinding. Use the `hotkeIn the above example, pressing <kbd>2</kbd> will launch Bookstack. Or hitting <kbd>3</kbd> will open Git in the workspace view.+## URL Aliases++Set an `alias` on an item, and visiting that word as a path on your dashboard will redirect you straight to the item's URL. This lets you jump to an app by typing `dashy/jelly` into the address bar, without loading the dashboard first.++```yaml+- title: Jellyfin+ icon: sh-jellyfin+ url: https://jellyfin.lab.local+ alias: jelly+```++Above, visiting `https://dashy.lab.local/jelly` sends you to Jellyfin. Matching ignores case, and an alias which doesn't match any item shows the 404 page. Aliases are also searchable, so typing `jelly` into Dashy's search will surface Jellyfin.++Some limitations to be aware of:+- Aliases must be lowercase, may only contain letters, numbers, hyphens and underscores+- Only items in your main config file are reachable - items on [multi-page](/docs/pages-and-sections.md) sub-pages are not+- Only `http://` and `https://` item URLs can be redirected to+- Items hidden from the current user (via `displayData`) are not reachable by their alias (you need to login to a user with access first)+- Requires history routing (the default). Under `VITE_APP_ROUTING_MODE=hash` the URL would need to be `dashy/#/jelly`+- It's not possible to create aliases for pages Dashy already uses, including: 'home', 'minimal', 'workspace', 'login', 'download' and '404'+- If two items share an alias, the first one in the config wins+## Web SearchIt's possible to launch a web search directly from Dashy, which might be useful if you're using Dashy as your start page. This can be done by typing your query as normal, and then pressing <kbd>β</kbd>/Enter. Web search options are configured under `appConfig.webSearch`.diff --git a/src/main.js b/src/main.jsindex 3d290e75..b61360e8 100644--- a/src/main.js+++ b/src/main.js@@ -72,6 +72,9 @@ const handleAuthFailure = (provider, err) => {const needsOidcLoginPage = () => isOidcLoginPageEnabled() && !isLoggedIn()&& router.currentRoute.value.name !== 'login';+/* A guard can abort the first navigation (like an item alias redirect), leaving no route to render */+const skipMount = () => {};+router.isReady().then(() => {if (isOidcEnabled()) {initOidcAuth().then((reloading) => {@@ -86,4 +89,4 @@ router.isReady().then(() => {} else {mount();}-});+}, skipMount);diff --git a/src/router.js b/src/router.jsindex f47d232f..a71a9ae3 100644--- a/src/router.js+++ b/src/router.js@@ -20,7 +20,7 @@ import { isOidcEnabled } from '@/utils/auth/OidcAuth';import { isKeycloakEnabled } from '@/utils/auth/KeycloakAuth';import { isHeaderAuthEnabled } from '@/utils/auth/HeaderAuth';import { startingView as defaultStartingView, routePaths } from '@/utils/config/defaults';-import { VIEW_META } from '@/utils/config/ConfigHelpers';+import { VIEW_META, getUrlForAlias } from '@/utils/config/ConfigHelpers';import ErrorHandler from '@/utils/logging/ErrorHandler';const progress = new Progress({ color: 'var(--progress-bar)' });@@ -123,6 +123,18 @@ const router = createRouter({next();},},+ { // Item aliases, where /<alias> redirects straight to that item's URL+ path: '/:alias',+ name: 'alias',+ component: () => import('./views/404.vue'),+ beforeEnter: (to, from, next) => {+ const url = getUrlForAlias(store.state.rootConfig?.sections, to.params.alias);+ if (!url) { next('/404'); return; }+ window.location.replace(url);+ progress.end();+ next(false);+ },+ },{ // Redirect any not-found routed to the 404 viewpath: '/:pathMatch(.*)*',redirect: '/404',diff --git a/src/utils/Search.js b/src/utils/Search.jsindex e3feabb7..71c4f8a0 100644--- a/src/utils/Search.js+++ b/src/utils/Search.js@@ -12,13 +12,13 @@ const haystackCache = new WeakMap();const buildHaystack = (tile) => {const {- title, description, provider, url, tags, subItems,+ title, description, provider, url, tags, alias, subItems,} = tile;const tagsStr = Array.isArray(tags) ? tags.join(' ') : (tags || '');const subText = Array.isArray(subItems)? subItems.map((s) => `${s.title || ''} ${s.url || ''}`).join(' '): '';- return normalize(`${title || ''} ${provider || ''} ${description || ''} ${tagsStr} ${url || ''} ${subText}`);+ return normalize(`${title || ''} ${provider || ''} ${description || ''} ${tagsStr} ${url || ''} ${alias || ''} ${subText}`);};const getHaystack = (tile) => {@@ -32,7 +32,7 @@ const getHaystack = (tile) => {/*** Filter tiles based on users search term, and returns a filtered list- * Will match based on title, description, provider, hostname from url and tags+ * Will match based on title, description, provider, hostname from url, tags and alias* Ignores case, special characters and other irrelevant things* @param {array} allTiles An array of tiles* @param {string} searchTerm The users search termdiff --git a/src/utils/config/ConfigHelpers.js b/src/utils/config/ConfigHelpers.jsindex 42c1bb78..0a2b17a5 100644--- a/src/utils/config/ConfigHelpers.js+++ b/src/utils/config/ConfigHelpers.js@@ -1,9 +1,11 @@import ConfigAccumulator from '@/utils/config/ConfigAccumalator';import filterUserSections from '@/utils/CheckSectionVisibility';+import checkItemVisibility from '@/utils/CheckItemVisibility';import { languages } from '@/utils/languages';import {visibleComponents,localStorageKeys,+ routePaths,language as defaultLanguage,} from '@/utils/config/defaults';@@ -189,6 +191,33 @@ export const getCustomKeyShortcuts = (sections) => (sections || []).filter((item) => item.hotkey).map((item) => ({ hotkey: item.hotkey, url: item.url })));+/* Paths owned by Dashy's own views, so can never be claimed as an item alias */+export const RESERVED_ALIASES = Object.freeze(+ Object.values(routePaths).map((path) => path.replace(/^\//, '')),+);++/* Lowercases and strips any surrounding slashes, so alias matching is forgiving */+const normalizeAlias = (alias) => String(alias ?? '').trim().toLowerCase().replace(/^\/+|\/+$/g, '');++/* Redirects must go somewhere absolute and browsable, never to javascript: or a relative path */+const isRedirectable = (url) => {+ try { return ['http:', 'https:'].includes(new URL(url).protocol); } catch { return false; }+};++/**+ * Returns the URL of the item assigned the given alias, used for /<alias> redirects+ * Pass the root config's sections, so a redirect never depends on the page being viewed+ */+export const getUrlForAlias = (sections, alias) => {+ const target = normalizeAlias(alias);+ if (!target || RESERVED_ALIASES.includes(target)) return undefined;+ const match = filterUserSections(sections || [])+ .flatMap((section) => section.items || [])+ .find((item) => item.alias && normalizeAlias(item.alias) === target);+ if (!match || !checkItemVisibility(match) || !isRedirectable(match.url)) return undefined;+ return match.url;+};+/*** Gets the users chosen language. Defaults to English.* If for any reason a lang code changes, add to legacyAliases for backwards compatdiff --git a/src/utils/config/ConfigSchema.json b/src/utils/config/ConfigSchema.jsonindex 1b951f1d..f2285736 100644--- a/src/utils/config/ConfigSchema.json+++ b/src/utils/config/ConfigSchema.json@@ -1311,6 +1311,15 @@"type": "number","description": "A numeric shortcut key, between 0 and 9. Useful for quickly launching frequently used applications"},+ "alias": {+ "title": "URL Alias",+ "type": "string",+ "pattern": "^[a-z0-9_-]+$",+ "not": {+ "enum": ["home", "minimal", "workspace", "login", "download", "404"]+ },+ "description": "A short lowercase word which, when visited as a path on your dashboard (e.g. /my-app), redirects straight to this item"+ },"rel": {"title": "rel","type": "string",diff --git a/tests/unit/alias-visibility.test.js b/tests/unit/alias-visibility.test.jsnew file mode 100644index 00000000..9facbcc6--- /dev/null+++ b/tests/unit/alias-visibility.test.js@@ -0,0 +1,67 @@+import { describe, it, expect, vi, beforeEach } from 'vitest';++vi.mock('@/utils/auth/Auth', () => ({+ getCurrentUser: () => mockUser,+ isLoggedInAsGuest: () => mockIsGuest,+}));++let mockUser = false;+let mockIsGuest = false;++const { getUrlForAlias } = await import('@/utils/config/ConfigHelpers');++const withItem = (displayData) => [{ items: [{ alias: 'app', url: 'https://app.local', displayData }] }];+const withSection = (displayData) => [{ displayData, items: [{ alias: 'app', url: 'https://app.local' }] }];+const setGroups = (info) => { localStorage.getItem.mockReturnValue(info ? JSON.stringify(info) : null); };++describe('getUrlForAlias - visibility rules', () => {+ beforeEach(() => {+ mockUser = false;+ mockIsGuest = false;+ setGroups(null);+ });++ it('resolves an item with no visibility rules', () => {+ expect(getUrlForAlias(withItem(undefined), 'app')).toBe('https://app.local');+ });++ it('honours hideForUsers on the item', () => {+ mockUser = { user: 'alice' };+ expect(getUrlForAlias(withItem({ hideForUsers: ['Alice'] }), 'app')).toBeUndefined();+ expect(getUrlForAlias(withItem({ hideForUsers: ['bob'] }), 'app')).toBe('https://app.local');+ });++ it('honours showForUsers on the item', () => {+ mockUser = { user: 'alice' };+ expect(getUrlForAlias(withItem({ showForUsers: ['bob'] }), 'app')).toBeUndefined();+ expect(getUrlForAlias(withItem({ showForUsers: ['alice'] }), 'app')).toBe('https://app.local');+ });++ it('honours hideForGuests when browsing as a guest', () => {+ mockIsGuest = true;+ expect(getUrlForAlias(withItem({ hideForGuests: true }), 'app')).toBeUndefined();+ mockIsGuest = false;+ expect(getUrlForAlias(withItem({ hideForGuests: true }), 'app')).toBe('https://app.local');+ });++ it('honours hideForGroups and hideForRoles', () => {+ setGroups({ groups: ['devs'], roles: ['viewer'] });+ expect(getUrlForAlias(withItem({ hideForGroups: ['devs'] }), 'app')).toBeUndefined();+ expect(getUrlForAlias(withItem({ hideForRoles: ['viewer'] }), 'app')).toBeUndefined();+ expect(getUrlForAlias(withItem({ hideForGroups: ['admins'] }), 'app')).toBe('https://app.local');+ });++ it('honours showForGroups and showForRoles', () => {+ setGroups({ groups: ['devs'], roles: ['viewer'] });+ expect(getUrlForAlias(withItem({ showForGroups: ['admins'] }), 'app')).toBeUndefined();+ expect(getUrlForAlias(withItem({ showForGroups: ['devs'] }), 'app')).toBe('https://app.local');+ expect(getUrlForAlias(withItem({ showForRoles: ['viewer'] }), 'app')).toBe('https://app.local');+ });++ it('honours the same rules applied at section level', () => {+ mockUser = { user: 'alice' };+ expect(getUrlForAlias(withSection({ hideForUsers: ['alice'] }), 'app')).toBeUndefined();+ expect(getUrlForAlias(withSection({ showForUsers: ['bob'] }), 'app')).toBeUndefined();+ expect(getUrlForAlias(withSection({ hideForUsers: ['bob'] }), 'app')).toBe('https://app.local');+ });+});diff --git a/tests/unit/config-helpers.test.js b/tests/unit/config-helpers.test.jsindex 48a7d112..33fadf39 100644--- a/tests/unit/config-helpers.test.js+++ b/tests/unit/config-helpers.test.js@@ -10,7 +10,10 @@ import {formatConfigPath,componentVisibility,getCustomKeyShortcuts,+ getUrlForAlias,+ RESERVED_ALIASES,} from '@/utils/config/ConfigHelpers';+import schema from '@/utils/config/ConfigSchema.json';describe('ConfigHelpers - makePageName', () => {it('converts page name to lowercase', () => {@@ -400,3 +403,97 @@ describe('ConfigHelpers - getCustomKeyShortcuts', () => {expect(getCustomKeyShortcuts(undefined)).toEqual([]);});});++describe('ConfigHelpers - getUrlForAlias', () => {+ const sections = [+ { name: 'Media', items: [{ title: 'Jellyfin', alias: 'Jelly', url: 'https://jelly.local' }] },+ { name: 'Widgets Only', widgets: [{ type: 'embed' }] },+ { name: 'Tools', items: [{ title: 'No alias', url: 'https://nope.local' }] },+ ];++ it('returns the URL of the item with a matching alias', () => {+ expect(getUrlForAlias(sections, 'jelly')).toBe('https://jelly.local');+ });++ it('matches regardless of case, whitespace or surrounding slashes', () => {+ expect(getUrlForAlias(sections, ' /JELLY/ ')).toBe('https://jelly.local');+ });++ it('returns undefined when no item claims the alias', () => {+ expect(getUrlForAlias(sections, 'plex')).toBeUndefined();+ });++ it('never matches items that have no alias', () => {+ const noAliases = [{ items: [{ title: 'No alias', url: 'https://nope.local' }] }];+ expect(getUrlForAlias(noAliases, 'anything')).toBeUndefined();+ expect(getUrlForAlias(noAliases, '')).toBeUndefined();+ });++ it('does not let a blank alias be reached by a blank lookup', () => {+ const blank = [{ items: [{ alias: ' ', url: 'https://blank.local' }] }];+ expect(getUrlForAlias(blank, '')).toBeUndefined();+ expect(getUrlForAlias(blank, ' ')).toBeUndefined();+ });++ it('ignores aliases YAML has coerced to a non-string', () => {+ const coerced = [{ items: [{ alias: 0, url: 'https://zero.local' }, { alias: false, url: 'https://no.local' }] }];+ expect(getUrlForAlias(coerced, '0')).toBeUndefined();+ expect(getUrlForAlias(coerced, 'false')).toBeUndefined();+ });++ it('refuses to redirect anywhere that is not an absolute http(s) URL', () => {+ const unsafe = [{+ items: [+ { alias: 'xss', url: "javascript:alert('x')" },+ { alias: 'loop', url: 'loop' },+ { alias: 'mail', url: 'mailto:[email protected]' },+ { alias: 'none', title: 'No URL' },+ ],+ }];+ ['xss', 'loop', 'mail', 'none'].forEach((a) => expect(getUrlForAlias(unsafe, a)).toBeUndefined());+ });++ it('skips items the current user is not allowed to see', () => {+ const hidden = [{+ items: [{ alias: 'secret', url: 'https://secret.local', displayData: { showForGroups: ['admins'] } }],+ }];+ expect(getUrlForAlias(hidden, 'secret')).toBeUndefined();+ });++ it('skips items inside a section the current user cannot see', () => {+ const hidden = [{+ displayData: { showForGroups: ['admins'] },+ items: [{ alias: 'secret', url: 'https://secret.local' }],+ }];+ expect(getUrlForAlias(hidden, 'secret')).toBeUndefined();+ });++ it('refuses every reserved word, even when an item claims it', () => {+ const shadowing = [{+ items: RESERVED_ALIASES.map((word) => ({ alias: word, url: `https://evil.local/${word}` })),+ }];+ RESERVED_ALIASES.forEach((word) => expect(getUrlForAlias(shadowing, word)).toBeUndefined());+ });++ it('returns undefined for null or undefined sections', () => {+ expect(getUrlForAlias(null, 'jelly')).toBeUndefined();+ expect(getUrlForAlias(undefined, 'jelly')).toBeUndefined();+ });+});++describe('ConfigSchema - item alias', () => {+ const aliasSchema = schema.properties.sections.items.properties.items.items.properties.alias;+ const RESERVED = ['404', 'download', 'home', 'login', 'minimal', 'workspace'];++ it('reserves the same words in the schema as the router does at runtime', () => {+ expect([...RESERVED_ALIASES].sort()).toEqual(RESERVED);+ expect([...aliasSchema.not.enum].sort()).toEqual(RESERVED);+ });++ it.each([+ ['jelly', true], ['git-tea', true], ['my_app', true], ['app2', true],+ ['Jelly', false], ['has space', false], ['a/b', false], ['', false],+ ])('accepts %j in the config: %s', (alias, valid) => {+ expect(new RegExp(aliasSchema.pattern).test(alias)).toBe(valid);+ });+});diff --git a/tests/unit/search.test.js b/tests/unit/search.test.jsindex 5d98efdf..6a8f3e54 100644--- a/tests/unit/search.test.js+++ b/tests/unit/search.test.js@@ -58,6 +58,16 @@ describe('Search - searchTiles', () => {expect(searchTiles([t], 'primary')).toHaveLength(1);});+ it('matches an item by its url alias', () => {+ const t = tile({+ title: 'Jellyfin', description: '', provider: '', url: 'https://media.lab', tags: [], alias: 'watchstuff',+ });+ expect(searchTiles([t], 'watchstuff')).toHaveLength(1);+ expect(searchTiles([t], 'WATCHSTUFF')).toHaveLength(1);+ expect(searchTiles([t], 'watchstuff media')).toHaveLength(1);+ expect(searchTiles([{ ...t, alias: undefined }], 'watchstuff')).toHaveLength(0);+ });+it('matches across multiple fields when the query has several words', () => {const t = tile({ title: 'Plex', description: 'Media server', tags: [] });expect(searchTiles([t], 'plex media')).toHaveLength(1);