VueJS

Vue 3 Composition API - watch and watchEffect

Published Apr 29, 2021

Updated Jul 22, 2024

8 min read

This article was written over 18 months ago and may contain information that is out of date. Some content may be relevant but please refer to the relevant official documentation or available resources for the latest information.

Vue 3 Composition API - `watch` and `watchEffect`

Introduction

One of the major benefits to the new Composition API in Vue 3 is how it provides a flexible and powerful reactivity system to developers. With Vue 2, developers were reliant on the Options API to build single-file components, which enforced a level of structure to how the system was used. The Composition API, on the other hand, gives the developer new opportunities to build reactive applications.

In a previous article, we explored the difference between ref and reactive methods. Let's build on that understanding, and introduce two new methods from the Composition API - watch and watchEffect.

Options API - `watch` in the Options API

The Options API provided us with the watch option, which is a way to observe when values changed and perform side effects based on that. Here's a basic example of what a watcher could look like with the Options API:

<template>
  <h2>Notes:</h2>
  <textarea v-model="notes" />
</template>

<script lang="ts">
import { defineComponent } from "vue";
import { save } from "./api";

export default defineComponent({
  data() {
    return {
      notes: ""
    }
  },
  watch: {
    notes(value, oldValue) {
      save(value);
    }
  }
})
</script>

Let's summarize what's going on here:

In our template, we have a textarea that is bound to our data value of notes. In our Javascript, we have a watch key, which takes an object. In that object, we have a function, also called notes. This function will be automatically called whenever the value of notes changes (for example, when text is entered into the field).

Each watcher takes two arguments: the new value, and the previous value. Since it's a function, we can do any validation or checks that need to happen here, and perform any side effects. In our example, when the text in the notes field changes, we are saving the value to a backend.

For further reading on watchers with the Options API, here's a link to the documentation for Vue 2.

Now that we have a basic understanding of watchers in the Options API, let's dive into the Composition API!

`watch` and `watchEffect`

The Composition API provides us with two different methods to handle side effects - watch and watchEffect. Just like with ref and reactive, these methods are not meant to compete with each other, but to be used as required by the application. Think of them as two similar tools that are each useful in certain cases. Both of these methods do the following:

Watch for changes in reactive variables
Allow the developer to perform side effects
Provide a way to cancel a side effect (in case the state has become invalid)

However, there are a number of differences between them as well. Here's a short list of what makes them different:

watch can be used to lazily trigger side effects (watchEffect is always immediate).
watchEffect automatically watches for changes to any state changes (watch must be provided with a variable or variables to watch).
watch provides access to the current and previous values.

It's important to take into account what you want to achieve, and use the correct tool for the job. As we work through this article, we'll do some comparison against the two options.

Composition API - `watchEffect`

Let's start refactoring the example above using watchEffect. Below is the same application using the Composition API:

<template>
  <h2>Notes:</h2>
  <textarea v-model="notes" />
</template>

<script lang="ts">
import { watchEffect, ref, defineComponent } from "vue";
import { save } from "./api";

export default defineComponent({
  setup() {
    const notes = ref("");

    watchEffect(() => save(notes.value));

    return {
      notes,
    };
  },
});
</script>

Since we are using the Composition API, we use ref to instantiate the notes variable. Also, we need to use notes.value, since it is a reference to the value and not the value itself. Finally, we return an object with notes so that it is available in the template.

With watchEffect, we provide an anonymous function as an argument, then perform our side effect of saving the text. Note that we don't need to provide notes as a value to be watched - watchEffect is capable of watching any reactive variables that are referenced within the callback function.

To highlight this, let's add a new variable to the mix - notesArePublic. Below is our updated application using two variables inside of the watchEffect:

<template>
  <h2>Notes:</h2>
  <textarea v-model="notes" />
  <label>
    Make notes public:
    <input type="checkbox" v-model="notesArePublic" />
  </label>
</template>

<script lang="ts">
import { watchEffect, ref, defineComponent } from "vue";
import { save } from "./api";

export default defineComponent({
  setup() {
    const notes = ref("");
    const notesArePublic = ref(false);

    watchEffect(() =>
      save({
        notes: notes.value,
        notesArePublic: notesArePublic.value,
      })
    );

    return {
      notes,
      notesArePublic,
    };
  },
});
</script>

