Writing an app with SvelteKit Part 2

In the last blog post we set up a web application using SvelteKit and fetched some data as a zipball from the Github repository content API.

Now the data should be displayed to the user in an easy to understand and navigate way. It’s currently stored in 6 stores:

• Textures (for base64 encoded image data)
• Patchouli (containing all categories and their corresponding entries)
• Recipes (containing all crafting recipes added by the mod)
• CurrentLanguage (the language being displayed to the user, defaults to english)
• Languages (containing all Ars Nouveau language files)
• MinecraftLanguage (containing the minecraft language file for the currently selected language)

A navigation to display all possible entries is the first thing we’re going to implement and since we don’t want to handle styling and responsive design ourselves we’ll use Skeleton, a UI-framework for Svelte, by following the installation instructions on the Skeleton page.

After that’s done, we can implement our navigation by creating the Navigation.svelte component in src/lib/components/navigation.

<script lang="ts">
    // A store that is automatically updated on navigation to contain the current URL
    import {storeCurrentUrl} from '$lib/stores/uiState.js';
    import {patchouliStore} from '$lib/stores/fileStore';
    // Store that handles the mobile navigation drawer being extended
    import {storeMobileDrawer} from '$lib/stores/uiState';
    import {Divider} from '@brainandbones/skeleton';
    import {afterNavigate} from '$app/navigation';
    import {scrollSelectionIntoView} from "$lib/components/navigation/scrollHelper";
    import Label from "$lib/components/Label.svelte";


    export let embedded: boolean = false;

    // ListItem Click Handler
    function onListItemClick(): void {
        if (!embedded) return;
        //Close the mobile drawer after a navigation click
        storeMobileDrawer.set(false);
    }

    // Sort the categories according to their sortnum key
    $: sortedCategories = Object.values($patchouliStore).sort(
        (categoryA, categoryB) => categoryA.sortnum - categoryB.sortnum
    );
    afterNavigate(() => {
        // For a better UX scroll the navigation entry into view that's currently displayed
        scrollSelectionIntoView();
    })
</script>

