VueJS

Getting started with Vitepress

Dec 21, 2023

12 min read

Getting started with Vitepress to create your blog site

Have you heard about Vitepress, but you have not checked it out at it yet? Well, in this article, we are going to cover the basic setup and share what all the fuss about this new fantastic static site generator.

If you are looking for something that would allow you to quickly create a static site with Markdown support, search, Light/Dark theme, advertisement, navigation, and much more, then Vitepress is what you are looking for.

Suppose you want some proof of Vitepress's power without having to invest any further time, I suggest you head over to the main Vitepress site (vitepress.dev) and experience what Vitepress can do, as the official site is built on Vitepress!

What is Vitepress

Vitepress is a powerful Static Site Generator powered by Vite mainly used for Documentation and Blogs with the default theme, and open to customization to be used for anything you may need it to with custom themes and theme overrides.. Vitepress power comes from its low learning curve, powerful configuration settings, and the ability to easily customize it.

For example, internationalization is built-in, Theme toggling is built-in and even full-site searches require a single line in the config to be set up.

What makes Vitepress so powerful is its extensive configuration and the fact that it can be customized by overriding the existing theme, creating your theme, or simply enhancing pages with custom Vue code.

Prerequisites

To successfully run the following demo, you will need:

Node.js version 18 or higher.
Terminal for accessing VitePress via its command line interface (CLI).
Text Editor with Markdown syntax support.
VSCode is recommended, along with the official Vue extension.

Create your project

To create the project, we will follow the steps shown in the official Getting Started guide.

If you want to set up a Vitepress project quickly, run the following steps:

Create a new folder mkdir vitepress-tutorial
Access the folder cd vitepress-tutorial
Install Vitepress npm add -D vitepress
Run the Wizard npx vitepress init
Answer the questions:
- Where should VitePress initialize the config?
- Site title
- Site Description
- Theme
- Do you want Typescript support?
run npm run docs:dev
Enjoy your site.

After you run the above steps, your Vitepress will be ready and running as shown below

What is available out of the box

The site comes fully set up with enough to get you started. Let's see what features are available within the software:

Navbar: The site comes with a Navbar that already includes links to our blog pages
Light/Dark theme: Out of the box theming
Home page: Basic Homepage layout
Blogs: Two different blog posts with sidebar navigation

All of the above is available with just 4 files! Let's move forward and see how to customize our app.

Overriding the homepage

It is time to modify our site by accessing its folders. What you will probably notice when opening the site, is that Vitepress follows a very simple file structure, in fact, a new installation just includes 4 extra files on top of the expected package.json and node_modules.

Let's update our homepage to make it more unique. Because Vitepress follows a "file-system based router" we can find this file within the root of the project within a file called index.md. This file will be accessible at "/" or "/index.html" of your site.

The content of the file is the following:

---
# https://vitepress.dev/reference/default-theme-home-page
layout: home

hero:
 name: "Vitepress tutorial"
 text: "A VitePress Site"
 tagline: My great project tagline
 actions:
   - theme: brand
     text: Markdown Examples
     link: /markdown-examples
   - theme: alt
     text: API Examples
     link: /api-examples

features:
 - title: Feature A
   details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
 - title: Feature B
   details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
 - title: Feature C
   details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
---

As you can see, the file has no code in it, and it is just driven by configuration, or more specifically in this case Markdown frontmatter, that is a set of configurations accepted by markdown files that help you set up your options such as title, description, og:image. We will describe frontmatter in more detail later in the article.

Before we jump into modifying the configuration of the file, you should know that Vitepress has a very extensive and well-detailed documentation site where you can find help if you are stuck or would like to learn more. In this case, we are overriding the "home" page, so the documentation can be found here: Home Page Default Theme configuration.

If you read the current file within the homepage, you will notice that it defines a "layout" of "home". This layout displays a main header with CTAs and a set of feature blocks.

There are three different layouts available in the Default theme: "home", "doc" and "page".

The title and description have already been set from the information we provided from the installation wizard. But the rest is just a basic boiler template. Let's see what we can change:

Add a hero image. This image can either be externally sourced or saved within the repository.

hero:
 name: "Vitepress tutorial"
 text: "A VitePress Site"
 tagline: My great project tagline
 image:
   src: 'assets/logo.png'
   alt: 'My logo'

Update the action buttons.

 actions:
   - theme: brand
     text: First Blog
     link: /first
   - theme: alt
     text: Thisdot.co
     link: https://thisdot.co

As shown above, Action buttons have two themes "brand" or "alt" and can accept internal or external links.

Vitepress is clever enough to set the external links to open in a new tab and set the rel="noreferrer".

Change the feature blocks:

Features blocks are great for engaging with the user and telling them what makes your site special. This accepts an icon and some text, so let's change ours with the following:

features:
 - icon: 🏚️
   title: Your Documentation house
   details: This is the house of your documentation
 - icon:
     src: https://emojipedia.org/house
   title: This is the logo
   details: Nothing else to say