Now, whenever either notes or notesArePublic change, the side effect will be triggered and our save function will be called. This can cut down on a lot of code compared to the Options API, where you would need to create multiple watchers that do the same thing.

A feature of the Composition API is the ability to remove watchers programmatically. Let's say that our user is done editing their notes, and wants to stop submitting values to the database. Both watch and watchEffect return a function that can be called to stop watching for changes.

Let's update our code to include a button that turns off our watcher.

<template>
  <h2>Notes:</h2>
  <textarea v-model="notes" />
  <label>
    Make notes public:
    <input type="checkbox" v-model="notesArePublic" />
  </label>
  <button @click="saveAndClose">Finish editing</button>
</template>

<script lang="ts">
import { watchEffect, ref, defineComponent } from "vue";
import { save } from "./api";

export default defineComponent({
  setup() {
    const notes = ref("");
    const notesArePublic = ref(false);

    const stopSaving = watchEffect(() =>
      save({
        notes: notes.value,
        notesArePublic: notesArePublic.value,
      })
    );

    const saveAndClose = () => {
      stopSaving();
    };

    return {
      notes,
      notesArePublic,
      saveAndClose,
    };
  },
});
</script>

When we call watchEffect, we are now saving its return as a variable, stopSaving. When the user clicks our Finish editing button, a function is called that will disable the watcher. Nice!

This can be useful when your application is watching for a certain critera to be met. Once the state is how you are watching it to be, you can stop watching, preventing your side effects from being triggered when they shouldn't be. This can help your code stay organized, and clearly communicates to other developers that a watcher is only neccessary for a certain task.

Another great feature is the ability to invalidate our side effects. In our example, what if the user enters more text after the save function has been called? By using the built-in invalidation, we can be aware when something has changed in our state and cancel our API request. Let's take a look at what that would look like.

<template>
  <h2>Notes:</h2>
  <textarea v-model="notes" />
  <label>
    Make notes public:
    <input type="checkbox" v-model="notesArePublic" />
  </label>
  <button @click="saveAndClose">Finish editing</button>
</template>

<script lang="ts">
import { watchEffect, ref, defineComponent } from "vue";
import { save } from "./api";

export default defineComponent({
  setup() {
    const notes = ref("");
    const notesArePublic = ref(false);

    const stopSaving = watchEffect((onInvalidate) => {
      const cancel = save({
        notes: notes.value,
        notesArePublic: notesArePublic.value,
      });

      onInvalidate(() => cancel());
    });

    const saveAndClose = () => {
      stopSaving();
    };

    return {
      notes,
      notesArePublic,
      saveAndClose,
    };
  },
});
</script>

The callback function we passed into watchEffect now has an argument - onInvalidate. This function also takes a callback as an argument, which is called when the watched state has changed. In our example, the save function is now returning a function that we are calling cancel, which can be used to abort the API request. When onInvalidate triggers, we call cancel, aborting the API request. No need to wait for the response when it's already out of date!

One thing to keep in mind is that watchEffect is immediately firing when your app loads. From the documentation, "To apply and automatically re-apply a side effect based on reactive state, we can use the watchEffect method. It runs a function immediately while reactively tracking its dependencies and re-runs it whenever the dependencies are changed." This means that immediately upon loading the page, our side effect is being triggered and data is sent to our API. This is very important to keep in mind! You may not want certain side effects (like saving an empty text field) to happen. If you need to lazily trigger effects, use the watch method instead.

Another important note: watchEffect is not watching your variables deeply. If we had a single object of data, which contained both of our variables, those variables updating would not trigger the side effect. In this case, we could convert the reactive object to refs, which would then correctly trigger our side effect.

<template>
  <h2>Notes:</h2>
  <textarea v-model="data.notes" />
  <label>
    Make notes public:
    <input type="checkbox" v-model="data.notesArePublic" />
  </label>
  <button @click="saveAndClose">Finish editing</button>
</template>

<script lang="ts">
import { watchEffect, reactive, defineComponent, toRefs } from "vue";
import { save } from "./api";

