developers

Vue Composition API Tutorial: Build a Project Idea Generator

Learn how to use the Vue 3 Composition API to build a project idea generator.

Holly Guevara

Former Developer Content Manager

Nov 11, 2020 • 19 min read

📌 Note: Auth0 doesn't yet support Vue 3. This tutorial is just a look at using the Composition API in a simple application without authentication.

A common issue that new developers run into is figuring out where to begin. You do tutorial after tutorial to learn a new concept, but once you complete a tutorial, you're left wondering, "...now what"?

In this tutorial, you'll build a project idea generator (inspired by this tweet). You'll be able to use the final application to select the skills you want to work on and be given project idea suggestions based on those selections.

The primary purpose of this tutorial is to learn how to use the Vue 3 Composition API, but the project generator will be a fun side effect.

The tutorial will cover:

  • Calling an Express API with Vue 3
  • Using the Composition API in Vue 3
  • Advanced JavaScript array filtering
  • Using filters in Vue 3

I'll assume you have some basic Vue 2 knowledge but are new to Vue 3. If this is your first time using Vue and you feel you need some background, check out my Beginner's Vue.js Tutorial.

You can find the final project in this GitHub repository.

🚀 Let's get started!

Vue 3 Setup

First, you need to create your Vue project. I like to use the Vue CLI to get up and running quickly.

You can create a new project with the CLI by running:

npx @vue/cli create project-generator

If you already have the CLI, make sure your running at least 

v4.5
so that you can use Vue 3.

Choose the options shown below.

? Please pick a preset:
  Default ([Vue 2] babel, eslint)
  Default (Vue 3 Preview) ([Vue 3] babel, eslint)
❯ Manually select features

👩‍💻 Tip: Press 

spacebar
to select an option and 
enter
to submit once you're done selecting

? Check the features needed for your project:
❯ ◉ Choose Vue version
  ◉ Babel
  ◯ TypeScript
  ◯ Progressive Web App (PWA) Support
  ◯ Router
  ◯ Vuex
  ◉ CSS Pre-processors
  ◉ Linter / Formatter
  ◯ Unit Testing
  ◯ E2E Testing

For features, select "Choose Vue version", "Babel", "CSS Pre-processors", and "Linter / Formatter".

? Choose a version of Vue.js that you want to start the project with
  2.x
❯ 3.x (Preview)
? Pick a CSS pre-processor (PostCSS, Autoprefixer and CSS Modules are supported by default): (Use arrow keys)
❯ Sass/SCSS (with dart-sass)
  Sass/SCSS (with node-sass)
  Less
  Stylus
? Pick a linter / formatter config: (Use arrow keys)
❯ ESLint with error prevention only
  ESLint + Airbnb config
  ESLint + Standard config
  ESLint + Prettier
? Pick additional lint features: (Press <space> to select, <a> to toggle all, <i> to invert selection)
❯ ◉ Lint on save
  ◯ Lint and fix on commit
? Where do you prefer placing config for Babel, ESLint, etc.? (Use arrow keys)
❯ In dedicated config files
  In package.json
? Save this as a preset for future projects? (y/N) N

Now you'll wait a minute for the CLI to generate your project. Once it's done, switch into the project folder and run it with:

cd project-generator
npm run serve

And your starter application is now running on http://localhost:8080!

Modify the Starter App

Open up the project in your code editor.

👩‍💻 Tip: If you're using VS Code, install the Vetur extension to get syntax highlighting, Emmet shortcuts, formatting, auto-completion, and more.

For simplicity, you're going to just keep everything in one main component called 

Generator.vue
. You'll notice at the end that some of this can be refactored out into separate components, but to keep this tutorial focused on the Composition API, you can save refactoring for later.

Rename the 

src/components/HelloWorld.vue
component to 
src/components/Generator.vue
and replace its content with a barebones Vue component:

// src/components/Generator.vue

<template>
  <div>
  </div>
</template>

<script>
export default {
  name: 'Generator'
}
</script>

<style>
</style>

Next, open up 

src/App.vue
and replace it with:

<template>
  <Generator />
</template>

<script>
import Generator from './components/Generator.vue'

export default {
  name: 'App',
  components: {
    Generator
  }
}
</script>