The homepage is now completed and updated and it should look like this: Vitepress homepage with redesign

Please note that what we did on the homepage is just changing the markdown front matter of the "home" layout. What this means is that if you want to, you can easily customise the page further by either adding more blocks to the layout file or actually by writing and styling the rest of the page as normal.

Site configuration

In this step, we are going learn about the main site configuration and how we can use it to customize our site.

The configuration file can be found in the .vitepress folder under the name of "config.mjs".

Just like the homepage layout, the configuration used in the preset file is self-explanatory:

import { defineConfig } from 'vitepress'

// https://vitepress.dev/reference/site-config
export default defineConfig({
 title: "Vitepress tutorial",
 description: "A VitePress Site",
 themeConfig: {
   // https://vitepress.dev/reference/default-theme-config
   nav: [
     { text: 'Home', link: '/' },
     { text: 'Examples', link: '/markdown-examples' }
   ],

   sidebar: [
     {
       text: 'Examples',
       items: [
         { text: 'Markdown Examples', link: '/markdown-examples' },
         { text: 'Runtime API Examples', link: '/api-examples' }
       ]
     }
   ],

   socialLinks: [
     { icon: 'github', link: 'https://github.com/vuejs/vitepress' }
   ]
 }
})

This file is very important and you are probably going to have it open at all times as it is going to be responsible for the layout of the sidebar navigations of your site.

In this section, we are going to learn how to use the Vitepress configuration file to achieve the following:

Modify the sidebar navigation
Enable Search
Add Favicon to your site

The sidebar is the component displayed on the left-hand side of the blog pages. This is not automatically generated, but it is manually set in this file.

You can have more than one navigation, so, for example, you could specify sidebar navigation that shows in pages that have "/blog/" within their path and another one for all markdown pages that have "/tutorials/".

Let's see how to implement this:

{
   sidebar: {
     '/blog/': [
       {
         text: 'Blog',
         items: [
           { text: 'Index', link: '/blog/' },
           { text: 'One', link: '/blog/one' }
         ]
       }
     ],

     '/tutorials/': [
       {
         text: 'Tutorial',
         items: [
           { text: 'Index', link: '/tutorials/' },
           { text: 'Two', link: '/tutorials/two' }
         ]
       }
     ]
   },
}

With the above code, there will be 2 different sidebars. One will just show if the URL includes "/blog" and the other will be displayed if the path includes "tutorials".

Clicking on the above items will give a 404 error as we do not have any pages in that specific location. Still, we can easily fix the issue by creating the two folders "blog" and "tutorial" and creating the required files within these folders in our case are "index.md" and "one.md" for the blog and "index.md" and "two.md" for tutorials.

The sidebar has further settings like the ability to create a nested tree or create collapsable menus. You can learn more by checking out the the official documentation on default theme sidebar.

Enable Search

No documentation or blog site is complete until a search is fully implemented on it. Luckily for us, enabling a site-wide search is extremely simple with Vitepress.

Vitepress supports two different search types: a full-text search using minisearch and Algolia based search.

In this tutorial, we are going to enable the full-text search. This is fully built-in and requires no external accounts.

To enable search, we need to add a "Search" parameter within our themeConfig and set the provider to "local". We can add this right below the socialLinks.

   socialLinks: [
     { icon: 'github', link: 'https://github.com/vuejs/vitepress' }
   ],
   search: {
     provider: 'local'
   }
 }

With just a simple config change, our site will now have a full site search working as shown below: Full site search of Vitepress

The official search documentation has further information about the look and functionality of the search.

Add Favicon to your site

Even if the site configuration is very extensive, there are times when you will need to add something within the site-wise page that is not available.

In this section we are going to learn how to add specific attributes to the <head> of our site, and specifically how to add a favicon.

To add custom values to the head, we are going to use the "head" properties available with the Vitepress configuration.

The "head" configuration is an array that accepts an array with the element type (eg. link, script, meta), and an object including all the attributes for that specific element.

So for example to replicate the following HTML:

<link rel="icon" href="/image/favicon.ico"/>

we would define the following head config:

 head: [
   [ 'link', { rel: 'icon', href: '/images/favicon.ico' } ],
 ]

We can use this technique to set up metadata and even load fonts or Google Analytics. More info in the site-config head

Writing your post

In the last section of this article, we are going to learn how to actually write a blog post and also learn how to customize the pages with JS and styles.

Writing your first page

In the previous section, we created a couple of markdown files, but they are currently empty. Let's see how to create beautiful documentation using the built-in feature of Vitepress.

In this section, we are going to work on the file stored in /blog/index.md. This file can be accessed in your browser by accessing "http://localhost:5174/blog/index.html".

Blog Frontmatter

Every file needs to have a frontmatter defined. This is used to define basic information on the page, such as the title, description, and more.