export default defineComponent({
  setup() {
    const data = reactive({
      notes: "",
      notesArePublic: false,
    });

    const stopSaving = watchEffect((onInvalidate) => {
      // This doesn't work
      // const cancel = save(data);

      // This does
      const parsed = toRefs(data);

      const cancel = save({
        notes: parsed.notes.value,
        notesArePublic: parsed.notesArePublic.value
      })

      onInvalidate(() => cancel());
    });

    const saveAndClose = () => {
      stopSaving();
    };

    return {
      data,
      saveAndClose,
    };
  },
});
</script>

Composition API - `watch`

Now let's explore the watch method. We can improve it by adding some feedback to the user when their notes have been saved. To do this, we will add a new variable: showNotesSavedNotification, but we'll only show it for a specific amount of time.

<template>
  <h2>Notes:</h2>
  <textarea v-model="notes" />
  <label>
    Make notes public:
    <input type="checkbox" v-model="notesArePublic" />
  </label>
  <button @click="saveAndClose">Finish editing</button>
  <aside v-if="showNotesSavedNotification">Notes have been saved!</aside>
</template>

<script lang="ts">
import { watchEffect, watch, ref, defineComponent } from "vue";
import { save } from "./api";

export default defineComponent({
  setup() {
    const notes = ref("");
    const notesArePublic = ref(false);
    const showNotesSavedNotification = ref(false);

    const stopSaving = watchEffect((onInvalidate) => {
      const cancel = save({
        notes: notes.value,
        notesArePublic: notesArePublic.value
      }, () => showNotesSavedNotification.value = true)

      onInvalidate(() => cancel());
    });

    const saveAndClose = () => {
      stopSaving();
    };

    watch(showNotesSavedNotification, (value) => {
      if (value) {
        setTimeout(() => {
          showNotesSavedNotification.value = false;
        }, 5000);
      }
    })

    return {
      notes,
      notesArePublic,
      showNotesSavedNotification,
      saveAndClose,
    };
  },
});
</script>

Using the watch method is very similar to how we would use functions with the watch option in the Options API. In fact, according to the documentation, "The watch API is the exact equivalent of the component watch property." In our example above, whenever content is saved, the showNotesSavedNotification variable is set to true. Our watcher is then called, setting a timeout and clearing the notification after five seconds.

Let's go back to the point I made before about watchEffect being immediate. We don't really want to save an empty text field to our database - it's much more reasonable to wait for the user to enter a value first. Let's try using watch instead of watchEffect and see what benefits we get from it.

<template>
  <h2>Notes:</h2>
  <textarea v-model="notes" />
  <label>
    Make notes public:
    <input type="checkbox" v-model="notesArePublic" />
  </label>
  <button @click="saveAndClose">Finish editing</button>
  <aside v-if="showNotesSavedNotification">Notes have been saved!</aside>
</template>

<script lang="ts">
import { watch, ref, defineComponent } from "vue";
import { save } from "./api";

export default defineComponent({
  setup() {
    const notes = ref("");
    const notesArePublic = ref(false);
    const showNotesSavedNotification = ref(false);

    const stopSaving = watch(
      [notes, notesArePublic],
      (value, oldValue, onInvalidate) => {
        const cancel = save(
          {
            notes: notes.value,
            notesArePublic: notesArePublic.value,
          },
          () => (showNotesSavedNotification.value = true)
        );

        onInvalidate(() => cancel());
      }
    );

    const saveAndClose = () => {
      stopSaving();
    };

    watch(showNotesSavedNotification, (value) => {
      if (value) {
        setTimeout(() => {
          showNotesSavedNotification.value = false;
        }, 5000);
      }
    });

    return {
      notes,
      notesArePublic,
      showNotesSavedNotification,
      saveAndClose,
    };
  },
});
</script>

We have removed watchEffect and replaced it with watch. Did you notice that the first argument to the method is an array with both of our values? We can use this syntax to watch multiple variables, rather than being tied to a single one. In this way, we still only have to write a single watcher, which is excellent for avoiding code duplication.

Also of note - because we are watching an array, the values of value and oldValue are also arrays. For example, on the first keypress, oldValue would look like [ "", false ]. Depending on your use case, this might not be particularly helpful, but it's important to be aware of if you need to track the previous values of your watched variables.