<style lang="scss">
html, body {
  margin: 0;
  height: 100%;
  background: #F9F9F9;
}
.container {
  padding-top: 20px;
}
</style>

Here, you're just pulling in the 

Generator
component. There's nothing in here yet, but once you start adding to the component, the base 
App
component is already set up to display it.

Finally, in 

src/assets
, delete 
Logo.png
.

Add styles with Bulma

For basic styling, you're going to use Bulma, which is an open-source CSS framework.

Run the following in your terminal to install it:

npm install bulma

Next, you need to import it into your Vue project. Create a new file under 

src/assets
called 
main.scss
. Here, you just need to import Bulma.

// src/main.scss
@import '~bulma';

Now, bring that 

main.scss
file into your Vue templates by opening 
src/main.js
and updating it with:

import { createApp } from 'vue'
import App from './App.vue'
import '@/assets/main.scss';  // 👈 new code

createApp(App).mount('#app')

This should leave you with a simple base Vue application. And this is where the real fun begins!

Composition API vs Options API

One of the big features that the Vue 3 release brings is the Composition API. In Vue 2, components were built using the Options API. The CodeSandbox below shows a very simple component using the Options API.

Component with Options API

In Vue 3, in addition to the Options API, you now have the option to use the Composition API. Below is an example of the exact same component, but using the Composition API instead.

Component with Composition API

You'll notice the big difference here is the 

setup
function. This is a new component option that holds all of the logic for the component. Instead of defining data, methods, and lifecycle hooks as separate component options, all of these now lie in the 
setup
function.

Another important difference is that you no longer have to use 

this
to access your data in methods. This change has allowed for much better Typescript support in Vue 3.

Create a Component using Composition API

Let's see the Composition API in action by adding to the 

Generator
component that you created earlier.

Here's what this component should do:

  • Call the Express API (will be provided) to grab the list of skills that can be used in the generator
  • Display the list of skills
  • Allow the user to select the skills they want to work on
  • Call the Express API to get the list of application ideas
  • Display the application idea options based on the skills selected
  • Create a filter to select a random option from the app list

First, clone the Application Generator API repository to get the Express API. 

git clone git@github.com:auth0-blog/app-generator-api.git
cd app-generator-api

Run it with:

npm install
node server.js

You'll be working with the data shown here soon, so you can leave these tabs open if you'd like to reference the data structure throughout the article.

Get the list of skills

Next, open up 

src/components/Generator.vue
. The first item on the agenda is to call the Express API to get the list of skills. Let's do that now. Replace the 
<script></script>
section with the following:

// src/components/Generator.vue

// ...

<script>
import { ref } from 'vue';

export default {
  name: 'Generator',
  setup() {
    const GENERATOR_BASE = 'http://localhost:3000';
    const skillList = ref([]);

    async function getSkillList() {
      const response = await fetch(`${GENERATOR_BASE}/skills`);
      skillList.value = await response.json();
    }

    getSkillList();

    return {
      skillList
    }
  }
}
</script>

// ...

So what's happening here? First, you're importing 

ref
. This allows your data to be reactive. In other words, you can use this data in your template, and if it changes, the template value will change as well.

Inside the 

setup
function, you'll see that 
skillList
is declared as an empty array wrapped in 
ref()
. This returns a reactive ref object with just one property: 
value
. The 
.value
property points to the inner value of the ref object, which in this case, is the empty array.

Next, in the 

getSkillList
function, you're making a request to the 
/skills
endpoint of the Application Generator API. 
skillList
is set to the response that comes back. You should notice here the use of the 
.value
property mentioned above. This is how you access and set the value of a 
ref
.

Finally, you need to return any data you want to expose to the template. So far, that's just 

skillList
.

Display the list of skills

The next item on the agenda is to display the list of skills. Let's do this now so that you can see how 

skillList
can be used in the template.

Update the 

<template></template>
and 
<style></style>
sections as follows:

<template>
<div class="generator">
  <section class="hero is-primary is-bold has-text-centered py-6">
    <div class="hero-body">
      <div class="container">
        <h1 class="title">
          What skills do you want to work on?
        </h1>
        <div v-for="skill in skillList" :key="skill.id">
          <div class="field">
            <label class="checkbox">
              <input type="checkbox" :value="skill.id">
              {{ skill.skill }}
            </label>
          </div>
        </div>
      </div>
    </div>
  </section>