For best SEO results, it is best practice to always define a title and description for a new page. We can do this by adding the following code at the top of our file:

---
title: My Blog post title
description: My unique description
---

Frontmatter in Markdown files are delimited by the "---". In the above code, we set our title and description.

Vitepress frontmatter supports further config like lastUpdates, sidebar, outline, and more. You can find info on the frontmatter-config documentation.

Frontmatter has some global configuration, such as title and description, but also "layout specific" settings that are just available on specific layouts. This is clearly explained in the documentation.

Blog Markdown

Now that our post frontmatter is set, it is time to write the content of it. This is done using a very extensive markdown engine.

Let's start with the basics and write a heading with some text and a link as shown below:

## My heading one

My text

[link](thisdot.co)

After saving, our development environment will show the following results:

Let's add a couple of headings and a table of contents to our document using [[toc]] to the top of our page:

My Table of Contents:
[[toc]]

## first heading
My text

[link](thisdot.co)

### inner heading 3

## second heading
My text

[link](thisdot.co)

The above will produce an unordered list with all our links. Table of content

The last feature that I want to share about the Vitepress markdown engine is the code editors. The markdown engine used in Vitepress offers extensive features when it comes to code rendering.

Features available are "code highlight", "code focus", external snippets loading and much more. The full list of features can be found in the markdown docs.

Let's implement a simple code snippet with a line of code focused. This can be achieved by adding "// [!code focus]" at the end of our row. Let's give it a try:

const myNewFunction = () => {
   externalApi();
   const newCode = true; // [!code focus]
   return newCode;
}

The output of this will be:

Customize your blog with Vue

In this last section, we will learn how to customize our code by adding js logic, style, and external components.

Before we begin, it is important to understand that when you use the default template of Vitepress, your pages are going to be rendered with Vue.

This means that we can expand the individual page's functionality by rendering other vue components and/or writing logic and styles directly on the page.

To better explain this concept, we are going to create a team page. Create a file called team.md within the root of our repository.

This file will be accessible on "http://localhost:5174/team.html" and will be just a simple Markdown file.

First, we set up the frontmatter as before. In this case, we have to specify an additional config called "layout". This will ensure the page has no style or components loaded such as sidebar or aside.

---
layout: page
title: My team page
---

Then we will have to create our team variable, just like a normal Vue component; we can do so by defining a script setup tag and defining the constant there.

<script setup>
import {
 VPTeamMembers
} from 'vitepress/theme'

const members = [
 {
   avatar: 'assets/logo.png',
   name: 'Simone',
   title: 'Software Architect',
   links: [
     { icon: 'github', link: 'https://github.com/#' },
     { icon: 'Twitter', link: 'https://twitter.com/#' }
   ]
 },
 {
   avatar: 'assets/logo.png',
   name: "This Dot",
   title: "Software Company"
 }
]
</script>

In the above code, we have imported the VPTeamMembers component from the vitepress/theme and defined an array of members. The values used in the members array are hardcoded, but as you may expect, you can load this information directly from an API.

We now have to use the "members" variable within our file. We can do so by writing normal JavaScript. The markdown file will evaluate the JavaScript and render it, so in the following example it will render a specific component.

## Our Team

Say hello to our awesome team.
<VPTeamMembers size="small" :members="members" />

Before we move forward we need to define some style as the page is unstyled since we have loaded the layout of "page".

Just like we did with the <script> tag, we can load a <style> tag and update our styles:

<style>
h1 {
   color: red;
}
h1, p {
   text-align: center;
}
</style>

The completed file will look like this:

---
layout: page
title: My team page
---
<script setup>
import {
 VPTeamPage,
 VPTeamPageTitle,
 VPTeamMembers
} from 'vitepress/theme'

const members = [
 {
   avatar: 'assets/logo.png',
   name: 'Simone',
   title: 'Software Architect',
   links: [
     { icon: 'github', link: 'https://github.com/#' },
     { icon: 'Twitter', link: 'https://twitter.com/#' }
   ]
 },
 {
   avatar: 'assets/logo.png',
   name: "This Dot",
   title: "Software Company"
 }
]
</script>

<style>
h2 {
   color: red;
}
h2, p {
   text-align: center;
}
</style>
## Our Team

Say hello to our awesome team.

<VPTeamMembers size="small" :members="members" />

The file above now includes:

A frontmatter that specifies a "page" layout
A script tag that loads an external component and defines a variable
Styles to make the page pretty
Markdown with a custom component

The completed team page would render the following: Customised Theme page in Vitepress

Conclusion

Vitepress is an extremely flexible static site generator. Its default theme provides you with everything you need to get started quickly. The ability to load external themes, enhance the current theme, and or write custom code within your page makes this tool extremely powerful.

In future articles, we will discover what components are available within the Default Theme and see how you can make the most of your Vitepress site but keep on coding.

This Dot is a consultancy dedicated to guiding companies through their modernization and digital transformation journeys. Specializing in replatforming, modernizing, and launching new initiatives, we stand out by taking true ownership of your engineering projects.