In addition, the watch method is still providing us with the ability to remove the watcher, as well as the onInvalidate method. This is another improvement over the Options API. Regardless of whether we use watchEffect or watch, we still get the benefits of the improved API.

Let's make one last change to our application. I'd really like to bundle our notes and public status into a reactive object. Does that work with watch better than it did with watchEffect? Let's find out.

<template>
  <h2>Notes:</h2>
  <textarea v-model="data.notes" />
  <label>
    Make notes public:
    <input type="checkbox" v-model="data.notesArePublic" />
  </label>
  <button @click="saveAndClose">Finish editing</button>
  <aside v-if="showNotesSavedNotification">Notes have been saved!</aside>
</template>

<script lang="ts">
import {
  watch,
  ref,
  reactive,
  defineComponent,
} from "vue";
import { save } from "./api";

export default defineComponent({
  setup() {
    const data = reactive({
      notes: "",
      notesArePublic: false,
    });
    const showNotesSavedNotification = ref(false);

    const stopSaving = watch(
      () => ({...data}),
      (value, oldValue, onInvalidate) => {
        console.log(value, oldValue)
        const cancel = save(
          value,
          () => (showNotesSavedNotification.value = true)
        );

        onInvalidate(() => cancel());
      }
    );

    const saveAndClose = () => {
      stopSaving();
    };

    watch(showNotesSavedNotification, (value) => {
      if (value) {
        setTimeout(() => {
          showNotesSavedNotification.value = false;
        }, 5000);
      }
    });

    return {
      data,
      showNotesSavedNotification,
      saveAndClose,
    };
  },
});
</script>

Yes, in fact, we can watch our reactive object! According to the documentation, "A watcher data source can either be a getter function that returns a value, or directly a ref". In this case, since we are using a reactive object, we can pass in a function that returns our data reactive object, and the watcher will trigger as expected.

Be aware that we technically could watch the data object directly, but this can have unintended consequences. Again from the docs, "Watching a reactive object or array will always return a reference to the current value of that object for both the current and previous value of the state. To fully watch deeply nested objects and arrays, a deep copy of values may be required."

In this case, if we were to do this:

const stopSaving = watch(
  data,
  (value, oldValue, onInvalidate) => {
    console.log(value, oldValue)
    const cancel = save(
      value,
      () => (showNotesSavedNotification.value = true)
    );

    onInvalidate(() => cancel());
  },
);

Then both value and oldValue would be identical! This is clearly not what we meant to do. To avoid this, we are using the Spread syntax to create a new object which is both updating and being watched correctly, as well as not be passed by reference into both the current and previous values.

One more point to be aware of: because the watch method is the same as what is provided in the Options API, we also have access to its options, like deep and immediate. So if you need to watch an object deeply, or trigger side effects immediately, you can still do so with the watch method!

Conclusion

Both watch and watchEffect have their uses. Both of them can be used to trigger side effects in your application. Next time you find yourself needing to trigger an effect in your code, ask yourself:

Does this effect need to be immediate?
Should it only trigger from a single source, or whenever its dependencies change?
Am I watching an object, or a ref?

And of course, make sure that a side effect is really the correct course of action for your use case. Side effects can often be used when either a computed property, or a method is a better choice for the situation.

Here's a link to an example of the final version of this code on Stackblitz.

One last thing - because the Composition API doesn't need to be used within Vue single-file components, there are a lot of great uses for both watch and watchEffect. Here's a great presentation from VueConf Toronto where Oscar Spencer uses the Vue Composition API with an Express app to trigger side effects on Twitter. Check it out!

Until next time!

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.

About the author(s)

Lindsay Wardell
Lindsay is a software engineer at This Dot Labs, and a host on the podcast Views on Vue. She loves learning about new languages and tools, and sharing that knowledge with the community.
@lindsaykwardell @lindsaykwardell

Color Theory For Software Engineers + Color Accessibility & Performance with Sarah Shook

