DEV Community: Saje

I Tried Creating An SPA With JavaScript and HTML 🤯

Saje — Mon, 07 Aug 2023 11:38:46 +0000

Due to the popularity of several modern frontend frameworks, many frontend developers are gradually losing touch of what it's like to build an entire application without using any framework or library.
Based on my previous article, I decided to try out what it would be like to create a Single Page Application (SPA) using only JavaScript and custom elements. So I ended up creating a "mini" ecommerce store.
Even though I couldn't complete it, it provided a few insights which I found interesting.

Before we continue, you can check out the web page here or check out the repo here.

A single-page application (SPA) is a web application or website that interacts with the user by dynamically rewriting the current web page with new data from the web server, instead of the default method of a web browser loading entire new pages.

One popular concept in SPAs is Component Driven Development, which is basically an approach of separating your code into smaller reusable components that deliver a single/simple functionality.
After publishing an article on custom elements, which provided a way to create reusable components using vanilla JavaScript; out of curiosity, I've been thinking and enquiring how far we can push custom elements, or more specifically, how much can we do in JavaScript without our favorite frameworks/libraries, perhaps using just custom elements? When I asked this on social media, some of the reactions were quite funny but they sparked some interest in me. I decided to sacrifice some time to choose stress (as one person described it), and find out how much stress it could cause. Turns out, it is quite a lot of stress - but not as much as I had imagined.
There are three major concepts that distinguish an SPA:

Structure: by structure, I mean, the folder/code structure, the layout, components, etc.
Routing: this, of course is very crucial since routing is handled in the frontend
State management: even though this is not unique to SPAs alone, state management is very crucial in an SPA

Based on these three concepts, I've split this article into three sections, to discuss each of these topics based on how I approached them in my little adventure.

Folder Structure

This aspect was perhaps the simplest aspect of the project - thanks to custom elements. As I explained in the article on custom elements, you can easily create reusable html components with JavaScript. So, as you might expect, I made a deliberate effort to make the folder structure look similar to what you'd have in a React application. Here's a screenshot of the expanded folder structure:

Yes, quite a lot of files, I know - some of them aren't even being used at the moment - but this was a somewhat sarcastic mimicry of an SPA folder structure 😅
And if you're curious how the snippet of the components looks, here's the navbar:

Routing

Basic routing in an SPA is quite straightforward and relatively easy to implement. The way React Router works under the hood, for example, is by generating a routes object which contains all the defined routes, and then throw a 404 error when a user tries to access a route that is not among the predefined routes.
To mimic this, I just created a routes object that looks like this:

// routes.js
// all available routes
const routes = {
    '?about': () => {
        return about()
    },

    '?home': function () {
        return product()
    },

    '': async () => {
        return await home('')
    },
    404: () => {
        error404()
    },
}

export default routes

It looks a bit messy I know, but there's a reason for that...

In the snippet above, I created an object with the route as the key, and a function which returns another function as the value. The reason for using Higher Order Functions is because I wanted to be able to pass arguments to the template function (to create 'dynamic' routes), and this seemed like the easiest approach.
Notice that I used search params (?), instead of regular routing (/) - more on this soon.

// app.js
// import the routes object
import routes from './api/routes.js'
// Main container
const main = document.querySelector('.root')

// switch route without reloading the page (default behavior of links)
function handleRoute(event) {
    event = event || window.event
    event.preventDefault()
    window.history.pushState({}, '', event.target.href)

    handleLocation()
}
// check if the current path (url) is part of the preconfigured routes, else display the 404 page
async function handleLocation() {
    const path = window.location.search
    const templateFunc = routes[path] || routes[404]
    const html = await templateFunc()

    main.innerHTML = html
}
// make handleRoute() a method on the window object
window.handleRoute = handleRoute
// when user clicks back/forward, trigger the location function
window.onpopstate = handleLocation
// call the location function on first page load
handleLocation()
// export the function so it can be used within custom elements
export { handleRoute }

The comments in the snippets above are self-explanatory; first we import the routes object, then create a handleRoute function which we'll add to our links for routing across pages. The function takes an event argument (which is triggered when a user clicks a link), prevents the default behavior of the event (stop the page from reloading), and calls history.pushstate to 'push' the user to the URL specified in the link, after which we call the function: handleLocation.
handlelocation is for getting the current URL the user is on (in this case the search params - which was what we used in the routes object) using window.location.search, check if that route is in the routes object. If it is, we return the contents of the route, else we return the 404 route, and then finally call the function returned by the route and append its content to the main page wrapper.
After configuring our routes, we can now create our "soft links" to link different pages without reloading the browser:

<button class="nav-btn"><a href="/" onclick="handleRoute()">Home</a></button>

Different ways of doing the same thing

There are different ways to implement routing in an SPA. Let's look at three of these:

Regular Routes (/): This is the standard approach often used in routing libraries, like React Router, etc. This method allows you to create routes that appear as separate pages, using forward slashes (/). To use this method, we'd need to modify the handleLocation function to use window.location.pathname instead of window.location.search,

// app.js
// check if the current path (url) is part of the preconfigured routes, else display the 404 page
async function handleLocation() {
    const path = window.location.pathname
    const templateFunc = routes[path] || routes[404]
    const html = await templateFunc()

    main.innerHTML = html
}

Then modify the routes object:

// routes.js
// all available routes
const routes = {
    '/about': () => {
        return about()
    },

    '/home': function () {
        return product()
    },

    '/': async () => {
        return await home('')
    },
    404: () => {
        error404()
    },
}

export default routes

However, when using this method, you also need to configure your server to return a single HTML page for all routes entered by the user. Without doing this (since the HTML is always parsed before the JavaScript), the browser throws an error when it tries to access an HTML file for a route that doesn't match an existing HTML file. Of course if you're interested, you can easily use Express or any similar tool to implement this.

Query Params: This is the method I used above so I think you already get the idea. The main advantage of this (which made me choose it) of course, is that the browser already considers a URL with a query parameter as part of the base URL, so everything works "as a single page" without requiring any server-side configuration.
Hash URL: This - as you'd expect, is similar to using query parameters. The only difference is that it uses the hashchange event instate of the popstate event used with query parameters. You can check out this video for more on this:

What about dynamic routes?

The first approach that crossed my mind for creating dynamic routes was to create a function that accepts a path and template (in this case, a function that returns a template), and appends it to the routes object.


// programmatically create a new route and append it to the routes object
async function createRoute(path, template) {
    routes[path] = await template
}

Unfortunately this didn't work, of which I can't yet fully visualize why (perhaps you could help).
Because of this, I had to proceed with my initial idea of passing props to the template function for the route. The complete route object ended up looking like this:

// route.js
// all available routes
const routes = {
    '?about': () => {
        return about()
    },
    '?home': function () {
        return product()
    },
    '': async () => {
        return await home('')
    },
    '?category=jewelery': async () => {
        return await home('jewelery')
    },
    '?category=electronics': async () => {
        return await home('electronics')
    },
    '?category=men%27s%20clothing': async () => {
        return await home("men's clothing")
    },
    '?category=women%27s%20clothing': async () => {
        return await home("women's clothing")
    },
    404: () => {
        error404()
    },
}

Note: I used encodeURI to format the prop before appending it to endpoint for fetching the products.

State Management

State management is arguably the most crucial, mind-boggling and perhaps most difficult aspect of frontend development today - especially in an SPA; this difficulty is escalated when you try to implement the same functionality without using any specialized tool (a state management library/package).
While it's relatively easy to fire events with immediate side-effects within a component, sharing and maintaining state in real-time across components is almost a nightmare if you're trying to re-invent the wheel. For example, my initial plan for the products category was to create a single route and then fetch and display the content based on selected category. To achieve this, I added an event listener in the connectedCallback method of the custom element to fetch and display the products based on a selected category, and then use recursion to re-render the component in order to reflect the state change:

// home.js
// event listener to render a selected product category
connectedCallback() {
    this.shadowRoot.querySelectorAll('.category')
    .forEach((navLink) => navLink.addEventListener('click', async (e) => {
    let selectedCategory = e.target.textContent
    // update the selected product category
    category = await fetchProductCategory(selectedCategory)
    // call the home function to cause a re-render
    home()
}))
}

However, a weird behavior which I noticed was that, even the component was re-rendered, it still maintained the same stale data - basically, showing the default category instead of the new one. This led to the messy nature of the routes object as stated earlier.
Admittedly, there might be other better alternatives or methods to effectively manage state in a Single Page Application using plain old JavaScript, but I'm yet to come across any. In my research, I came across several speculative implementation of the useState hook like this one, but none of them was able to solve the challenge; and so with a little hesitation, I gave up.

Conclusion

Yes, it is technically possible to create single-page applications using web components. However, one of the foundational issues with this method —which inherently applies to all SPAs— is the amount of JavaScript shipped to the browser. The total unminified size of JavaScript in the above project is about 2MB, which is quite A LOT of JavaScript for such a small app; of course, using a module bundler would significantly reduce this size, however, this doesn't override the performance impact experienced by the user on initial load.