<div class="mb-8 {$$props.class || ''}">
    {#each sortedCategories as category, i}
        <!-- Each category will have it's own nav list with it's own entry heading,
             using the handy list-nav class provided by Skeleton -->
        <nav class="list-nav">
            <div class="text-primary-500 font-bold uppercase">
                <!-- Link to the category page -->
                <a href={`/category/${category.id}`} class="no-underline text-primary-500">
                    <!-- The Label component is being used to provide internationalization -->
                    <Label label={category.name}/>
                </a>
            </div>
            <ul>
                {#each Object.entries(category.entries) as [id, entry]}
                    <!-- Each category entry gets rendered as a list item containing a link to the relevant page -->
                    {@const href=`/category/${entry.category}/entry/${id}`}
                    <li>
                        <!-- if the hypertext reference is equal to the current URL the navSelected class will be applied-->
                        <a {href} on:click={onListItemClick} class:navSelected={$storeCurrentUrl === href}>
                            <span class="flex-auto">
                                <Label label={entry.name}/>
                            </span>
                        </a>
                    </li>
                {/each}
            </ul>
        </nav>
        <!-- Every category except the last one will be seperated from the next one by a Divider -->
        {#if i + 1 < sortedCategories.length}
            <Divider class="my-4 opacity-40"/>
        {/if}
    {/each}
</div>


		

Handling internationalization

Usually internationalization (i18n) should be handled by a well tested library like svelte-i18n, svelte-intl-precompile or react-intl for react apps. Since our usecase of multiple dynamic language files is difficult to handle with them, especially with a precompiled solution like svelte-intl-precompile, we’re going to do it by hand with the Label.svelte component, located in src/lib/components.

This also highlights the power of Sveltes Store API!

<script lang="ts">
    // Import the stores necessary for i18n
    import {chosenLanguageStore, languagesStore, minecraftLanguageStore} from "$lib/stores/languageStore";

    // Prop that takes the label key that should be displayed
    export let label: string;

    const getLabel = (
        label: string,
        languages: App.LanguageDictionary,
        chosenLanguage: string,
        minecraftLanguage: App.MinecraftLanguageDictionary
    ): string => {
        // Only try to do i18n when the language stores are loaded
        if (languages && minecraftLanguage) {
            // try to find the i18n text in the AN translations, then in the minecraft translations, use label key if it can't be found
            return languages[chosenLanguage][label] || minecraftLanguage[label] || label;
        } else {
            console.log('Languages not yet loaded');
            return 'unknown label';
        }
    };
</script>
<!-- use automatic store subscribtions and the getLabel function to get i18n that
     automatically updates when the selected language changes -->
{getLabel(label, $languagesStore, $chosenLanguageStore, $minecraftLanguageStore)}


		

Displaying the Navigation

Skeleton doesn’t just provide helpful css class components like the list-nav class we’ve used in the Navigation.svelte component, it also provides an AppShell that gives an application a basic layout. To use it, the div containing your %sveltekit.body% needs to be removed from src/app.html

<!DOCTYPE html>
<html class="dark" lang="en">
   <head>
      <meta charset="utf-8" />
      <link href="%sveltekit.assets%/favicon.png" rel="icon" />
      <meta content="width=device-width" name="viewport" />
      %sveltekit.head%
   </head>
   <body>
      <!-- previously <div>%sveltekit.body%</div> -->
      %sveltekit.body%
   </body>
</html>

html,
body {
   @apply h-screen overflow-hidden;
}

<script lang="ts">
    // import of a custom Skeleton theme
    import '../theme.postcss';
    // import of all the Skeleton classes and tailwind directives
    import '@brainandbones/skeleton/styles/all.css';
    // import of the apps global styles
    import '../app.postcss';
    import {AppShell} from '@brainandbones/skeleton';
    // import of SvelteKits page store to retrieve the current path and make it easily accessible in storeCurrentUrl
    import {page} from '$app/stores';
    // livecycle function to always keep storeCurrentUrl up to date
    import {afterNavigate} from '$app/navigation';
    import {storeCurrentUrl} from '$lib/stores/uiState';
    import NavigationDrawer from '$lib/components/navigation/NavigationDrawer.svelte';
    import Navigation from '$lib/components/navigation/Navigation.svelte';
    import HeaderBar from '$lib/components/HeaderBar.svelte';

    // Lifecycle Events
    afterNavigate(() => {
        // Store current page route URL
        storeCurrentUrl.set($page.url.pathname);
        // Scroll to top of page component
        const elemPage = document.querySelector('#page');
        if (elemPage !== null) {
            elemPage.scrollTop = 0;
        }
    });
</script>

<!-- The Skeleton Drawer used to display the Navigation Menu
     on screens smaller than tailwinds large breakpoint -->
<NavigationDrawer/>

<AppShell>
    <svelte:fragment slot="header">
        <!-- Header with a Darkmode toggle, menu button for screens smaller than the large breakpoint,
             the site title, a language selection and a search box-->
        <HeaderBar/>
    </svelte:fragment>
    <svelte:fragment slot="sidebarLeft">
        <!-- Navigation will be hidden unless the display is larger than tailwinds large breakpoint -->
        <Navigation class="hidden lg:block w-[300px]"/>
    </svelte:fragment>
    <svelte:fragment slot="pageFooter">
        <footer class="flex justify-end mb-1 mr-1 appFooter"><p>Ars Nouveau Wiki</p></footer>
    </svelte:fragment>
    <div class="m-4 page">
        <!-- Page content will be displayed here -->
        <slot/>
    </div>
</AppShell>

Displaying the content

Now that navigation and the overall App layout are handled, the actual content still needs to be displayed! Since the pages for a category and an entry are pretty similar, this is only going to focus on the category page since they are a bit simpler.

First, the directory structure for the path needs to be created: src/routes/category/[category]. A small reminder from the blog post overview of SvelteKit, a folder name in [] brackets is a path parameter. That means that an actual call to this page would look like this /category/getting_started.

To make the category name available to the page component, a +page.ts file needs to be created in the [category] folder:

import type { LoadEvent } from '@sveltejs/kit';

/** @type {import('./$types').PageLoad} */
export async function load({ params }: LoadEvent) {
   return {
      category: params.category
   };
}

This should make the category available in the page data and allows the creation of this +page.svelte component:
<script lang="ts">
    import {patchouliStore} from '$lib/stores/fileStore';
    import Label from "$lib/components/Label.svelte";
    import {getLabelWithCurrentValues} from "$lib/languages";

    /** @type {import('./$types').PageData} */
    export let data: App.PageData;

    // get the category page data that should be displayed from the patchouli store,
    // using the category provided by +page.ts
    $: displayedCategory = $patchouliStore[data?.category];
    // Use a utility function to get the i18n value of the category name for the page title
    $: categoryName = getLabelWithCurrentValues(displayedCategory.name);
</script>

<!-- use svelte:head to set the page title. It's not possible to use the Label component here
     so we have to use a utility funtion to get the translated page title -->
<svelte:head><title>{categoryName}</title></svelte:head>

<h2 class="text-center"><Label label={displayedCategory.name}/></h2>
<div class="flex flex-col justify-start items-center h-full m-4">
    <p><Label label={displayedCategory.description}/></p>
</div>


		

Adding a search function

Since there are a lot of entries in the documentation and the Navigation gets pretty long, it would be great to offer a search functionality. To implement this, fast-fuzzy is used. Fast-fuzzy is an amazing piece of engineering using a modification of the levenshtein distance to implement lightning quick javascript searches.

It’s perfect for this usecase since it can be initialized on the client side once the documentation stores are loaded and the Searcher it exports for searching the same candidates multiple times can just be wrapped in a Svelte Store to be available everywhere.

import { Searcher } from 'fast-fuzzy';
import { getLabelWithCurrentValues } from '$lib/languages';
import { searchStore } from '$lib/stores/searchStore';
import { patchouliStore } from '$lib/stores/fileStore';
import { get } from 'svelte/store';

// concatenates all text contained in text entries into a single string
const getEntryText = (entry: App.PatchouliEntry) => {
   let text = '';
   entry.pages.forEach((page: App.PatchouliPage) => {
      if (page.type === 'patchouli:text' && page.text) {
         text += getLabelWithCurrentValues(page.text);
      }
   });
   return text;
};

// re-initializes the Searcher when the display language is changed
export const updateSearch = () => {
   const patchouli = get(patchouliStore);
   if (patchouli) {
      const entries = Object.values(patchouli)
         .map((category) => category.entries)
         .reduce((previousValue, currentValue) => {
            return { ...previousValue, ...currentValue };
         }, {});
      initializeSearch(patchouli, entries);
   }
};

// Initializes a Searcher and stores it in the searchStore
export const initializeSearch = (
   categories: { [x: string]: App.PatchouliCategory } | undefined,
   entries: { [x: string]: App.PatchouliEntry } | undefined
) => {
   const searchCandidates: Array<App.SearchCandidate> = [];
   if (categories) {
      // Collect all categories into search candidates containing their title, display text
      // and a link to their category page
      Object.values(categories).forEach((category) => {
         searchCandidates.push({
            title: getLabelWithCurrentValues(category.name) || '',
            text: getLabelWithCurrentValues(category.description) || '',
            href: `/category/${category.id}`
         });
      });
   }
   if (entries) {
      // Collect all entries into search candidates containing their title, display text
      // and a link to their entry page
      Object.values(entries).forEach((entry) => {
         searchCandidates.push({
            title: getLabelWithCurrentValues(entry.name) || '',
            text: getEntryText(entry) || '',
            // the entry name is in the form of 'ars_noveau.itemname' and only the itemname is necessary for navigation
            href: `/category/${entry.category}/entry/${entry.name?.split('.').pop()}`
         });
      });
   }

   // Set the searchStore to a new Searcher
   searchStore.set(
      new Searcher(searchCandidates, {
         // The searcher should search the title and text keys, if they exist
         keySelector: (s: App.SearchCandidate) => {
            const items: Array<string> = [];
            if (s.title) {
               items.push(s.title);
            }
            if (s.text) {
               items.push(s.text);
            }
            return items;
         },
         // The whole SearchCandidate should be returned on matches so that the Link can be used in the display
         returnMatchData: true
      })
   );
};

Now that the Searcher is set up, it needs to be displayed in a Search Component:
<script lang="ts">
    import {searchStore} from "$lib/stores/searchStore";
    import Search from "$lib/components/Search/Search.svelte";
    import Dropdown from "$lib/components/Search/Dropdown.svelte";

    export let mobile = false;

    let value: string;
    let searchElement: HTMLElement;

    // Search results should only be shown while the search input has focus
    let focus = false;
    const onFocus = () => {
        focus = true;
    }
    const onBlur = () => {
        focus = false;
    }

    // Get the search results for the currently entered search term
    const getSearchResults = (value?: string) => {
        // there needs to be a searcher with a search method and at least 3 characters in the input to do a search
        if ($searchStore && $searchStore.search && value && value.length > 2) {
            return $searchStore.search(value)
        } else {
            return [];
        }
    }

    // show only the first 5 items, since the others are probably not relevant
    $: results = getSearchResults(value).slice(0, 5).map(foundValue => foundValue.item)
</script>

<div
        aria-controls="search-dropdown"
        aria-expanded={focus && results}
        aria-haspopup="listbox"
        aria-owns="listbox"
        bind:this={searchElement}
        class:dropdown={results.length > 0}
        data-svelte-typeahead
        role="combobox"
>
    <!-- bind the focus methods to control the dropdown display -->
    <Search bind:value on:blur={onBlur} on:focus={onFocus}/>
    <!-- Dropdown should only be open when the Search input is focused and there are results -->
    <Dropdown id="search-dropdown" open={focus && !!results} openLeft={mobile} parentElement={searchElement}>
        <nav class="list-nav" slot="content">
            <ul>
                {#each results as result}
                    <li>
                        <!-- use the href prepared in each SearchCandidate -->
                        <a href={result.href}>
                            <span class="flex-auto">
                                {result.title}
                            </span>
                        </a>
                    </li>
                {/each}
            </ul>
        </nav>
    </Dropdown>
</div>


		

Take a look at the final result on https://arsnouveau.wiki or view the sourcecode on github, or continue reading in part 3 to learn how to deploy the app.