In this episode of the Modern Web podcast, Tracy Lee and Rob Ocel sit down with Sarah Shook, a UI/UX engineer at Hunter Industries. They discuss the topic of Sarah’s THAT Conference talk on color theory, exploring the intricacies of RGB, HSL, and hex color models. The discussion also touches on the importance of understanding how color accessibility impacts your page’s performance. Chapters - 00:00 - Introduction and Guest Introduction - 01:30 - Balancing Work and Parenthood - 03:20 - Family-Friendly Conferences and THAT Conference Experience - 05:45 - Overview of Sarah's Presentation on Color Theory - 07:00 - Understanding Additive and Subtractive Color Models - 09:00 - RGB to Hex Conversion Explained - 11:45 - Importance of Color Theory in Web Development - 14:00 - Accessibility and Color Luminescence - 16:00 - Tools and Resources for Color Accessibility - 18:30 - Sarah’s Experience with Vue and Other Frameworks - 21:00 - Discussion on Framework Deployment and Tooling - 23:15 - The Challenges and Benefits of Learning Multiple Frameworks - 25:00 - Tailwind, TypeScript, and Framework Preferences - 27:00 - Vue Community and Tooling Insights - 29:00 - Advanced JavaScript and TypeScript Content with DropJS - 31:00 - Sarah’s Color Utility Project and Where to Find Her - 32:30 - Closing Thoughts and Outro Follow Sarah Shook on Social Media Twitter: https://x.com/shookcodes Linkedin: https://www.linkedin.com/in/sarahshook/ Github: https://github.com/shookcodes Sponsored by Wix Studio...

Aug 27, 2024

1 min

JavaScriptVueReact

Getting started with Vitepress

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: ` 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: 1) Add a hero image. This image can either be externally sourced or saved within the repository. ` 2) Update the action buttons. ` 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". 3) 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: ` The homepage is now completed and updated and it should look like this: 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: ` 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 Modify the sidebar navigation 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: ` 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. ` With just a simple config change, our site will now have a full site search working as shown below: 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 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: ` we would define the following head config: ` 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: ` 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: ` 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: ` The above will produce an unordered list with all our links. 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: ` 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. ` 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. ` 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. ` 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 tag, we can load a tag and update our styles: ` The completed file will look like this: ` 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: 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....

Dec 21, 2023

12 mins

VueViteVitepress

Building Web Components with Vue 3.2