The purpose of this little challenge —and even this article— is not necessarily to encourage developers to stop using frameworks or libraries, the main reason why these technologies were invented in the first place was to solve different challenges in the software development process; so, most of them are definitely useful and important. However, my perception is that developers should be curious enough to truly understand how these tools work and the tradeoffs involved when using them.
I hope this was a fun read for you, and don't forget to check out the main article before this on custom elements.

Create Reusable HTML Components Using Only JavaScript

Saje — Sat, 29 Jul 2023 12:18:10 +0000

With the advent of a plethora of frontend frameworks and libraries, many developers are gradually losing touch with a lot of the amazing features that are baked into JavaScript. While these frameworks and libraries simplify a lot of the development process, in some cases, using them can be overkill.

One of the major challenges of using HTML is the unnecessary repetitiveness it introduces to the codebase. However, JavaScript provides several features that provide a workaround for this repetitiveness. One of these features is the newly introduced customElements object.

In this article, we dive into what custom elements are, how to create them using customElements, how to create more flexible and reusable custom components using the slot attribute, styling and adding event listeners to a custom element, and the advantages and drawbacks of using custom elements.

An Introduction to Web Components

If you are familiar with React, Vue, or any similar frontend library/framework, you have probably come across, or even worked with components that use a syntax similar to this:

<MyComponent />

These components provide a way to encapsulate and split your code into different sections or files based on their functionality, making it very easy to write code once and reuse it as many times as necessary. But what if I told you that there is a way to achieve something very similar to this using just HTML and vanilla JavaScript? Custom elements are a part of the newly introduced Web Components API. They provide a way to define and use custom HTML tags with custom functionalities, and reuse those tags/elements as many times as you want.

Custom Elements

Custom elements incorporate three different features that are intertwined between HTML and JavaScript. These are:

HTML templates
Shadow DOM
CustomElements (an instance of CustomElementRegistry)

Templates

The HTML template tag is used for creating an HTML markup that is not displayed immediately but is rather intended to be rendered later using JavaScript.

<template>
    <section>
        <h2>HTML Templates</h2>
        <p>everything in a template tag is not displayed on the browser.</p>
    </section>
</template>

We can use JavaScript to display the contents of this template in the browser by cloning its content and appending it to an element in the DOM.

const template = document.querySelector('template')
const clone = template.content.cloneNode(true)

document.querySelector('main').appendChild(template)

In the example above, we first select the content of the template, then clone its content by referencing content.cloneNode(), the Boolean flag (true) is to specify that it should be a deep copy.

Shadow DOM

If you've been using React for a while, or know how it works, you might have heard about the Shadow DOM. This works just like the regular DOM, in the sense that it represents a tree-like structure of the relationship between HTML elements in the browser. The unique feature of the shadow DOM is that it allows hidden DOM trees to be attached to elements in the regular DOM tree.

// create a div element
const htmlSection = document.createElement('div')
// create HTML using template literals
const content = `
<h3>This is a heading</h3>
<p>this content is meant to be added to the shadow DOM</p>
`
htmlSection.innerHTML = content
// select the element with a class called root
const root = document.querySelector('.root')
// attach a shadow DOM to the selected element
root.attachShadow({ mode: 'open' })
// append the html element to the shadow DOM
root.shadowRoot.appendChild(htmlSection)

CustomElement

customElementsRegistry or simply customElements is a JavaScript object that allows you to define a customized HTML element/tag, along with its content and functionality, and use the element in your HTML as a regular HTML element. This element would usually be a block of code that can be used multiple times in your HTML.

The syntax for creating a custom element is as follows:

customElements.define('element-name', customClass )

In the code snippet above,

element-name represents the name of the custom element. This name can be anything, as long as it follows the naming convention, which we will talk about soon.
customClass represents a class object which usually extends the HTMLElement class, and also contains the functionality and content of the custom element.

Now let's dive into some examples of how to create and use custom elements.

Basic usage

The simplest way to create a custom element is as follows:

class anyName extends HTMLElement {}
customElements.define('custom-element', anyName)

In this example, we created a JavaScript class called anyName which inherits HTMLElement object, then we used customElements to define a custom element, custom-element which is the name we have chosen to represent our custom tag, and then passed the class as the second argument.

After defining the custom element, you can then use it in your HTML as follows:

<custom-element>Some text here</custom-element>