</div>
</template>

<script>
// ...
</script>

<style scoped>
  label {
    font-size: 20px;
  }
</style>

Here, you're looping over the 

skillList
array and setting up a checkbox input next to each skill. There is also some simple Bulma styling here.

Allow the user to select skills

Next up, you need to allow the user to select the skills they want to work on. You've already laid the foundation for this by setting up the checkboxes and setting the value to the 

id
of the selected skill. However, the checkboxes currently aren't bound to anything, so nothing is really happening.

To fix this, add a new ref in the 

setup
function called 
selectedSkills
, and set it to an empty array. Make sure you also return it so that it can be used in the template. Then, update the template to bind the checked boxes to 
selectedSkills
using 
v-model
.

<template>
  <div class="generator">
    <!-- ... -->
    <div v-for="skill in skillList" :key="skill.id">
      <div class="field">
        <label class="checkbox">
          // 👇 new code
          <input type="checkbox" v-model="selectedSkills" :value="skill.id"> 
          {{ skill.skill }}
        </label>
      </div>
    </div>
    <!-- ... -->
  </div>
</template>
<script>
  import { ref } from 'vue';

  export default {
    name: 'Generator',
    setup() {
      const GENERATOR_BASE = 'http://localhost:3000';
      const skillList = ref([]);
      const selectedSkills = ref([]);  // 👈 new code

      async function getSkillList() {
        const response = await fetch(`${GENERATOR_BASE}/skills`);
        skillList.value = await response.json();
      }

      getSkillList();

      return {
        skillList,
        selectedSkills  // 👈 new code
      }
    }
  }
</script>
<style scoped>
  label {
    font-size: 20px;
  }
</style>

To confirm that it's working, you can temporarily add the following to the template:

<template>
  <div class="generator">
    <!-- ... -->
    <div v-for="skill in skillList" :key="skill.id">
      <div class="field">
        <label class="checkbox">
          <input type="checkbox" v-model="selectedSkills" :value="skill.id">
          {{ skill.skill }}
        </label>
      </div>
    </div>
    {{ selectedSkills }}   <!-- 👈 new temp code -->
    <!-- ... -->
  </div>
</template>

Select some skills, and you should see an array displayed that holds the 

id
s of the skills that you select. Once you confirm that's working, go ahead and remove the last line.

Get the list of application ideas

Next up, you need to grab the list of application ideas from the Express API. This will look similar to the API call that was made earlier to get the skills list.

Add the following to your 

setup
function:

setup() {
  const GENERATOR_BASE = 'http://localhost:3000';
  const skillList = ref([]);
  const selectedSkills = ref([]);
  const filteredAppList = ref([]);    // 👈 new code
  let appList = [];   // 👈 new code

  async function getSkillList() {
    const response = await fetch(`${GENERATOR_BASE}/skills`);
    skillList.value = await response.json();
  }

  // 👇 new code
  async function getAppList() {
    const response = await fetch(`${GENERATOR_BASE}/apps`);
    appList = await response.json();
    filteredAppList.value = appList;
  }

  getSkillList();
  getAppList();   // 👈 new code

  return {
    skillList,
    selectedSkills,
    filteredAppList   // 👈 new code
  }
}

Do you notice anything different here? Take a look at how 

appList
is declared. It isn't using 
ref()
! Because this value isn't being exposed in the template, you don't need it to be reactive. The purpose of this list is to be the main source of possible applications that the user can build.

Because the user is going to be filtering the list based on what skills they want to work on, you're also setting up the 

filteredAppList
array. This array needs to be reactive because it's going to be displayed in the template. As soon as the user clicks on a skill, this list will need to be updated to show which applications include that skill. You're setting it to include all applications before the user selects anything.

Display the options based on the skills selected

This leads to the next action item: displaying the application options based on the skills that the user selects.

The filtering required to get the final application list is going to get a little complicated, so let's walk through the logic first. The goal of this function is to generate the 

filteredAppList
array. This will hold all the possible application suggestions that contain the skills that the user selected.

You're going to create a function called 

generateFilteredAppList()
that will do the following:

  • Loop through the main application list
  • For every application, check if the selected skills array is a subset of the application list's skills array
  • If that application contains all of the selected skills, then add it to the new 
    filteredAppList
    array