We love helping teams with projects that have missed their deadlines or helping keep your strategic digital initiatives on course. Check out our case studies and our clients that trust us with their engineering.

Simone Cuomo

Software Architect, Mentor, Speaker and Writer. Passionate about all aspect of web development, with a special love for VueJs

@zelig880 @zelig880

Understanding Vue's Reactive Data

Introduction Web development has always been about creating dynamic experiences. One of the biggest challenges developers face is managing how data changes over time and reflecting these changes in the UI promptly and accurately. This is where Vue.js, one of the most popular JavaScript frameworks, excels with its powerful reactive data system. In this article, we dig into the heart of Vue's reactivity system. We unravel how it perfectly syncs your application UI with the underlying data state, allowing for a seamless user experience. Whether new to Vue or looking to deepen your understanding, this guide will provide a clear and concise overview of Vue's reactivity, empowering you to build more efficient and responsive Vue 3 applications. So, let’s kick off and embark on this journey to decode Vue's reactive data system. What is Vue's Reactive Data? What does it mean for data to be ”'reactive”? In essence, when data is reactive, it means that every time the data changes, all parts of the UI that rely on this data automatically update to reflect these changes. This ensures that the user is always looking at the most current state of the application. At its core, Vue's Reactive Data is like a superpower for your application data. Think of it like a mirror - whatever changes you make in your data, the user interface (UI) reflects these changes instantly, like a mirror reflecting your image. This automatic update feature is what we refer to as “reactivity”. To visualize this concept, let's use an example of a simple Vue application displaying a message on the screen: ` In this application, 'message' is a piece of data that says 'Hello Vue!'. Let's say you change this message to 'Goodbye Vue!' later in your code, like when a button is clicked. ` With Vue's reactivity, when you change your data, the UI automatically updates to 'Goodbye Vue!' instead of 'Hello Vue!'. You don't have to write extra code to make this update happen - Vue's Reactive Data system takes care of it. How does it work? Let's keep the mirror example going. Vue's Reactive Data is the mirror that reflects your data changes in the UI. But how does this mirror know when and what to reflect? That's where Vue's underlying mechanism comes into play. Vue has a behind-the-scenes mechanism that helps it stay alerted to any changes in your data. When you create a reactive data object, Vue doesn't just leave it as it is. Instead, it sends this data object through a transformation process and wraps it up in a Proxy. Proxy objects are powerful and can detect when a property is changed, updated, or deleted. Let's use our previous example: ` Consider our “message” data as a book in a library. Vue places this book (our data) within a special book cover (the Proxy). This book cover is unique - it's embedded with a tracking device that notifies Vue every time someone reads the book (accesses the data) or annotates a page (changes the data). In our example, the reactive function creates a Proxy object that wraps around our state object. When you change the 'message': ` The Proxy notices this (like a built-in alarm going off) and alerts Vue that something has changed. Vue then updates the UI to reflect this change. Let’s look deeper into what Vue is doing for us and how it transforms our object into a Proxy object. You don't have to worry about creating or managing the Proxy; Vue handles everything. ` In the example above, we encapsulate our object, in this case, “state”, converting it into a Proxy object. Note that within the second argument of the Proxy, we have two methods: a getter and a setter. The getter method is straightforward: it merely returns the value, which in this instance is “state.message” equating to 'Hello Vue!' Meanwhile, the setter method comes into play when a new value is assigned, as in the case of “state.message = ‘Hey young padawan!’”. Here, “value” becomes our new 'Hey young padawan!', prompting the property to update. This action, in turn, triggers the reactivity system, which subsequently updates the DOM. Venturing Further into the Depths If you have been paying attention to our examples above, you might have noticed that inside the Proxy method, we call the functions track and trigger to run our reactivity. Let’s try to understand a bit more about them. You see, Vue 3 reactivity data is more about Proxy objects. Let’s create a new example: ` In this example, when you click on the button, the message's value changes. This change triggers the effect function to run, as it's actively listening for any changes in its dependencies. How does the effect property know when to be called? Vue 3 has three main functions to run our reactivity: effect, track, and trigger. The effect function is like our supervisor. It steps in and takes action when our data changes – similar to our effect method, we will dive in more later. Next, we have the track function. It notes down all the important data we need to keep an eye on. In our case, this data would be state.message. Lastly, we've got the trigger function. This one is like our alarm bell. It alerts the effect function whenever our important data (the stuff track is keeping an eye on) changes. In this way, trigger, track, and effect work together to keep our Vue application reacting smoothly to changes in data. Let’s go back to them: ` Tracking (Dependency Collection) Tracking is the process of registering dependencies between reactive objects and the effects that depend on them. When a reactive property is read, it's "tracked" as a dependency of the current running effect. When we execute track(), we essentially store our effects in a Set object. But what exactly is an "effect"? If we revisit our previous example, we see that the effect method must be run whenever any property changes. This action — running the effect method in response to property changes — is what we refer to as an "Effect"! (computed property, watcher, etc.) > Note: We'll outline a basic, high-level overview of what might happen under the hood. Please note that the actual implementation is more complex and optimized, but this should give you an idea of how it works. Let’s see how it works! In our example, we have the following reactive object: ` We need a way to reference the reactive object with its effects. For that, we use a WeakMap. Which type is going to look something like this: ` We are using a WeakMap to set our object state as the target (or key). In the Vue code, they call this object targetMap. Within this targetMap object, our value is an object named depMap of Map type. Here, the keys represent our properties (in our case, that would be message and showSword), and the values correspond to their effects – remember, they are stored in a Set that in Vue 3 we refer to as dep. Huh… It might seem a bit complex, right? Let's make it more straightforward with a visual example: With the above explained, let’s see what this Track method kind of looks like and how it uses this targetMap. This method essentially is doing something like this: ` At this point, you have to be wondering, how does Vue 3 know what activeEffect should run? Vue 3 keeps track of the currently running effect by using a global variable. When an effect is executed, Vue temporarily stores a reference to it in this global variable, allowing the track function to access the currently running effect and associate it with the accessed reactive property. This global variable is called inside Vue as activeEffect. Vue 3 knows which effect is assigned to this global variable by wrapping the effects functions in a method that invokes the effect whenever a dependency changes. And yes, you guessed, that method is our effect method. ` This method behind the scenes is doing something similar to this: ` The handling of activeEffect within Vue's reactivity system is a dance of careful timing, scoping, and context preservation. Let’s go step by step on how this is working all together. When we run our Effect method for the first time, we call the get trap of the Proxy. ` When running the get trap, we have our activeEffect so we can store it as a dependency. ` This coordination ensures that when a reactive property is accessed within an effect, the track function knows which effect is responsible for that access. Trigger Method Our last method makes this Reactive system to be complete. The trigger method looks up the dependencies for the given target and key and re-runs all dependent effects. ` Conclusion Diving into Vue 3's reactivity system has been like unlocking a hidden superpower in my web development toolkit, and honestly, I've had a blast learning about it. From the rudimentary elements of reactive data and instantaneous UI updates to the intricate details involving Proxies, track and trigger functions, and effects, Vue 3's reactivity is an impressively robust framework for building dynamic and responsive applications. In our journey through Vue 3's reactivity, we've uncovered how this framework ensures real-time and precise updates to the UI. We've delved into the use of Proxies to intercept and monitor variable changes and dissected the roles of track and trigger functions, along with the 'effect' method, in facilitating seamless UI updates. Along the way, we've also discovered how Vue ingeniously manages data dependencies through sophisticated data structures like WeakMaps and Sets, offering us a glimpse into its efficient approach to change detection and UI rendering. Whether you're just starting with Vue 3 or an experienced developer looking to level up, understanding this reactivity system is a game-changer. It doesn't just streamline the development process; it enables you to create more interactive, scalable, and maintainable applications. I love Vue 3, and mastering its reactivity system has been enlightening and fun. Thanks for reading, and as always, happy coding!...