Introduction Have you ever worked across multiple projects, and wanted a set of custom components you could just leverage across all of them? Whether for a job or just for side projects, having a suite of components you can reach for is an excellent way to get going faster in a new or existing project. But what if not all of your projects are using the same UI framework? Or, what if you have one that isn't using any JavaScript framework at all, and is completely server-rendered? As a Vue developer, ideally we would like to just use our framework of choice to build complex user interfaces. But sometimes we find ourselves in the above situation, working with another JavaScript framework such as React or Angular, or using a backend rendering system like Rails or Laravel. How can we build a reusable UI across these various frontend options? In Vue 3.2, we now have a solution to this problem: Web Components, powered by Vue! Web Components According to MDN, "Web Components is a suite of different technologies allowing you to create reusable custom elements — with their functionality encapsulated away from the rest of your code — and utilize them in your web apps." Consider a few existing elements in HTML, such as select or video. These interactive elements contain their own basic styling (typically provided by the browser), some internal logic, and a way to listen to events. Web Components allow developers to build their own elements, and reference them in their HTML - no framework required. Here's a very basic web component example of a component that would display the current time. ` Once a custom Web Component has been defined, they can be rendered as part of the DOM, just like any standard HTML element. We can use this element in our HTML like this: ` We can also use custom attributes with these elements, allowing us to pass data into them (similar to props in Vue). Note that objects cannot be passed in as attributes, because that is a JavaScript concept, not an HTML feature. ` While we could write this logic pretty easily in a script tag using vanilla JavaScript, utilizing Web Components gives us the ability to encapsulate specific logic and functionality within the component, thus keeping our code more organized and understandable. This is the same reason we utilize component frameworks like Vue and React. Also, as we discussed earlier, Web Components are flexible in that they can be used without a JS framework, but are also compatible with modern frameworks (React and Vue both other support for using Web Components). Vue-Powered Web Components Vue 3.2 includes built-in support for defining custom Web Components while utilzing the Vue API. In this way, we get the best of both worlds - custom, reusable components across frameworks/interfaces, plus the excellent API of Vue. Let's take our example of getting the current time, and translate that into a Vue component. We will be using , which is the recommended way to write Vue single-file components today. To start, let's create our new file, CurrentTime.ce.vue (ce in this case stands for custom element). ` Great, our component is doing exactly what we were doing before. Next, we need to import this into our main Javascript somewhere, and define it as a custom element. ` What did we do here? 1. First, we import Vue's defineCustomElement function, which converts a Vue component into a custom element. 2. We then import our Vue SFC, and pass it into defineCustomElement, generating the constructor required for the web components APIs. 3. Then, we define the custom element in the DOM, supplying it with the tag that we want to use (current-time) and the constructor it should use to render. With that, our Vue web component can now be rendered in our app! And since web components work in all modern frameworks (as well as non-JS frameworks like Ruby on Rails or Laravel), we can now build out a suite of web components for our application using Vue, and then utlize them in any frontend we want. Here's a basic example using vanilla JS, and the default Vite template: ` You can see a working example of this on Stackblitz. More Features Creating a basic Vue component isn't always what you want to do, though. What happens if we need to utilize props or events? Fortunately, Vue has us covered here as well. Let's explore some of the basic functions we'd expect from our custom Vue components. Props The first thing we want to do is pass in props to our web component. Using our component, we want to be able to set the time zone. For this case, we can use props as we normally would for an HTML element. In our HTML template, let's change our code to the following: ` If you save your file now, you will probably get an error in your console like this one: ` This is because our prop isn't defined in the component yet. Let's take care of that now. Go back to your Vue component, and make the following changes: ` In our Vue component, we are now defining props (using Vue 3.2's defineProps helper, which we do not need to import), then using the timeZone prop to translate the date into the correct time zone string. Nice! Save your files, and our app should work again as expected, but this time, it will display the date in a different time zone. Feel free to play around with it a bit, trying out some different time zones. By default, Vue will translate props into their defined types. Since HTML only allows strings to be passed in as attributes, Vue is handling the translation to different types for us. Events From the docs: "Events emitted via this.$emit or setup emit are dispatched as native CustomEvents on the custom element. Additional event arguments (payload) will be exposed as an array on the CustomEvent object as its details property." Let's add a basic emit from our component that will trigger a console.log. In our Vue component, update our script block to the following: ` The main change we're making here is to add defineEmits (also available without import, similar to defineProps) in order to define what events this component makes. We then begin to use this in our setInterval step, to emit the new date as an event. In our main.js, we'll now add the event listener to our web component. ` With this, whenever the first component emits a datechange event, we will be able to listen for it, and act accordingly. Nice! Slots Slots are used exactly as expected within Vue, including named slots. Scoped slots, as they are an advanced feature within a full Vue application, are not supported. Also, when utilizing named slots in your application, you will need to use the native slot syntax, rather than Vue's specific slot syntax. Let's give this a try now. In you Vue component, change your template to the following: ` For this example, we are using a standard slot (we'll get back to named slots later). Now, in your HTML, add some text in between the tags: ` If you save and reload your page, you should now see that your text (or whatever content you want) is correctly passing into your web component. Now, let's do the same thing using named slots. Change your Vue component to have a named slot (`, for example), and your HTML like this: ` The result should be the same! And now we can use named slots in our web components. Styles One of the great parts about web components is that they can utilize a shadow root, an encapsulated portion of the DOM that contains their own styling information. This feature is available to our Vue web components as well. When you name your file with the .ce.vue extension, it defaults to having inline styles. This is perfect if you want to use your components as a library in an application. Provide/Inject Provide and inject also work as expected within Vue web components. One thing to keep in mind, however, is that they only can pass data to other Vue web components. From the docs, "a Vue-defined custom element won't be able to inject properties provided by a non-custom-element Vue component." Conclusion Vue 3.2 provides the ability to write custom web components using Vue's familiar syntax, and the flexibility of the Composition API. Keep in mind, however, that this is not the recommended approach to writing Vue applications, or application development in general. The documentation goes to great lengths to explain the differences between web components and Vue-specific components, and why the Vue team feels their approach is preferable for web development. However, web components are still an amazing technology for building cross-framework applications. Plenty of tools exist in the web development ecosystem focused purely on web components, such as Lit or Ionic. While this may not be the recommended approach to building applications with Vue, it can provide an encapsulated way to get certain features developed and functional across teams or projects. Regardless of your stance on web components, I highly encourage you to check out this new feature of Vue and experiment with it yourself. You could even try mounting your component in React or Svelte, and see how easy it is to work with across JavaScript frameworks. Most important of all, remember that the development ecosystem is always improving and growing, and it's up to you to be ready to grow with it. StackBlitz Demo Play around with the StackBlitz demo below and here's an example of a Vue web component I am utilizing in a side project I'm working on. Have fun!...

Oct 5, 2021

7 mins

VueJavaScriptWeb Development

Learning Paths for Next.JS Developers with Ankita Kulkarni

In this video, Rob Ocel and co-hosts Tracy Lee, Adam Rackis, and Danny Thompson talk with tech educator Ankita Kulkarni about her journey from engineering leader to full-time educator. Ankita shares insights on teaching Next.js, bridging practical knowledge gaps, and helping developers tackle real-world challenges. They discuss Next.js as a React-based framework, its benefits, and the challenges it presents for beginners. Chapters - Introduction to the Podcast and Guests 00:01 - Meet Ankita Kulkarni, Tech Educator 00:26 - Ankita's Transition to Full-Time Education 01:41 - Teaching Practical Knowledge in Next.js 03:19 - Effective Methods for Teaching Next.js 05:27 - Challenges of Being a Full-Time Educator 07:48 - Balancing Broad and Specific Examples 09:54 - Embracing Mistakes as a Teaching Tool 12:13 - Pair Programming and Mentorship 14:00 - Discussion on Next.js and Framework Adoption 16:48 - Advantages and Challenges of Next.js 18:12 - Choosing the Right Framework for Your Needs 20:35 - Impact of Next.js in React Documentation 22:26 - Learning Paths for New Developers 23:24 - The Rise of Full-Stack Web Development 25:09 - Benefits of Frameworks Abstracting Complexity 26:27 - OpenNext and Deployment Flexibility 28:06 - Ankita's Excitement for New Next.js Features 30:35 - The Future of Next.js Without Vercel 32:16 - Final Thoughts and Where to Find Everyone Online 34:21 Follow Ankita Kulkarni on Social Media Twitter: https://x.com/kulkarniankita9 YouTube: https://www.youtube.com/@kulkarniankita Sponsored by This Dot: thisdot.co...

Nov 12, 2024

2 mins

NextJSJavaScript

Let's innovate together!

We're ready to be your trusted technical partners in your digital innovation journey.

Whether it's modernization or custom software solutions, our team of experts can guide you through best practices and how to build scalable, performant software that lasts.

Vue 3 Composition API - watch and watchEffect

Vue 3 Composition API - `watch` and `watchEffect`

Introduction

Options API - `watch` in the Options API

`watch` and `watchEffect`

Composition API - `watchEffect`

Composition API - `watch`

Conclusion

Lindsay Wardell

You might also like

Color Theory For Software Engineers + Color Accessibility & Performance with Sarah Shook

Getting started with Vitepress

Building Web Components with Vue 3.2

Learning Paths for Next.JS Developers with Ankita Kulkarni

Let's innovate together!

You might also like

Color Theory For Software Engineers + Color Accessibility & Performance with Sarah Shook

Getting started with Vitepress

Building Web Components with Vue 3.2

Learning Paths for Next.JS Developers with Ankita Kulkarni

Vue 3 Composition API - watch and watchEffect

Introduction

Options API - watch in the Options API

watch and watchEffect

Composition API - watchEffect

Composition API - watch

Conclusion

Lindsay Wardell

Color Theory For Software Engineers + Color Accessibility & Performance with Sarah Shook

Getting started with Vitepress

Building Web Components with Vue 3.2

Learning Paths for Next.JS Developers with Ankita Kulkarni

Let's innovate together!

Color Theory For Software Engineers + Color Accessibility & Performance with Sarah Shook

Getting started with Vitepress

Building Web Components with Vue 3.2

Learning Paths for Next.JS Developers with Ankita Kulkarni

Vue 3 Composition API - `watch` and `watchEffect`

Options API - `watch` in the Options API

`watch` and `watchEffect`

Composition API - `watchEffect`

Composition API - `watch`