To envision this better, remember what the data looks like:

// example of 2 applications in appSkills
appSkills = [
  {
    id: 4,
    app: 'a blog',
    skills: [1, 3, 5]
  },
  {
    id: 5,
    app: 'a shopping cart',
    skills: [1, 3, 4]
  },
]

// example of selectedSkills
selectedSkills = [1, 5]

// result after filtering
filteredAppList = [
  {
    id: 4,
    app: 'a blog',
    skills: [1, 3, 5]
  }
];

In this case, 

filteredAppList
should be 
{ id: 4, app: 'a blog', skills: [1, 3, 5]}
because that is the only application that contains all of the selected skills.

Update 

setup
as follows:

setup() {
  const GENERATOR_BASE = 'http://localhost:3000';
  const skillList = ref([]);
  const selectedSkills = ref([]);
  const filteredAppList = ref([]);
  let appList = [];

  // 👇 new code
  function generateFilteredAppList() {
    filteredAppList.value = [];

    for (const app of appList) {
      const appSkillsArray = app.skills;
      const selectedSkillsArray = selectedSkills.value;

      if (hasAllSkills(appSkillsArray, selectedSkillsArray)) {
        filteredAppList.value.push(app);
      }
    }
  }

  // 👇 new code
  function hasAllSkills(appSkills, selectedSkills) {
    return selectedSkills.every(f => appSkills.includes(f));
  }

  async function getSkillList() {
    const response = await fetch(`${GENERATOR_BASE}/skills`);
    skillList.value = await response.json();
  }

  async function getAppList() {
    const response = await fetch(`${GENERATOR_BASE}/apps`);
    appList = await response.json();
    filteredAppList.value = appList;
  }

  getSkillList();
  getAppList();

  return {
    skillList,
    selectedSkills,
    filteredAppList,
    generateFilteredAppList   // 👈 new code
  }
}

First, you're looping through every item in the 

appList
array. For each item, you're checking if the all the selected skills are contained in that application's 
skills
array. This is done by combining Javascript's 
.include()
and 
.every()
.

.every()
— The 
every()
method tests whether all elements in the array pass the test implemented by the provided function. It returns a Boolean value.

.includes()
— The 
includes()
method determines whether an array includes a certain value among its entries. It returns true or false.

For every application option, you're running it through the checker function, 

hasAllSkills()
, which returns true or false. If the value is true, then you push it onto the 
filteredAppList
array.

Make sure you also create the 

filteredAppList
ref and include 
filteredAppList
and 
generateFilteredAppList
in the return object.

Now that you've gotten through that fun filtering function (😅), it's time to display it in the template!

Update your template as follows:

<template>
<div class="generator">
  <section class="hero is-primary is-bold has-text-centered py-6">
    <div class="hero-body">
      <div class="container">
        <h1 class="title">
        What skills do you want to work on?
        </h1>
        <div v-for="skill in skillList" :key="skill.id">
          <div class="field">
            <label class="checkbox">
              <input type="checkbox" :value="skill.id">
              {{ skill.skill }}
            </label>
          </div>
        </div>
      </div>
    </div>
  </section>

  <!-- 👇 new code -->
  <div class="container">
    <div class="columns is-multiline mt-3">
      <div v-for="app in filteredAppList" :key="app.id" class="column is-one-third">
        <div class="card">
          <header class="card-header">
            <p class="card-header-title is-uppercase is-size-5">
              {{ app.app }}
            </p>
          </header>
          <div class="card-content">
            <div class="content has-text-left mb-4">   
              <p class="is-size-7">{{ app.instructions }}</p>    
              <h4>Skills:</h4>
              <ul v-for="skill in app.skills" :key="skill.id">
                <li>
                  <strong>{{ skillList[skill-1].skill }}</strong>
                </li>
              </ul>
            </div>
          </div>
        </div>
      </div>
    </div>
  </div>
  <!-- ☝️ end new code -->
</div>
</template>

Here, you're looping through the 

filteredAppList
to display each skill that the application utilizes. You're also showing the resource link that is included for that skill. You'll notice though, when you click on some checkboxes, nothing happens. That's because you're never calling the 
generateFilteredAppList
function.

Update the input to call 