Practical example

The previous example is probably not that useful, as you can achieve the same functionality—maybe even more—by using any native HTML tag. However, custom elements are more useful for creating reusable components, like navbars, footers, etc. Here's an example of a navbar component:

// create an HTML template element
const template = document.createElement('template')

template.innerHTML = `
<nav>
    <div>
        <img src="./assets/logo.png" alt="logo">
    </div>
    <ul>
        <li><a href="/">Home</a></li>
        <li><a href="/about">About</a></li>
        <li><a href="/services">Services</a></li>
        <li><a href="/contact">Contact</a></li>
    </ul>
</nav>
`
// create a navBar class, and clone the content of the template into it
class navBar extends HTMLElement {
    constructor() {
        super()
        this.attachShadow({ mode: 'open' })
        this.shadowRoot.appendChild(template.content.cloneNode(true))
    }
}
// define a custom element called 'nav-bar' using the navBar class
customElements.define('nav-bar', navBar)

The above code creates a custom navbar component that we can use in our HTML document by just adding <nav-bar></nav-bar> to the markup.

Extending functionality with slots

Oftentimes, when working with components, you might want to be able to add extra content or functionality that is unique to the current page or section you are using the component. A good instance of this is when creating modals or popups. Modals usually have a basic layout and structure, the difference is usually in the content. By using a slot in custom elements, you can create a component that is able to accept extra or unique content.

Let's extend the functionality of our navbar component by adding a section that displays a login button if the user is not logged in, but displays a logout button if the user is logged in:

// adding slots to a custom element
template.innerHTML = `
<nav>
    <div>
        <img src="./assets/logo.png" alt="logo">
    </div>
    <ul>
        <li><a href="/">Home</a></li>
        <li><a href="/about">About</a></li>
        <li><a href="/services">Services</a></li>
        <li><a href="/contact">Contact</a></li>
    </ul>
    
    <slot name="auth">
        <button>Login</button>
    </slot
</nav>
`

By default, when we add the custom component to our markup, it shows the login button. However, we can replace this slot element with any HTML content of our choice (in this case, a logout button):

// using slots to replace content defined in a custom element
<nav-bar>
    <div slot="auth">
        <button>Logout</button>
    </div>
</nav-bar>

Some things to keep in mind when using slots:

You can add as many slots as you want in your custom components, and reference them in your markup.
Slots work like IDs in HTML markup; each slot name within a component must be unique.
The content being used to replace the slot can also be anything, as long as the name of the slot corresponds.
Slots have a default display value of contents which might make the elements behave differently from what you expect. If you want the slot to display as a block element, you have to style it as such (using display: block; or display: inline-block;).

Styling a custom element

Styling a custom element works a bit differently from styling a regular HTML document, as it does not support external CSS. The reason for this behavior is primarily because the shadow DOM encapsulates and separates the content within it from the main DOM.

The only way to style a custom element is by writing the stylesheet within the template; this can be via a style tag, Bootstrap, inline styles, or any method that involves writing the styles directly in the template.

// Styling a custom element
template.innerHTML = `
<style>
.navbar {
    height: 4rem;
    width: 100%;
    display: flex;
    align-items: center;
    padding: 1rem 2rem;
}

.navbar__logo {
    height: 100%;
}

.brand {
    height: 100%;
    object-fit: contain;
}

.navlink__container {
    display: flex;
    align-items: center;
    gap: 2rem;
    margin-left: auto;
}

.navlink {
    list-style: none;
    font-size: 1.6rem;
}

.navlink a {
    text-decoration: none;
    color: inherit;
}
</style>
<nav class="navbar">
    <div class="navbar__logo">
        <img src="./assets/logo.png" class="brand" alt="logo">
    </div>
    <ul class="navlink__container">
        <li class="navlink"><a href="/">Home</a></li>
        <li class="navlink"><a href="/about">About</a></li>
        <li class="navlink"><a href="/services">Services</a></li>
        <li class="navlink"><a href="/contact">Contact</a></li>
    </ul>
    
    <slot name="auth">
        <button class="primary-btn">Login</button>
    </slot
</nav>
`

However, slots support external styles, for example, we can style the auth slot via a CSS file:

<!-- styling a slot -->
<nav-bar>
    <div slot="auth" class="auth__wrapper">
        <button>Logout</button>
    </div>
</nav-bar>

Adding Event Handlers to a Custom Element

Adding event listeners to a custom element also follows a similar pattern with adding styles as we discussed earlier: all event listeners must be defined as a method within the class.