Nov 22, 2023

7 mins

VueJavaScriptTypeScriptWeb Development

Layouts & Theming in Vuetify 3

Introduction Do you want to avoid tinkering with CSS to get your website looking just right? Branding is everything in today's digital landscape. With Vuetify 3's customizable theming options, you can create web projects that perfectly reflect your unique branding, and visual identity. Additionally, you can reduce the duplicated code by creating layouts representing your application's different page structures. In a previous article introducing Vuetify 3 with Vue 3, we created an application that allowed us to add, display, and delete jokes. If you'd like to follow along with this article, please clone the GitHub repository. ` In this article, we'll go over how you can create layouts in Vuetify 3 to allow you to reuse the same layout for pages that share the same structure. We will also go over how you can customize the look and feel of your application to match your brand's visual identity through the powerful theming tools that Vuetify 3 offers us. Layouts in Vuetify 3 What are layouts, and how are they useful? In web development, layouts are akin to blueprints for the structure of your web pages. They provide a consistent and reusable frame for the different pages of an application. A well-designed layout can improve the user experience by providing familiarity and predictability as the user navigates through other parts of your application. Layouts are particularly helpful in reducing code duplication. Instead of defining the same structure for each page—headers, footers, and navigation menus, you define them once in a layout, and then apply that layout to any page that uses the same structure. This speeds up development, and makes your code easier to maintain. Using Layouts in Vuetify 3 Creating a layout in Vuetify 3 is as simple as creating a new Vue component. This component will include the common elements shared across multiple pages like headers, footers, and navigation bars. Here is an example of a basic layout: ` This layout has a header, a navigation drawer, and a footer. The component is where the content of the specific pages will be injected. Building a layout for our application Let's create a layout for our application. We'll have a top navigation bar and a footer. Inside the layouts directory, create a new file named Default.vue and add the following code: ` Additionally, in order for us to use our layout, we will need to modify our router/index.ts file to use the Default.vue component: ` This will make sure that our respective pages use the Default.vue layout that we created. The contents of the pages will appear in place of in the layout. It is also worth noting that you can create, and nest as many layouts as you want. Theming in Vuetify 3 Themes allow you to customize your application's default colors, surfaces, and more. If your brand has specific colors and styling, you can theme your Vuetify application to resemble your brand through theming better. Additionally, Vuetify 3 allows you to modify your theme in real-time programmatically. [Vuetify 3] also comes with light and dark themes pre-installed. Theming API Vuetify 3 offers us 2 main APIs for working with themes: - useTheme is a composable that allows us to get information about the current theme and will enable us to modify the existing theme. - v-theme-provider is used in the section of your Vue files to modify the theme of all of its children. Updating the theme of our application Updating the theme of our application is straightforward with Vuetify 3. Let's customize our application's primary and secondary colors. In the vuetify.ts file, modify the themes section to contain the following styles: ` In this example, we're defining a custom 'light' theme. If you want to use a dark theme, or any other named theme, you can add those as additional properties within the themes object. For example: ` And... That's it! By changing the various config options in the vuetify.ts file, you can modify how your application looks and feels to match your brand. If you'd like to learn more about themes and all the options you can provide, please check out the official Vuetify documentation. Conclusion In this article, we've gone through the concepts of layouts and theming in Vuetify 3. We've seen how layouts can reduce code duplication, and provide consistency across your application. We've looked at how Vuetify's theming features allow you to customize your application to match your brand's visual identity. Understanding and utilizing these features effectively can significantly enhance the development experience and the end user's interaction with your application. Remember, a well-structured and visually appealing application not only attracts users, but also retains them. Happy coding!...

May 19, 2023

4 mins

Vue

Ticket Management for a Successful Project Delivery

Introduction It is very common to assume that when a project fails to deliver on time, it is either the client's fault for changing scope during development, or the development team's technical inability to deliver the scoped milestone in time. Even if the above assumption may at times be partly correct, in this article, we will cover techniques and management tricks that are aimed at removing or minimizing the risk of failure. I am a strong believer that the way the project is managed is key to a project's success, no matter its scope-creep or difficulties. This article will focus on a specific area of project management: Ticket Management. The article will cover multiple areas of Ticket Management, from "Project Breakdown", to the definition of MVP, until exploring the very fine art of ticket writing. Disclaimer Before we jump into the main content of the article, I want to clarify that what I am about to share in the article below has helped me for years on multiple projects, but it is not a rule, and things may be adapted and work differently for different people and management styles. Break the Project Down There is no better way to start our little journey into project management technique than by discussing project breakdown. There are multiple videos, books, and posts that cover this topic and mostly all of them will refer to the definition of MVP (minimum viable product) as the starting point and first delivery milestone for a project: > A minimum viable product (MVP) is a version of a product with just enough features to be usable by early customers who can then provide feedback for future product development. > https://en.wikipedia.org/wiki/Minimum_viable_product As a project manager (or a tech lead taking over PM responsibility) you will be asked to work with the client to define the first milestone for a given product. This as defined above, will include the minimum amount of features to make the product "usable". On multiple occasions in my career, the client's expectation of an MVP has included more than a real MVP should. This is normal, since the client always wants to make a good first impression, and removing features may, at times, be seen negatively for the product. As I mentioned at the start, this post is going to focus on what YOU can do to make sure it is delivered successfully, and it will not focus on how to deal with difficult clients as that is outside the scope of this post. You may probably be wondering how, if we are not going to discuss MVP definition, are we going to change MVP delivery? Your MVP May Not Be the Client's MVP Well, this is actually where the magic begins. I call it magic, but as you will read in a few sentences, the method I use is pretty simple, but I can guarantee you to be very effective. The first step that we are going to take is to sit down with our team and define what you really would expect to see in a real barebone MVP. I usually find it simpler to address this by calling it *Alpha*. The idea of this exercise is to start from a very basic workable product, and then add small features to it as you and the team may seem fit as the MVP. > NOTE: Instead of starting from MVP requirements and trying to remove things, start from the basic technical implementation and build it up to the client MVP. The expectation of this exercise is a set of milestones that are smaller than the client MVP. This should not only be achieved by removing features that may not be seen as required (for example a newsletter integration), but also by proposing a basic version of agreed components (eg. Removing complex shadow from a card, or removing animation on client interaction). A reduced scope should also be associated with a quicker delivery. It is important to understand that this MVP does not have to be shared with the client, but should be visible within the team and actively used as the first and more important delivery milestone. The client (and all communication to them), will still work toward the MVP feature set and timeline. But internally, the team is working toward a faster delivery and a smaller feature set. You may be asking yourself, what are the reasons to add extra work on your shoulder and how can this help the delivery of a project? An effective breakup of MVP and Alpha will produce the following results: - It will provide early insight into project delivery: If you fail delivery of Alpha, you will quite probably fail overall MVP. - Reduce the complexity of the first iteration: As we will see later, removing unneeded complexity helps the team to focus. - Remove the stress from the team and you: Working on your deadline helps manage internal team stress and work with them. - Prioritizes what is needed: A successful Alpha delivery will deliver the client's working version very early on, and will also reduce the "consequences of failure". Failsafe for Missing Delivery Before we move forward to the next topic, I want to share a few more words about the "Alpha MVP" and its benefits. We are going to focus on missing deadlines and how the above methods, can act as a failsafe. As we all know, projects never go to plan. Many things can happen in a project that could affect its delivery. This could be a team member being sick, a delay in hardware delivery, a slow client, a change of scope, and more. Knowing that missing q deadline is more possible than actually hitting them due to unforeseen circumstances, it is just expected to create some guardrails to support our project. The first thing that comes to mind is probably adding a buffer to your project, and this is amazing if possible. But as experience shows us, extra time means extra features and scope creep from the client (Of course there are techniques to avoid this, but this blog post is focusing on what you can do without involving the client). I am not proposing anything extra for you to do to ensure you have an emergency exit in case of late delivery. All you need to know has already been shared above in the previous section! I have delivered many projects on time, but I have also failed others. What needs to be learned from the failure is that even if we "missed the full delivery" in many cases, we still went to production and the client was still happy. via GIPHY Defining an MVP that focuses on what is needed and not what is nice to have, not only speeds up development, but it will also mean that the tasks left at the end of the project are just nice to have, and issues that can easily go live after a few days and do not require immediate intervention. Just to provide more context, these are a few examples of things that have "bleed" outside of the project delivery, and the client was ok with it as we were still able to go to production. - Progress bars attached to client scrolling of the page - Renewal emails and cron for an e-commerce website - Complex page transition - Image zooming - Past event page The ones above are just simple tasks that we sometimes add to our tickets, without realizing the complexity and extra time that they may bring. Let's analyze the first point "Progress bar". This was initially expected to be developed as part of the main navbar ticket. As much as the feature seems simple, it takes time to test and develop, so we moved it out and delivered it later in the project. This allowed us to use those extra hours for actual changes to the data that happened right before the deadline. Creating an environment within your team where "saving a couple of hours" is seen as something important at every stage of the project, will eventually help you deliver faster. > Sometimes we think of a simple few hours of saving as superfluous, but it just takes a few of these changes to make a difference between delivery and failure. Write Just a Few Tickets In the previous section, we defined our MVP and Alpha milestones, and it is now time to write the tickets to achieve this delivery. My second suggestion is: Just write enough tickets to fulfil a couple of days of work and no more. As you may be aware, writing a ticket is a complicated matter and it can take quite some time- time that can be very valuable at the start of a project. Let's assume two different scenarios. The first is where the PM will focus on writing all the tickets, and the second is where we just write a few to get the team going and then analyze the key differences. Write All the Tickets This is a very common scenario. The PM has been given a project and asked to start it asap. At this stage, the PM will spend his first few days writing all the tickets that have been defined as the MVP and will share them with the rest of the team. He will probably join an onboarding meeting, but most of his time for the first few days will be in writing tickets. The backlog at the end of this exercise is going to be nice and full and the PM is going to feel ready to start. Write Just a Few Tickets Also in this case, the PM has been asked to task a new project, but instead of writing lots of tickets, the PM will just write enough for a couple of days. The Backlog looks empty with just a few tickets. Many Tickets vs Just a Few I know that you are probably thinking that I am mad to suggest writing fewer tickets, but I suggest you read below and probably even ask your team and you will be surprised about the answers. Let's compare the two above by using a few metrics: PM, Team, and Project. PM Time The first is PM. In the case of many tickets, the PM will have to spend a few hours writing tickets. Want or not, this is a lengthy operation that takes time. I usually take around 5-10 min per ticket to write them well with all the acceptance criteria and links required. So writing 20, 30 or even 50 of them can take days. In the case of a few tickets, the PM will regain valuable hours at the start of the project. This can be spent on many important tasks such as defining MVP, client communication, setting up procedures within the team, and actively spending time with the team to ensure they have a full understanding of the project and the product to be delivered. WIN: Write just a few tickets Team We are now changing perspectives and looking at this from the team side. As we have seen before, we have two possible examples. In the first one, the time will come in the morning, and have an onboarding meeting with the PM. After this meeting, they will have the ability to start a project. The backlog is nice and defined, and they have lots of tickets to work on, so they can put their heads down, and get on with the work. In the second, the PM is going to introduce the project and share a few tickets that they should accomplish within the next couple of days. The PM is going to be actively involved, and can get the team feedback on the tickets. For example, the team may prefer a Figma screenshot instead that the link or the team mentioned that would be nice to define Accessibility requirements within each ticket. Even if you would probably think that active cooperation can be achieved also from the first iteration (lots of tickets), I have learned from experience that this is not always the case. When the team has lots of tickets available, they just go on with the work and do not think of changing things as they are already set. Making fewer tickets forces the PM and the team to cooperate, they will all know what they are working toward and make adjustments very easy. WIN: Write just a few tickets Project In this last point, we are going to analyze the advantages and disadvantages that the above methodology would produce for our project. In the first method, the project is going to be fully scoped. The PM is going to be able to easily track the burndown and see the progress of the project. This can also be useful for the client as it will have clean visibility on its "MVP". In the second scenario, the PM has surely lots of extra work to do to maintain the project. She will have to be able to track projects using her milestones and not tickets, and she will have to fill the communication gap produced by the missing tickets. At this stage, you probably think that having more tickets is going to be better, but here comes the best part. Even if having fewer tickets will require the PM to work harder, it will produce a more flexible environment that can easily adapt and or change. Small changes in the way ticket are written can benefit the team's velocity, defining a small chunk of work help understand velocity and productivity, and having fewer tickets allow the client to change the scope and re-imagine his product without creating many obsolete tickets on the board. I agree that having fewer tickets and a dry backlog can be complicated to manage, but the benefits, in the long run, are massive. WIN: Fewer tickets if managed well! :) > Note: I may have been a little biased in the above comparison :P Conclusion Project Management is an art and it can be accomplished in many different ways. My management technique focuses on flexibility, but most importantly, team engagement. I think the success of every project is not held by the client's ability to stay on course with its initial idea, or by PM micro-managing the team to complete all the tasks to create the perfect burndown. I am a strong believer that the project's success is helped by the team working on it. If they are engaged, and all work together to accomplish the project, the project will have no issue. Please note that I am not saying that, if the team can complete their tickets, the project is going to be a success, but if the team is engaged in all aspects of the project, the project has a big chance of success. If a developer has a forum to help you define the technical flow of MVP, the project will be delivered faster. If a developer has the forum to express his/her idea on different breakdowns and execution of a task, the project will gain speed and momentum. Remember, you are not always able to change the client, but you can change the way you deliver the work to them!...

Jul 21, 2023

11 mins

Project Management

How to Make Coding Both Your Hobby and Profession with Jason Lengsdorf @ CityJS Conf 2024

Join us backstage at CityJS Conf for this conversation with Jason Lengsdorf. In this discussion, we explore strategies for reducing stress and anxiety among engineers, ensuring they maintain relevance in the dynamic world of coding. Jason emphasizes the importance of self-assurance and the role of play in fostering continual engagement with evolving technologies. Moreover, we get a sneak peek into Jason's latest venture, "Web Lunch," a platform where he converses with developers who have found harmony between their careers and personal satisfaction. Coding isn't just a job; it's a passion and a lifestyle. Jason highlights the significance of pursuing work that excites and challenges us, echoing the sentiment that coding can be both a career and a hobby. By infusing enjoyment and creativity into our coding endeavors, we can shape our professional trajectories in alignment with our values and interests. This approach not only minimizes regret but also maximizes happiness and fulfillment in our careers. Central to our discussion is the pivotal role of effective leadership in creating a supportive and encouraging work environment. Leaders who prioritize the well-being and happiness of their team members foster a culture of collaboration and empowerment. Through mentorship, guidance, and opportunities for growth, these leaders enable developers to align their personal goals with organizational objectives, leading to increased job satisfaction and professional fulfillment. Adaptability is key to sustained success in software engineering. Jason emphasizes the value of remaining open-minded and continuously learning, even when it means stepping out of our comfort zones. Embracing discomfort is an integral part of personal growth, allowing us to overcome obstacles and unlock our full potential. By nurturing a spirit of curiosity and adaptability, developers can navigate the complexities of their careers with resilience and enthusiasm....

Apr 25, 2024

2 mins

JavaScriptMentorship

Getting started with Vitepress

Getting started with Vitepress to create your blog site

What is Vitepress

Prerequisites

Create your project

What is available out of the box

Overriding the homepage

Site configuration

Modify the sidebar navigation

Enable Search

Add Favicon to your site

Writing your post

Writing your first page

Blog Frontmatter

Blog Markdown

Customize your blog with Vue

Conclusion

Simone Cuomo

You might also like

Understanding Vue's Reactive Data

Layouts & Theming in Vuetify 3

Ticket Management for a Successful Project Delivery

How to Make Coding Both Your Hobby and Profession with Jason Lengsdorf @ CityJS Conf 2024

You might also like

Understanding Vue's Reactive Data

Layouts & Theming in Vuetify 3

Ticket Management for a Successful Project Delivery

How to Make Coding Both Your Hobby and Profession with Jason Lengsdorf @ CityJS Conf 2024