generateFilteredAppList
whenever any checkbox is clicked:

<input
  type="checkbox"
  v-model="selectedSkills"
  :value="skill.id"
  @change="generateFilteredAppList"
>

Now, if you click on some checkboxes, you should see the application options updating immediately!

You can fix the card styling by adding the following to the component styles:

<style scoped>
  label {
    font-size: 20px;
  }
  /* 👇 new code */
  .card {
    height: 100%;
  }
</style>

Create a filter to display a random option

This brings us to the final item on the agenda: create a Vue filter to display a random option from the skill list for each application option.

You want to give the user as much direction as possible, so instead of just listing the skill, you're going to include what service or resource they should use to accomplish it. So, you need to pseudo-randomly grab one of the skill options and display it.

So how do you do that? Well, it's a bit of a trick question.

Here's the problem: filters were removed in Vue 3!

In Vue 2, you could create a filter and add the pipe symbol to use it in your template, like this:

<p><strong>{{ skillList[skill-1].skill | random }}</strong></p>

Since this functionality was removed in Vue 3, it's recommended to just create a method instead and call that in the template.

This is what the data for the 

skillList
looks like:

// structure of skillList array
skillList = [
  { 
    id: 1, 
    skill: 'Charting',
    options: [
      'https://www.chartjs.org/',
      'https://d3js.org/',
      'https://www.highcharts.com/'
    ]
  },
  { 
    id: 2, 
    skill: 'Analytics',
    options: [
      'https://developers.google.com/analytics',
      'https://matomo.org/docs/'
    ]
  }
];

For the selected skill, you need to look into the 

options
array and randomly pick one of the items. Update 
setup
as follows:

setup() {
  const GENERATOR_BASE = 'http://localhost:3000';
  const skillList = ref([]);
  const selectedSkills = ref([]);
  const filteredAppList = ref([]);
  let appList = [];

  function generateFilteredAppList() {
    filteredAppList.value = [];

    for (const app of appList) {
      const appSkillsArray = app.skills;
      const selectedSkillsArray = selectedSkills.value;

      if (hasAllSkills(appSkillsArray, selectedSkillsArray)) {
        filteredAppList.value.push(app);
      }
    }
  }

  function hasAllSkills(appSkills, selectedSkills) {
    return selectedSkills.every(f => appSkills.includes(f));
  }

  // 👇 new code
  function getRand(value) {
    let keys = Object.keys(value);
    return value[keys[ keys.length * Math.random() << 0]];
  }

  async function getSkillList() {
    const response = await fetch(`${GENERATOR_BASE}/skills`);
    skillList.value = await response.json();
  }

  async function getAppList() {
    const response = await fetch(`${GENERATOR_BASE}/apps`);
    appList = await response.json();
    filteredAppList.value = appList;
  }

  getSkillList();
  getAppList();

  return {
    skillList,
    selectedSkills,
    filteredAppList,
    generateFilteredAppList,
    getRand   // 👈 new code
  }
}

Next, back in the template, update the skill list as follows:

<li>
  <strong>{{ skillList[skill-1].skill }}</strong>
  <p v-if="skillList[skill-1].options" :set="randSkill = getRand(skillList[skill-1].options)">
    🦮 <a :href="randSkill">{{ randSkill }}</a>
  </p>
</li>

And then add the last of the styles:

<style scoped>
  label {
    font-size: 20px;
  }
  .card {
    height: 100%;
  }
  /* 👇 new code */
  a {
    word-break: break-word;
  }
</style>

Because you need to use the random value twice (for the link and to display the skill), you're going to have to use a little "trick" here. You're creating a temporary local value that holds the current return value of 

getRand()
for this spot in the 
for
loop.

And that should do it!

Take a look at your final application, and you should now be able to filter through to find the perfect app to test your skills.

Vue 3 project generator

Wrap Up

Phew, that was... a lot. Let's recap everything that you just learned.

  • How to use the Vue 3 Composition API
  • How to call an API using Vue
  • Advanced list filtering in JavaScript
  • How to use filters in Vue 3
  • How to use Bulma with Vue

Feel free to modify the Express API to add some more skills and sample application options that interest you. If you end up building any of the practice applications, tweet me and let me know! And if you have any questions, be sure to leave them down below. Thanks for reading!