You can add event listeners or manipulate child elements within the custom element by defining the event handler in a connectedCallback method,

// create a navBar class, and clone the content of the template into it
class navBar extends HTMLElement {
    constructor() {
        super()
        this.attachShadow({ mode: 'open' })
        this.shadowRoot.appendChild(template.content.cloneNode(true))
    }
    
// adding event listeners to child elements within a custom element
    connectedCallback() {
        this.shadowRoot.querySelector('.primary-btn').addEventListener('click', (e) => {
            console.log('shadow event triggered!')
        })
    }
}

In the above example, we defined a connectedCallback method in the navBar class. We then proceeded to add an event listener to the login button; therefore when the button is clicked, we see shadow event triggered! in the console.

Some Interesting Gotchas About Custom Elements

While testing different ways to work with custom elements, I found a couple of things I believe you will find interesting. Here are some of them:

You can append a custom element using JavaScript via this syntax:

container.innerHTML = `<custom-element></custom-element>`

You can also define and use custom elements without using the shadow DOM:

const content = `
<h3>This is a heading</h3>
<p>Hello world from here</p>
<p>this content is meant to be added to the Custom Element</p>
<button>Hello There</button>
`
class element extends HTMLElement {
    constructor() {
        super()
        this.innerHTML = content
    }
}

The benefit of using this method is that the component is treated as part of the main DOM tree, therefore:

it can be styled using a separate CSS file
Event listeners for child elements can be defined outside the class
You can either add the event listener in the connectedCallback or define it outside the class.

The drawback of this method is that slots no longer work, which means that you can no longer add modifiable content within the custom component.

Slots can have event listeners both in the connectedCallback method and outside the class object, but only if the slot is used in the markup. this is because a slot and its replacement are treated as separate elements. When you add event listeners like this, the one defined outside the class is triggered first.

Rules For Naming Custom Elements

When creating custom elements, there are certain naming conventions/rules that must be followed, otherwise, it would result in an error:

It must contain a hyphen
It must not contain any ASCII uppercase letters
It must start with an alphabet
It cannot be any of these reserved words:

annotation-xml, font-face-format,
color-profile, font-face-name,
font-face, missing-glyph,
font-face-src, font-face-uri

Asides from lowercase alphabets and hyphens, a name can also include a dot ("."), underscore ("_"), and a few other special characters.

Advantages Of Using Custom Elements

So far, we've discussed quite a lot about custom elements; now let's talk about some advantages of using them. There are several advantages of using custom elements, below are some of them:

Reusability: Custom elements promote code reusability by encapsulating specific functionalities into self-contained components. Once defined, they can easily be used throughout the application or even across different projects, leading to more efficient development and maintenance.
Framework Agnostic: They work natively in modern browsers, making them independent of any specific JavaScript framework or library. This flexibility makes it easy to use custom elements alongside other frameworks or even without any framework, depending on project requirements.
Vendor Independence: Using custom elements avoids the vendor lock-in often associated with using specific frameworks. This independence ensures that the application remains viable even if the preferred framework becomes less popular or maintained in the future.
Forward Compatibility: As custom elements follow web standards, they are designed to be future-proof. Browsers will continue to support them and adhere to the specifications, reducing the risk of breaking changes in the future.
Modularity: This is usually one of the major reasons a lot of companies/individuals use component-based frameworks. By breaking down complex user interfaces into smaller custom elements, developers can create a modular architecture. This approach simplifies the development process, as each element can be developed and tested independently before being combined into larger components or applications.

Disadvantages And Drawbacks Of Custom Elements

Along with their many advantages, custom elements also have some disadvantages and drawbacks which you should consider before using them:

Lack of Built-in Features: Unlike some frameworks, custom elements do not come with built-in features and utilities like state management, routing, or form validation. You may need to implement or integrate these functionalities separately, which can be more time-consuming.
Event Handling Complexities: Managing event listeners and propagating events among custom elements can be more complex than in some frameworks, where event handling is abstracted and streamlined.
Browser Support: While modern browsers have good support for custom elements, some older browsers may lack full support or require polyfills to function correctly. This can add complexity to the development process, especially when considering the need for backward compatibility.

Conclusion

This article was meant to give you a basic overview of what is possible with just HTML and vanilla JavaScript. Custom elements might just be a step in the direction of framework-agnostic, component-based frontend development. We might even be able to create Single Page Applications with just HTML and vanilla JavaScript! However, for developers to fully adopt it, a lot of improvement is required to standardize, and make it more developer-friendly.