<p>Creating a handful of components to render the data that loaded from a JSON file was covered in the <a href="/posts/2022/first-rudimentary-mercenary-components/">previous post</a>. It can feel a little defeating to just have a dump of content without any style to it. This step of the tutorial will cover implementing TailwindCSS to our project and adding some basic styling.</p>
<p><img src="/images/hsmercs-banner-varden.png" alt="No one is as pretty as Varden"></p>
<blockquote>
<p>The fourth in a series of posts on <a href="/series/hsmercs-from-scratch">'HSMercs Helper From Scratch'</a>, a tutorial for recreating <em><a href="https://hsmercs.rovani.net">HSMercs Helper</a></em>.</p>
</blockquote>
<p>The native <a href="https://tailwindcss.com/docs/guides/vite">tutorial for installing</a> Tailwind CSS with Vue 3 and Vite is straightforward and easy to follow. Most of what you'll see in this post is following the steps in that post.</p>
<pre><code class="language-bash">yarn add -D tailwindcss postcss autoprefixer
</code></pre>
<p><em><a href="https://postcss.org/">PostCSS</a></em> is a tool for transforming styles with JS plugins. These plugins can lint the CSS, support variables and mixins, transpile future CSS syntax, create inline images, and more. The <em><a href="https://github.com/postcss/autoprefixer">Autoprefixer</a></em> plugin parses CSS and adds vendor prefixes to CSS rules using values from <em><a href="https://caniuse.com/">Can I Use</a></em>. Together, these provide the functionality that Tailwind uses to pump out the CSS we need it to.</p>
<p>The official tutorial now instructs you to run the command <code>yarn tailwindcss init -p</code> which creates a <code>postcss.config.js</code> file for <em>PostCSS</em> configuration and a <code>tailwind.config.js</code> file for Tailwind specific configuration.</p>
<h4>postcss.config.js</h4>
<pre><code class="language-js">module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};
</code></pre>
<p>This tells <em>PostCSS</em> to utilize the <code>tailwindcss</code> and <code>autoprefixer</code> plugins.</p>
<h4>tailwind.config.js</h4>
<pre><code class="language-js">module.exports = {
  content: ["./index.html", "./src/**/*.{vue,ts}"],
  theme: {
    extend: {},
  },
  plugins: [],
};
</code></pre>
<p>Additional configuration is provided to <em>TailwindCSS</em> informing it to parse the root <code>/index.html</code> file and all <code>.vue</code> and <code>.ts</code> files anywhere under the <code>src</code> folder.</p>
<h4>src/index.css</h4>
<pre><code class="language-css">@tailwind base;
@tailwind components;
@tailwind utilities;
</code></pre>
<p>These three layers are where PostCSS and Autoprefixer inject the styles that Tailwind generates.</p>
<h4>src/main.ts</h4>
<pre><code class="language-diff">  import { createApp } from 'vue'
  import App from './App.vue'
+ import './index.css'
  import { store } from './store'
  
  
  createApp(App)
      .use(store)
      .mount('#app')
</code></pre>
<p>The main script file loads the Tailwind generates CSS file into the full app. All of the magic happens behind the scenes, so we won't go into the details on how or why this happens. We're just happy it works.</p>
<h4>src/App.vue</h4>
<pre><code class="language-diff">  &#x3C;template>
+   &#x3C;header class="ml-4 p-4 rounded-bl-md border-l-2 border-b-2">
+     &#x3C;div class="text-2xl font-extrabold">HSMercs Helper&#x3C;/div>
+     &#x3C;div class="font-light">A set of tools for Hearthstone Mercenaries players.&#x3C;/div>
    &#x3C;/header>
    &#x3C;Mercenaries>&#x3C;/Mercenaries>
  &#x3C;/template>
</code></pre>
<p>This applies a little styling to the header section of the app. Eventually, we will be putting navigation to different tools up there, so it is nice to give it some visual separation.</p>
<h4>src/components/Mercenaries.vue</h4>
<pre><code class="language-diff">&#x3C;template>
  &#x3C;section>
+   &#x3C;h1 class="text-xl mx-8">Collectable Mercenaries&#x3C;/h1>
+   &#x3C;div class="flex flex-wrap gap-2 px-2">
      &#x3C;MercenaryCard
        v-for="(merc, mercName) in mercenaries"
        :key="mercName"
        v-bind="merc"
        >{{ mercName }}
      &#x3C;/MercenaryCard>
    &#x3C;/div>
  &#x3C;/section>
&#x3C;/template>
</code></pre>
<p>When there is a set of cards, and we don't particularly care how many are in a row, the best case is to use <code>flex</code> on the container, instructing the browser to place entries next to each other, and wrap (<code>flex-wrap</code>) onto the next line when the block element won't fit in the viewport. <code>px-2</code> means to put a small padding on the left and right side of the container and <code>gap-2</code> instructs flex to keep a small space between elements.</p>
<pre><code class="language-bash">yarn dev
</code></pre>
<p><img src="/images/hsmercs-mercstyled.png" alt="A little style!"></p>
<p>One of this first things I panicked on when I first installed Tailwind was that all of my text was suddenly the same size. What did I screw up?!</p>
<p>Well, fear not; this is intentional. The directive <code>@tailwind base</code> contains reset rules (called <a href="https://tailwindcss.com/docs/preflight">Preflight</a>)that clear all of the browser defaults. Since each browser has slightly different default stylying, the first thing Tailwind does is strip it all out.</p>
<h2>Style Some More Components</h2>
<p>Most of the styling is going to be inside the Mercenary Card or one of its children. We can start by throwing around a couple classes and seeing what happens. Now is a good time to experiment and see what you like. This first pass doesn't involve adding any color or images, it is strictly to improve readability of the basic content.</p>
<h4>src/components/MercenaryCard.vue</h4>
<pre><code class="language-diff">&#x3C;template>
  &#x3C;div
+   class="grid grid-rows-3 w-96 rounded-md border-2 gap-y-1 pb-1"
  >
    &#x3C;div>
      &#x3C;div
+       class="flex justify-between px-2 py-1 text-white bg-gray-700"
      >
+       &#x3C;h2 class="font-bold text-xl whitespace-nowrap">
          &#x3C;slot />
        &#x3C;/h2>
      &#x3C;/div>
+     &#x3C;div class="grid grid-cols-5 justify-around place-items-center px-2">
        &#x3C;Attack :role="role" :attack="attack" />
        &#x3C;Tribe :tribe="tribe" />
        &#x3C;Health :role="role" :health="health" />
+       &#x3C;Rarity class="col-span-2" :rarity="rarity" />
      &#x3C;/div>
    &#x3C;/div>
+   &#x3C;div class="grid grid-cols-3 gap-x-1">
      &#x3C;AbilityStamp
        v-for="(ability, abilityName) in abilities"
        :key="abilityName"
        :ability="ability"
        class="rounded"
        >{{ abilityName }}
      &#x3C;/AbilityStamp>
    &#x3C;/div>
+   &#x3C;div class="grid grid-cols-3 gap-x-1">
      &#x3C;ItemStamp
        v-for="(item, itemName) in equipment"
        :key="itemName"
        :item="item"
        >{{ itemName }}
      &#x3C;/ItemStamp>
    &#x3C;/div>
  &#x3C;/div>
&#x3C;/template>
</code></pre>
<p><strong>This right here</strong> is why I think CSS is so frickin' cool. We made a small adjustment to the CSS and BOOM, it looks so incredibly different. I get excited when I start seeing things really begin to take shape.</p>
<p>I hope you're getting excited, too.</p>
<p><img src="/images/hsmercs-mercs-level1styled.png" alt="HS Mercs - adding style to the MercenaryCard"></p>
<p>Let's do a some touch-up here and there by going into some of the components and applying a little style.</p>
<h4>src/components/AbilityStamp.vue</h4>
<pre><code class="language-diff">&#x3C;template>
+ &#x3C;div class="border rounded text-sm sm:text-base text-center">
    &#x3C;slot />
  &#x3C;/div>
&#x3C;/template>
</code></pre>
<h4>src/components/Attack.vue</h4>
<pre><code class="language-diff">&#x3C;template>
+ &#x3C;div class="text-center font-bold w-10 h-10 text-xl p-2">
    {{ attack }}
  &#x3C;/div>
&#x3C;/template>
</code></pre>
<h4>src/components/Health.vue</h4>
<pre><code class="language-diff">&#x3C;template>
+ &#x3C;div class="text-center font-bold w-10 h-10 text-xl p-2">
    {{ health }}
  &#x3C;/div>
&#x3C;/template>
</code></pre>
<h4>src/components/ItemStamp.vue</h4>
<pre><code class="language-diff">&#x3C;template>
+ &#x3C;div class="border rounded text-sm sm:text-base text-center">
    &#x3C;slot />
  &#x3C;/div>
&#x3C;/template>
</code></pre>
<h4>src/components/Tribe.vue</h4>
<pre><code class="language-diff">&#x3C;template>
+ &#x3C;div class="whitespace-nowrap text-center">
+   &#x3C;span class="align-middle">{{ tribe }}&#x3C;/span>
  &#x3C;/div>
&#x3C;/template>
</code></pre>
<p>Those little touches don't add much, but they set us to for the next stage in styling, which is to start having fun with dynamic colors and images based on properties of the mercenary.</p>
<p><img src="/images/hsmercs-mercs-level2styled.png" alt="HSMercs - level 2 shaping"></p>
<h2>Time For Some Images</h2>
<p>All this grey and white and boxes is getting boring. The excitement is starting to wear off. Time to add some pictures into this. Head over to the repo for this project and download the images from the <a href="https://github.com/drovani/hsmercs-helper/tree/main/assets">"/assets/" folder</a>. It's safe to grab all of the images in that folder, but if you want to be selective, these are the ones we are going to work with first.</p>
<h4>Assets Folder</h4>
<pre><code>├── assets
│   ├── alliance-watermark.png
│   ├── caster-attack.png
│   ├── caster-health.png
│   ├── epic.png
│   ├── fighter-attack.png
│   ├── fighter-health.png
│   ├── horder-watermark.png
│   ├── legendary.png
│   ├── neutral-attack.png
│   ├── neutral-health.png
│   ├── protector-attack.png
│   ├── protector-health.png
│   ├── rare.png
</code></pre>
<p>Be sure to place the <code>assets</code> folder at the root.</p>
<h4>src/components/Attack.vue</h4>
<pre><code class="language-diff">&#x3C;template>
  &#x3C;div
+   class="bg-center bg-contain bg-no-repeat text-center font-bold text-white w-10 h-10 text-xl p-2"
+   :style="{
+     'background-image': `url('/assets/${role.toLowerCase()}-attack.png')`,
+   }"
  >
    {{ attack }}
  &#x3C;/div>
&#x3C;/template>
</code></pre>
<h4>src/components/Health.vue</h4>
<pre><code class="language-diff">&#x3C;template>
  &#x3C;div
+   class="bg-center bg-contain bg-no-repeat text-center font-bold text-white w-10 h-10 text-xl p-2"
+   :style="{
+     'background-image': `url('/assets/${role.toLowerCase()}-health.png')`,
+   }"
  >
    {{ health }}
  &#x3C;/div>
&#x3C;/template>
</code></pre>
<p>If you've left the <code>vite</code> server running, your place should be autorefreshing with the new content when you save the Vue files. If not, go ahead and start it up, now. You can see how the affect of the <code>role</code> property plays out by dynamically setting the URL of the background image.</p>
<h4>src/components/Rarity.vue</h4>
<pre><code class="language-diff">&#x3C;template>
  &#x3C;div>
+   &#x3C;img
+     class="max-h-6 inline"
+     :src="`./assets/${rarity.toLowerCase()}.png`"
+     :alt="rarity"
+   />
    {{ rarity }}
  &#x3C;/div>
&#x3C;/template>
</code></pre>
<p>Tailwind's Preflight sets the <code>img</code> to <code>display:block</code>, so we need to set it back to <code>inline</code> for this instance. The <code>max-h-6</code> is there to keep the image contained. We could also set an explicit height or width, but I prefer telling it the maximum allowed size and if the container shrinks, then the image will scale, too.</p>
<p><img src="/images/hsmercs-mercs-level2images.png" alt="HSMercs - level 2 images"></p>
<h3>Tailwind Custom Colors</h3>
<p>The next style we are going to implement is to color the border and the top bibbon of each card based on the class. Looking through Tailwind's <a href="https://tailwindcss.com/docs/customizing-colors#default-color-palette">default color palette</a>, the colors red-800, green-800, and blue-800 seem to nicely fit with the Mercenaries color palette. However, instead of having to remember which color we picked for each class, and which shade is the right one, Tailwind allows us to create custom named colors.</p>
<h4>tailwind.config.js</h4>
<pre><code class="language-diff">+ const colors = require("tailwindcss/colors");
  
  module.exports = {
    content: ["./index.html", "./src/**/*.{vue,ts}"],
    theme: {
      extend: {
+       colors: {
+         protector: colors.red[800],
+         fighter: colors.green[800],
+         caster: colors.blue[800],
+       },
      },
    },
    plugins: [],
  };
</code></pre>
<p>The Tailwind compiler (and the VSCode Intellisense) now know that "protector", "fighter", and "caster" are valid colors.</p>
<h4>src/components/MercenaryCard.vue</h4>
<pre><code class="language-diff">&#x3C;template>
  &#x3C;div
    class="grid grid-rows-3 w-96 rounded-md border-2 gap-y-1 pb-1"
+   :class="{
+     'border-protector': role == 'Protector',
+     'border-fighter': role == 'Fighter',
+     'border-caster': role == 'Caster',
+   }"
  >
    &#x3C;div>
      &#x3C;div
        class="flex justify-between px-2 py-1 text-white bg-gray-700"
+       :class="{
+         'bg-protector': role == 'Protector',
+         'bg-fighter': role == 'Fighter',
+         'bg-caster': role == 'Caster',
+       }"
      >
        &#x3C;h2 class="font-bold text-xl whitespace-nowrap">
          &#x3C;slot />
        &#x3C;/h2>
      &#x3C;/div>
...
    &#x3C;/div>
...
  &#x3C;/div>
&#x3C;/template>
</code></pre>
<p>How cool is that?! Using the <code>role</code> prop, Vue assigns the right border and background class to use. Tailwind knows to generate the appropriate CSS class to match the colors we want.</p>
<h3>Tribe &#x26; Faction</h3>
<p>There is a concept in Mercenaries PVE where some tribes are a part of the "Alliance" faction, others are in the "Horde", and the rest are neutral or without a faction. Instead of doing a long set of logic in the <code>&#x3C;template></code> block, we'll create a <code>computed</code> property that will evaluate the faction based on the mercenary's tribe.</p>
<h4>src/components/Tribe.vue</h4>
<pre><code class="language-diff">  &#x3C;template>
    &#x3C;div
+     class="bg-center bg-no-repeat bg-contain h-10 whitespace-nowrap min-w-[6rem] text-center"
+     :style="{
+       'background-image': backgroundImage,
+     }"
    >
      &#x3C;span class="align-middle">{{ tribe }}&#x3C;/span>
    &#x3C;/div>
  &#x3C;/template>
  &#x3C;script setup lang="ts">
+ import { computed } from "vue";

  const props = defineProps({
    tribe: {
      type: String,
    },
  });

+ const horde = ["Blood Elf", "Goblin", "Half-Orc", "Orc", "Tauren", "Troll", "Undead"];
+ const alliance = ["Draenei", "Dwarf", "Gnome", "High Elf", "Human", "Night Elf"];
+ 
+ const faction = computed(() => {
+   return horde.find(t => t === props.tribe)
+     ? "Horde"
+     : alliance.find(t => t === props.tribe)
+     ? "Alliance"
+     : "Neutral";
+ });

+ const backgroundImage = computed((): string => {
+   if (faction.value === "Horde" || faction.value === "Alliance") {
+     return `url('/assets/${faction.value.toLowerCase()}-watermark.png')`;
+   }
+   return "unset";
+ });
  &#x3C;/script>
</code></pre>
<p>The two arrays tell us which tribes are in which factions and the <code>faction</code> computed property does a quick look-up. We then utilize that value to drive the <code>background-image</code> style for the <code>div</code>.</p>
<p><img src="/images/hsmercs-mercs-level1dynamic.png" alt="HSMercs - Round 1 Styling Complete"></p>


Adding Some Style

<p>In the previous step, we took the first pass at the Vuex store by creating a <code>getter</code> and a <code>mutation</code> to interact with the <code>state</code>. For the next step, we will load the data and create and initial round of components to render the data to the client.</p>
<p><img src="/images/hsmercs-banner-alexstrasza.png" alt="Alexstrasza is alphabetically first"></p>
<blockquote>
<p>The third in a series of posts on <a href="/series/hsmercs-from-scratch">'HSMercs Helper From Scratch'</a>, a tutorial for recreating <em><a href="https://hsmercs.rovani.net">HSMercs Helper</a></em>.</p>
</blockquote>
<h2>Minimum Renderable Mercenaries</h2>
<p>There are a lot of directions that we could go to get something renderable. The goal is to have as little "temporary" code that is in place just to have <em>something</em> display, which then gets deleted or overwritten later.</p>
<h4>static/mercenaries.json</h4>
<pre><code class="language-json">{
    "mercenaries": {
        "Alexstrasza": {
            "role": "Protector",
            "rarity": "Legendary",
            "tribe": "Dragon",
            "attack": 7,
            "health": 76,
            "abilities": {
                "Dragon Breath": {},
                "Flame Buffet": {},
                "Dragonqueen's Gambit": {}
            },
            "equipment": {
                "Dragonflight Talisman": {},
                "Alexstrasza's Brooch": {},
                "Amulet of Swiftness": {}
            },
            "tasks": [
                {}
            ]
        }
    }
}
</code></pre>
<p>This JSON sample is a minimal view of what the entire file looks like. The complete <a href="https://raw.githubusercontent.com/drovani/hsmercs-helper/main/src/static/mercenaries.json">mercenaries.json</a> file can be found at the Github repo for the HSMercs Helper project, and I suggest you download that to the <code>src/static</code> folder. At 18,000+ lines of JSON, it is a sizable file.</p>
<h4>src/components/Mercenaries.vue</h4>
<pre><code class="language-vue">&#x3C;template>
  &#x3C;section>
    &#x3C;h1>Collectable Mercenaries&#x3C;/h1>
    &#x3C;div>
      &#x3C;MercenaryCard
        v-for="(merc, mercName) in mercenaries"
        :key="mercName"
        v-bind="merc"
        >{{ mercName }}
      &#x3C;/MercenaryCard>
    &#x3C;/div>
  &#x3C;/section>
&#x3C;/template>
&#x3C;script lang="ts">
import { defineComponent } from "vue";
import { MercCollection } from "../models/mercCollection";
import mercjson from "../static/mercenaries.json";
import { SET_MERCENARIES } from "../store/types";

export default defineComponent({
  computed: {
    mercenaries(): MercCollection {
      return this.$store.getters.getMercenaries;
    },
  },
  mounted(): void {
    if (Object.keys(this.mercenaries ?? {}).length === 0) {
      this.$store.commit(SET_MERCENARIES, mercjson.mercenaries);
    }
  },
});
&#x3C;/script>
</code></pre>
<p>We have created a component that, when it is mounted, will check to see if there is data in the <code>store</code> and if not, commit a write. The computed property <code>mercenaries</code> returns an object that looks like a <code>MercCollection</code> and retrieves it from the store. The component iterates over the collection and renders a <code>MercenaryCard</code> component.</p>
<h4>tsconfig.json</h4>
<pre><code class="language-diff">{
    "compilerOptions": {
        "module": "CommonJS",
        "moduleResolution": "Node",
        "esModuleInterop": true,
+       "resolveJsonModule": true,
    },
    "exclude": [
        "./node_modules/",
        "./dist/"
    ]
}
</code></pre>
<p>TypeScript allows for importing modules with a '.json' extension, which is common practice in Node projects. To <a href="https://www.typescriptlang.org/tsconfig#resolveJsonModule">enable this option</a>, though, we need to update the configuration file. TypeScript's reasoning for explicitly enabling this is because it can result in memory intensive delays if the JSON file is too large or complicated. By forcing a developer to opt-in, the presumption is that the developer understands these risks.</p>
<h4>src/main.ts</h4>
<pre><code class="language-diff">  import { createApp } from 'vue'
  import App from './App.vue'
+ import { store } from './store'


createApp(App)
+   .use(store)
    .mount('#app')

</code></pre>
<p>While we had created the Vuex store, we haven't yet made it available to the Vue application. Popping it in like this is the easiest way to get it globally accessible. Vue and Vuex work together to make the store available as a <code>$store</code> property on every component.</p>
<h4>src/env.d.ts</h4>
<pre><code class="language-diff">  /// &#x3C;reference types="vite/client" />
  
+ import { DefineComponent } from 'vue'
+ import { Store } from 'vuex'
+ import { State } from './store/state'
  
  declare module '*.vue' {
      // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/ban-types
      const component: DefineComponent&#x3C;{}, {}, any>
      export default component
  }
  
+ declare module '@vue/runtime-core' {
+     interface ComponentCustomProperties {
+         $store: Store&#x3C;State>
+     }
+ }
</code></pre>
<p>This is another one of those Tooling Updates that occassionally needs to be added so TypeScript doesn't freak out whenever it sees <code>this.$store</code> in the code. All components extend the <code>ComponentCustomProperties</code> interface that Vue exposes through the <code>@vue/runtime-core</code> module. Because TypeScript allows interfaces to be extended by just redeclaring it, developers are able to describe the custom properties of components by building on this interface. Thus, we can inform TypeScript that <code>$store</code> is an instance of the <code>Store&#x3C;State></code> that we created (found in "src/store/index.ts").</p>
<h4>src/App.vue</h4>
<pre><code class="language-diff">  &#x3C;script setup lang="ts">
+ import Mercenaries from "./components/Mercenaries.vue";
  &#x3C;/script>
  
  &#x3C;template>
    &#x3C;header>
      &#x3C;div>HSMercs Helper&#x3C;/div>
      &#x3C;div>A set of tools for Hearthstone Mercenaries players.&#x3C;/div>
    &#x3C;/header>
+   &#x3C;Mercenaries>&#x3C;/Mercenaries>
  &#x3C;/template>
</code></pre>
<p>Now that the <code>Mercenaries</code> component has been built, the <code>App</code> component needs to be informed of it and told where to place it. And that's it!</p>
<h4>src/components/MercenaryCard.vue</h4>
<pre><code class="language-vue">&#x3C;template>
  &#x3C;h2>
    &#x3C;slot />
  &#x3C;/h2>
&#x3C;/template>
&#x3C;script lang="ts">
import { defineComponent } from "vue";

export default defineComponent({
  props: {
    role: String,
    tribe: String,
    rarity: String,
    attack: Number,
    health: Number,
    abilities: Object,
    equipment: Object,
    tasks: Array,
  }
});
&#x3C;/script>
</code></pre>
<p>Since we already know what properties are coming with each <code>Mercenary</code>, we can create the components props right away.</p>
<pre><code class="language-bash">yarn test
yarn dev
</code></pre>
<p>Now is a good time to validate that everything works. We should now have a list of all of the mercenaries!</p>
<p><img src="/images/hsmercs-mercnames.png" alt="HSMercs Helper - Mercenaries, plus the names of all the mercs"></p>
<h3>Lots of New Components!</h3>
<p>It can be important to develop a common language when creating sets of components so that future developers (including yourself) know the purpose of everything that is developed. Otherwise, components may get remade as teams forget what is out there and end up recreating existing functionality.</p>
<ul>
<li><code>[Component].vue</code> is for an atomic piece of data or presentation element.</li>
<li><code>[Component]Stamp.vue</code> is a small version of a data object. It doesn't have an much information as a full details view would, but it isn't useful to stand alone.</li>
<li><code>[Component]Card.vue</code> displays a compact set of information, made up of multiple <code>Component</code> or <code>ComponentStamp</code> components.</li>
<li><code>[Component]Details.vue</code> contains an indepth display of the object, consiting of <code>Component</code>, <code>ComponentStamp</code>, and perhaps some <code>ComponentCard</code> components.</li>
</ul>
<h4>src/components/Role.vue</h4>
<pre><code class="language-vue">&#x3C;template>
  &#x3C;div>
    {{ role }}
  &#x3C;/div>
&#x3C;/template>

&#x3C;script lang="ts">
import { defineComponent } from "vue";

export default defineComponent({
  props: {
    role: {
      type: String,
      required: true,
    },
  },
});
&#x3C;/script>
</code></pre>
<p>There are going to be a lot of components that all look extremely similar. There is a single <code>div</code> that holds the one <code>prop</code> being passed to the component. We specify the <code>type</code> of the <code>prop</code> and whether it is required. By having all of these as individual components now, we will be able to add styling, computation, and features in the future without having to refactor the parent component by extracting this information later.</p>
<h4>src/components/Tribe.vue</h4>
<pre><code class="language-vue">&#x3C;template>
  &#x3C;div>
    {{ tribe }}
  &#x3C;/div>
&#x3C;/template>

&#x3C;script setup lang="ts">
defineProps({
  tribe: {
    type: String,
    required: true,
  },
});
&#x3C;/script>
</code></pre>
<h4>src/components/Rarity.vue</h4>
<pre><code class="language-vue">&#x3C;template>
  &#x3C;div>
    {{ rarity }}
  &#x3C;/div>
&#x3C;/template>

&#x3C;script setup lang="ts">
defineProps({
  rarity: {
    type: String,
    require: true,
  },
});
&#x3C;/script>
</code></pre>
<h4>src/components/Attack.vue</h4>
<pre><code class="language-vue">&#x3C;template>
  &#x3C;div>
    {{ attack }}
  &#x3C;/div>
&#x3C;/template>

&#x3C;script lang="ts">
import { defineComponent } from "vue";

export default defineComponent({
  props: {
    attack: {
      type: Number,
      required: true,
    },
    role: {
      type: String,
      default: "Neutral",
    },
  },
});
&#x3C;/script>
</code></pre>
<p>The <code>attack</code> and <code>health</code> components will also accept a <code>role</code> string <code>prop</code> because we know there will be different styling based on that value. In order to accomodate non-mercenaries (i.e. summoned minions), the <code>prop</code> comes with a default value. It is better to specify the default value in the component than expect all consumers of the component to remember to set and spell a default correctly.</p>
<h4>src/components/Health.vue</h4>
<pre><code class="language-vue">&#x3C;template>
  &#x3C;div>
    {{ health }}
  &#x3C;/div>
&#x3C;/template>

&#x3C;script lang="ts">
import { defineComponent } from "vue";

export default defineComponent({
  props: {
    health: {
      type: Number,
      required: true,
    },
    role: {
      type: String,
      default: "Neutral",
    },
  },
});
&#x3C;/script>
</code></pre>
<h3>Stub Components</h3>
<p>The <code>ability</code> and <code>item</code> components will be the most complicated components. They have descriptions, tiers of affects, different ways equipped items affect abilities, and other features that will get added piecemeal. However, in order to get to our Minimum Renderable Mercenary, the first pass is just going to display the name of the ability and item.</p>
<h4>src/components/AbilityStamp.vue</h4>
<pre><code class="language-vue">&#x3C;template>
  &#x3C;div>
    &#x3C;slot />
  &#x3C;/div>
&#x3C;/template>

&#x3C;script lang="ts">
import { defineComponent } from "vue";

export default defineComponent({
  props: {
    ability: {
      type: Object,
      required: true,
    },
  },
});
&#x3C;/script>
</code></pre>
<h4>src/components/ItemStamp.vue</h4>
<pre><code class="language-vue">&#x3C;template>
  &#x3C;div>
    &#x3C;slot />
  &#x3C;/div>
&#x3C;/template>

&#x3C;script lang="ts">
import { defineComponent } from "vue";

export default defineComponent({
  props: {
    item: {
      type: Object,
      require: true,
    },
  },
});
&#x3C;/script>
</code></pre>
<h3>Displaying Mercenary Data</h3>
<p>All of the initial components have now been built. Heading back to the mercenary card component, we import each of these components and give them a place.</p>
<h4>src/components/MercenaryCard.vue</h4>
<pre><code class="language-vue">&#x3C;template>
  &#x3C;div>
    &#x3C;div>
      &#x3C;div>
        &#x3C;h2>
          &#x3C;slot />
        &#x3C;/h2>
        &#x3C;Role :role="role" />
      &#x3C;/div>
      &#x3C;div>
        &#x3C;Attack :role="role" :attack="attack" />
        &#x3C;Tribe v-if="tribe" :tribe="tribe" />
        &#x3C;Health :role="role" :health="health" />
        &#x3C;Rarity :rarity="rarity" />
      &#x3C;/div>
    &#x3C;/div>
    &#x3C;div>
      &#x3C;AbilityStamp
        v-for="(ability, abilityName) in abilities"
        :key="abilityName"
        :ability="ability"
        >{{ abilityName }}
      &#x3C;/AbilityStamp>
    &#x3C;/div>
    &#x3C;div>
      &#x3C;ItemStamp
        v-for="(item, itemName) in equipment"
        :key="itemName"
        :item="item"
        >{{ itemName }}
      &#x3C;/ItemStamp>
    &#x3C;/div>
  &#x3C;/div>
&#x3C;/template>
&#x3C;script lang="ts">
import { defineComponent } from "vue";
import AbilityStamp from "./Ability.vue";
import Attack from "./Attack.vue";
import Health from "./Health.vue";
import ItemStamp from "./Item.vue";
import Rarity from "./Rarity.vue";
import Role from "./Role.vue";
import Tribe from "./Tribe.vue";

export default defineComponent({
  props: {
    role: String,
    tribe: String,
    rarity: String,
    attack: Number,
    health: Number,
    abilities: Object,
    equipment: Object,
    tasks: Array,
  },
  components: {
    AbilityStamp,
    Attack,
    Health,
    ItemStamp,
    Rarity,
    Role,
    Tribe,
  },
});
&#x3C;/script>
</code></pre>
<p>Everything is in place. Save the files and start the dev server back up!</p>
<pre><code class="language-bash">yarn dev
</code></pre>
<p><img src="/images/hsmercs-mercprops.png" alt="HSMercs - Mercenaries and more data"></p>
<h2>Step 4: <a href="/posts/2022/adding-some-style/">Adding Some Style</a></h2>
<p>The output is boring to look at and requires a very long scroll. Let's add some styling to this project using <a href="https://tailwindcss.com/">Tailwind CSS</a>.</p>


First Rudimentary Mercenary Components

<p>In the previous post, we built a Minimum Renderable Vue application - which is to say that it outputs text in the browser using Vue, Vite, and TypeScript. Most tutorials would now build on that by creating components and output content using temporary hard-coded data. Instead, this tutorial is going to go in the direction of loading real data, which we will then build components around. I think this is more in line with real-world applications, where you know what the general shape of the data looks like (or at least what the domain is) and getting it loaded into the app is a good first lift.</p>
<p><img src="/images/hsmercs-banner-gruul.png" alt="Gruul is a jerk"></p>
<blockquote>
<p>The second in a series of posts on <a href="/series/hsmercs-from-scratch">'HSMercs Helper From Scratch'</a>, a tutorial for recreating <em><a href="https://hsmercs.rovani.net">HSMercs Helper</a></em>.</p>
</blockquote>
<h2>Building an Extensible Vuex Store</h2>
<p><a href="https://vuex.vuejs.org/">Vuex</a> is the defacto standard state management pattern and library for Vue.js applications. It was created by the Vue core team, the repo is in their Github, and the website is hosted under the <code>vuejs.org</code> domain. There are other state libraries out there, but this website isn't complicated enough to need to branch out into something with <em>even more</em> features.</p>
<pre><code class="language-bash">yarn add vuex@^4 typescript@^4 @types/node
</code></pre>
<p>Add Vuex v4 and TypeScript v4 as dependencies and install them. Prior <code>.ts</code> files we created didn't have any TypeScript nomenclature, so the library wasn't required. Since the Vuex parts that we are about to create will be using strong typing, we need to do some transpiling. The <code>@types/node</code> library brings in TypeScript definitions for Node.</p>
<h4>tsconfig.json</h4>
<pre><code class="language-json">{
    "compilerOptions": {
        "module": "esnext",
        "moduleResolution": "Node",
        "esModuleInterop": true
    },
    "exclude": [
        "./node_modules/",
        "./dist/"
    ]
}
</code></pre>
<p>This configuration file tells the TypeScript compiler that we want to use the "CommonJS" module, which is what is typically used for Node.js applications. The <code>moduleResolution</code> <a href="https://www.typescriptlang.org/tsconfig#moduleResolution">setting</a> is a strategy for finding the TypeScript file when an <code>import</code> is called, and the <code>esModuleInterop</code> flag fixes a <a href="https://www.typescriptlang.org/tsconfig#esModuleInterop">flawed assumption</a> in the original and default way TypeScript treats CommonJS. The excludes are there because we don't want/need the TypeScript compiler touching anything in those two folders.</p>
<p>Most of this, you'll never have to think about ever again, it's just copy/paste from project to project.</p>
<h3>Vuex Folder Structure</h3>
<pre><code>├── src
│   ├── models
│   │   ├── merCollection.ts
│   │   ├── mercenary.ts
│   ├── store
│   │   ├── getters.ts
│   │   ├── index.ts
│   │   ├── mutations.ts
│   │   ├── state.ts
│   │   ├── types.ts
├── test
│   ├── vuex
│   │   ├── getters.test.ts
│   │   ├── mutations.test.ts
</code></pre>
<p>We will be creating all of the files one at a time and this is the layout that we will use. There is a bit of future-proofing in that we are splitting the Vuex <code>store</code> into several files from the beginning; also, the unit tests are in a <code>vuex</code> subfolder and broken into separate files by the piece of the store being tested.</p>
<h3>Initial Interfaces</h3>
<p>TypeScript uses interfaces to describe the shape of data. We'll utilize two of these to get us to the minimum testable state store.</p>
<h4>src/models/mercenary.ts</h4>
<pre><code class="language-typescript">export interface Mercenary {
  role: "Protector" | "Fighter" | "Caster";
  rarity: "Rare" | "Epic" | "Legendary";
  tribe?: "Beast" | "Blood Elf" | "Demon" | "Draenei" | "Dragon" | "Dwarf" | "Elemental" | "Gnome" | "Half-Orc" | "High Elf" | "Human" | "Murloc" | "Night Elf" | "Orc" | "Pirate" | "Tauren" | "Troll" | "Undead";
  attack: number;
  health: number;
  abilities: { [name: string]: any };
  equipment: { [name: string]: any };
  tasks: any[];
}
</code></pre>
<p>The initial data model is a very simplistic view of what goes into a Mercenary in Hearthstone. All of the fields are required except for Tribe (Gruul <em>is the only merc without a tribe</em>). If/when HS adds more tribes, we'll need to add them here. The same goes for role and rarity, though it is very doubtful these will ever change.</p>
<p>In future steps, we will expand out the abilities, equipment, and tasks properties of the mercenary.</p>
<h4>src/models/mercCollection.ts</h4>
<pre><code class="language-typescript">import { Mercenary } from "./mercenary";

export interface MercCollection {
  [name: string]: Mercenary;
}
</code></pre>
<p>The whole mercenary collection is an object of an arbitrary number of <code>Mercenary</code> objects with their name as the key/property. I debated doing this as an array, but found that the application would need to retrieve mercenaries by key/name, which would have meant iterating over the array every time the app needed to fetch a specific record.</p>
<h3>Minimum Testable State Store</h3>
<p><a href="https://vuex.vuejs.org/guide/#the-simplest-store">Vuex tutorials</a> often have the following objects all crammed into one file that defines the state and store. However, any application will quickly grow to the point where it will need to be refactored for readability, so we are starting at that level of code splitting. The next growth stage of an application would be to refactor into modules, but since this is a single-purpose application, we may never need to go that far.</p>
<h4>src/store/state.ts</h4>
<pre><code class="language-typescript">import { MercCollection } from "../models/mercCollection";

export interface State {
  mercenaries: MercCollection;
}

export function state(): State {
  return {
    mercenaries: {},
  };
}
</code></pre>
<p>The global state object, at this very early stage of construction, has a single property called <code>mercenaries</code> which is a <code>MercCollection</code>. The creation of a Vuex store takes a function that returns an object, which we are defining as a <code>State</code>.</p>
<h4>src/store/getters.ts</h4>
<pre><code class="language-typescript">import { MercCollection } from "../models/mercCollection";
import { State } from "./state";

export default {
  getMercenaries(state: State): MercCollection {
    return state.mercenaries;
  },
};
</code></pre>
<p>In this <code>getters.ts</code> file, we will be exporting an object that contains a collection of functions for retrieving values from the <code>State</code> state. This will eventually include filtered getters (i.e. only Protectors) and getters for the user's collection.</p>
<h4>src/store/types.ts</h4>
<pre><code class="language-typescript">export const SET_MERCENARIES = "set_mercenaries";
</code></pre>
<p>It took me a long time to understand the point of this file and the reason for having something so seemingly pointless be created from the beginning. Since committing state changes requires passing the string name of the mutation into Vuex, extracting the name out to a strongly typed set of values allows for Intellisense and TypeScript validation support. The actual string value of <code>"set_mercenaries"</code> should never be seen anywhere in the code base.</p>
<h4>src/store/mutations.ts</h4>
<pre><code class="language-typescript">import { MercCollection } from "../models/mercCollection";
import { State } from "./state";
import { SET_MERCENARIES } from "./types";

export default {
  [SET_MERCENARIES](state: State, mercenaries: MercCollection) {
    state.mercenaries = mercenaries;
  },
};
</code></pre>
<p>Much like the <code>getters</code>, the mutations file exports an object that contains all of the ways data changes can be committed to the state. For this first mutation, <code>SET_MERCENARIES</code> (which we know becomes <code>"set_mercenaries"</code>) accepts a <code>MercCollection</code> and assigns it to the correct property in the <code>state</code> parameter.</p>
<p>In actual code that we will use in the future, a commit looks like this:</p>
<pre><code class="language-typescript">const mercs: MercCollection = {}; // load the collection
this.$store.commit(SET_MERCENARIES, mercs); // commit to state
</code></pre>
<p>We'll dig deeper into this when we build out the data loader, though.</p>
<h4>src/store/index.ts</h4>
<pre><code class="language-typescript">import { createStore, useStore } from "vuex";
import getters from "./getters";
import mutations from "./mutations";
import { state, State } from "./state";

export const store = createStore&#x3C;State>({
  state,
  getters,
  mutations,
});

export function getStore() {
  return {
    store: useStore(),
  };
}
</code></pre>
<h2>Unit Tests!</h2>
<p>Test driven development has plenty of criticisms and I'm not going to get into the pros/cons of strict TDD. I find having unit tests to be extremely useful to validating code without having to build the front-end components to see if something works. Typically, I will take a first pass at the code, then write some tests, which inevitably reveal some bugs, and then fix my code. Now that we have built a simple create and read, so let's validate it works.</p>
<pre><code class="language-bash">yarn add -D vitest happy-dom
</code></pre>
<p>This project uses a bleeding edge, "this is in development, don't use this in production" testing library called "<a href="https://vitest.dev/">vitest</a>". Vitest is built on top of Vite, thus minimizing the differences between development, production, and testing environments. It is a wonderful approach to testing and has been a delight to work with. Vitest uses Jest's/Chai's grammer for writing tests, so if you are familiar with either of those, this will seem identical.</p>
<h4>tests/vuex/getters.test.ts</h4>
<pre><code class="language-typescript">import { describe, expect, it } from "vitest";
import getters from "../../src/store/getters";
import { State } from '../../src/store/state';

describe('Mercenary Data Getters', () => {

    it('gets mercenaries collection', () => {
        // Arrange a mock State
        const state: State = {
            mercenaries: {
                "Alexstrasza": {
                    role: "Protector",
                    rarity: "Rare",
                    tribe: "Dragon",
                    attack: 10,
                    health: 80,
                    abilities: {},
                    equipment: {},
                    tasks: []
                }
            }
        };

        // Act out the getter function
        const result = getters.getMercenaries(state);

        // Assert the expected results
        expect(result).deep.equal({
            "Alexstrasza": {
                role: "Protector",
                rarity: "Rare",
                tribe: "Dragon",
                attack: 10,
                health: 80,
                abilities: {},
                equipment: {},
                tasks: []
            }
        });
    });
});
</code></pre>
<p>There's a lot going on here, so let's take it from the top. First come the imports:</p>
<ul>
<li><code>expect</code> is an assertion method that is used to validate results of operations</li>
<li><code>getters</code> is the object that has all of the ways to retrieve data from the <code>state</code></li>
<li>We will be creating a mock <code>State</code> state to validate data retrieval</li>
</ul>
<p>The <code>describe</code> function creates a "suite" (in Vitest parlance) of tests which all have the same context. A test is created with a call to <code>it</code> and a callback function with the actual testing logic.</p>
<p>Following the <a href="https://xp123.com/articles/3a-arrange-act-assert/">Arrange, Act, Assert</a> testing pattern, we first create the objects required to run the function under test. Next we execute the method and capture the result. Finally, we check that the result matches our expectations. The Vitest library's <code>expect</code> takes the result of the act portion and begins the function chain to assert the values. We call <code>deep</code> to say we want to scan all nested properties of the result and then <code>equal</code> states that the result needs to match the comparing object.</p>
<h3>Minimum Passing Test</h3>
<p>We're almost there! Just need to set-up the tooling and we'll see our test passing.</p>
<h4>package.json</h4>
<pre><code class="language-diff">    "scripts": {
        "dev": "vite",
        "build": "vite build",
+       "test": "vitest"
    }
</code></pre>
<p>This adds a new command for <code>yarn</code> to execute, which kicks off a <code>vitest</code> process. When the command launches, it scans the test files, runs the tests, and watches the test files and source files for changes. When changes are made to these watched files, <code>vitest</code> will rerun the appropriate tests. It's like <a href="https://webpack.js.org/concepts/hot-module-replacement/">Hot Module Replacement</a> for tests!</p>
<pre><code class="language-bash">yarn test
</code></pre>
<p>The one test we created should now be passing.</p>
<p><img src="/images/vitest-getters.png" alt="gets mercenaries collection passing"></p>
<h4>tests/vuex/mutations.test.ts</h4>
<pre><code class="language-typescript">import { describe, expect, it } from "vitest";
import mutations from "../../src/store/mutations";
import { State } from '../../src/store/state';
import { SET_MERCENARIES } from '../../src/store/types';

describe('Mercenary Data Mutations', () => {
    it('sets mercenaries collection', () => {
        // Arrange an initial state
        const state: State = { mercenaries: {} };

        // Act out the mutation commit
        mutations[SET_MERCENARIES](state, {
            "Alexstrasza": {
                role: "Protector",
                rarity: "Rare",
                tribe: "Dragon",
                attack: 10,
                health: 80,
                abilities: {},
                equipment: {},
                tasks: []
            }
        });

        // Assert that the object was assigned to the state
        expect(state.mercenaries).deep.equal({
            "Alexstrasza": {
                role: "Protector",
                rarity: "Rare",
                tribe: "Dragon",
                attack: 10,
                health: 80,
                abilities: {},
                equipment: {},
                tasks: []
            }
        });
    });
});
</code></pre>
<p>After the explaination of the <code>getters</code> test, the mutation is just as straightforward.</p>
<pre><code class="language-bash">yarn test
</code></pre>
<p><img src="/images/vitest-mutations.png" alt="sets mercenaries collection passing"></p>
<h2>Step 3: <a href="/posts/2022/first-rudimentary-mercenary-components/">First Rudimentary Mercenary Components</a></h2>
<p>With a central state store in place, we will now import the JSON data; and since we will have real data, we will then build the initial round of components to render it.</p>


Storing State & Unit Testing

<p>As the name of this tutorial states, we are going to start this project from nothing but an empty folder and a few globally installed packages. Each file will be artisanally crafted and explained in detail. Additionally, I am striving to make all examples additive in nature. Instead of just putting "placeholder" text and hard-coding sample data, we will mostly just be creating files and adding code.</p>
<p><img src="/images/hsmercs-banner-logo.png" alt="HSMercs Helper for Hearthstone Mercenaries"></p>
<blockquote>
<p>The first in a series of posts on <a href="/series/hsmercs-from-scratch">'HSMercs Helper From Scratch'</a>, a tutorial for recreating <em><a href="https://hsmercs.rovani.net">HSMercs Helper</a></em>.</p>
</blockquote>
<h2>Starting from Complete Scratch</h2>
<p>This (and the rest of the posts) assume that the development environment matches the following requirements:</p>
<ul>
<li>Windows 10 with WSL2: Ubuntu installed.</li>
<li>Visual Studio Code with Volar, Prettier, ESLint plugins installed.</li>
<li>Using Node v16 with yarn and vite installed.</li>
</ul>
<p>Other environments may work, but I have no way to test it, so this is what is supported!</p>
<p>Before creating anything, we need a new repository. Time to create a new directory and initialize that git repo!</p>
<pre><code class="language-bash">mkdir hsmercs-helper
cd hsmercs-helper
git init
</code></pre>
<h2>Step-by-Step Tutorial for Recreating HSMercs Helper</h2>
<p>The core starting place for any Node application is the <code>package.json</code> file. This is where Node looks to understand what to execute when you run various commands, it is where the package manager looks to determine what needs to be downloaded, and where the configuration lies for so many build and runtime utilities.</p>
<h4>package.json</h4>
<pre><code class="language-json">{
  "name": "hsmercs-helper",
  "version": "0.2.0",
  "private": true,
  "engineStrict": true,
  "engines": {
    "node": "^16"
  },
  "scripts": {
    "dev": "vite"
  },
  "dependencies": {
    "vue": "^3.2.25"
  },
  "devDependencies": {
    "vite": "^2.7.10"
  }
}
</code></pre>
<p>The first few entries describe the package by giving it a name, a version number that we set to whatever we feel like, and letting the world know that it's not meant for public consumption into other applications. We are also announcing that this package requires v16 (<code>lts/gallium</code>) of Node. There are some known issues with running on v17, so we're avoiding that version for now.</p>
<p>The <code>scripts</code> entry sets an alias for <code>yarn dev</code> to be <code>yarn vite</code>. This becomes more useful as we have longer aliases, where we want to include command line switches and conditionals.</p>
<p>The <code>dependencies</code> section and the <code>devDependencies</code> sections describe what packages are required for production and development environments.</p>
<h4>.gitignore</h4>
<pre><code class="language-text">node_modules
</code></pre>
<p>Without the <code>.gitignore</code> file, git will tell you there are 2,000+ files that need to be checked in. We don't care about anything in <code>node_modules</code>, though. After saving this file, the "to be staged" file list goes back to the three we care about.</p>
<h4>index.html</h4>
<pre><code class="language-html">&#x3C;!DOCTYPE html>
&#x3C;html lang="en">
  &#x3C;head>
    &#x3C;meta charset="UTF-8" />
    &#x3C;meta name="viewport" content="width=device-width, initial-scale=1.0" />
    &#x3C;title>HSMercs Helper&#x3C;/title>
  &#x3C;/head>
  &#x3C;body>&#x3C;/body>
&#x3C;/html>
</code></pre>
<p>Vite <a href="https://vitejs.dev/guide/#index-html-and-project-root">projects feature</a> <code>index.html</code> as front-and-central in the project root instead of being tucked away inside a <code>public</code> folder. The intention being that during development, Vite is a server and <code>index.html</code> is the entry point to the application.</p>
<h2>Minimum Renderable Code</h2>
<pre><code class="language-bash">yarn
yarn dev
</code></pre>
<p>Running <code>yarn</code> without arguments tells it to examine the <code>package.json</code> file and install all dependencies. The second command says to execute the <code>dev</code> script. Vite will create a web server, typically running on port 3000, and can now serve the empty home page.</p>
<p><img src="/images/vite-localhost3000.png" alt="HSMercs Helper on localhost:3000"></p>
<p>Sure, it's boring, but this is where everything starts. Now time to get these files added to the repo, committed to the tree, and pushed up to system of truth.</p>
<pre><code class="language-bash">git add -A  # add the four files we created
git commit -m "minimum renderable code" # commit them to the repo with a comment
git remote add origin https://github.com/{username}/{repo} # add a github repo as the origin
git push --set-upstream-branch origin main # push the commit to a branch named main at the origin
</code></pre>
<h2>Minimum Renderable Vue</h2>
<p>We'll start by creating our first Vue component. By convention, we name the entrypoint to the whole application as <code>App.vue</code> and place it in our <code>src</code> folder.</p>
<h4>src/App.vue</h4>
<pre><code class="language-vue">&#x3C;script setup lang="ts">&#x3C;/script>

&#x3C;template>
&#x3C;&#x3C;&#x3C;&#x3C;&#x3C;&#x3C;&#x3C; HEAD
  &#x3C;div>HSMercs Helper&#x3C;/div>
=======
  &#x3C;header>
    &#x3C;div>HSMercs Helper&#x3C;/div>
    &#x3C;div>A set of tools for Hearthstone Mercenaries players.
  &#x3C;/header>
>>>>>>> main
&#x3C;/template>
</code></pre>
<p>Also by convention, the Typescript file that serves as the initial setup for the entire application is <code>main.ts</code> in the same <code>src</code> folder.</p>
<h4>src/main.ts</h4>
<pre><code class="language-typescript">import { createApp } from "vue";
import App from "./App.vue";

createApp(App).mount("#app");
</code></pre>
<p>This first imports the <code>createApp</code> function from the <code>vue</code> library and the <code>App</code> component we just created. Then it tells Vue to initialize with our component and mount it to the element with id <code>app</code>.</p>
<h4>index.html</h4>
<pre><code class="language-diff">  &#x3C;!DOCTYPE html>
  &#x3C;html lang="en">
    &#x3C;head>
      &#x3C;meta charset="UTF-8" />
      &#x3C;meta name="viewport" content="width=device-width, initial-scale=1.0" />
      &#x3C;title>HSMercs Helper&#x3C;/title>
    &#x3C;/head>
    &#x3C;body>
+     &#x3C;div id="app">&#x3C;/div>
+     &#x3C;script type="module" src="/src/main.ts">&#x3C;/script>
    &#x3C;/body>
  &#x3C;/html>
</code></pre>
<p>Adding in the div where the <code>App</code> component should be mounted and running the <code>main.ts</code> file. By specifying the type as "module", we are telling the browser that this script should be executed in "strict" mode. The browser will also wait to execute the code until the DOM is ready.</p>
<h3>Updating the Tools</h3>
<p>If you try to run <code>yarn dev</code> right now, you'll receive an internal server error.</p>
<p><img src="/images/vite-installplugin-vue.png" alt="Internal server error: Failed to parse source for import analysis because the content contains invalid JS syntax. Install @vitejs/plugin-vue to handle .vue files."></p>
<h4>package.json</h4>
<pre><code class="language-diff">  {
    "name": "hsmercs-helper",
    "version": "0.2.0",
    "private": true,
    "engineStrict": true,
    "engines": {
      "node": "^16"
    },
    "scripts": {
      "dev": "vite"
    },
    "dependencies": {
      "vue": "^3.2.25"
    },
    "devDependencies": {
+     "@vitejs/plugin-vue": "^2.0.1",
      "vite": "^2.7.10"
    }
  }
</code></pre>
<p>Update the <code>yarn.lock</code> file (and the node_modules folder) by telling yarn to double-check the packages</p>
<h4>vite.config.ts</h4>
<pre><code class="language-typescript">import vue from "@vitejs/plugin-vue";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [vue()],
});
</code></pre>
<p>We're not starting to add configuration options to the <code>vite</code> server. This is telling <code>vite</code> how to handle <code>vue</code>.</p>
<h4>/src/env.d.ts</h4>
<pre><code class="language-typescript">/// &#x3C;reference types="vite/client" />

declare module '*.vue' {
    import { DefineComponent } from 'vue'
    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/ban-types
    const component: DefineComponent&#x3C;{}, {}, any>
    export default component
  }
</code></pre>
<p>One little bit of tooling configuration before we wrap up this first step of the tutorial. If you check out the <code>src/main.ts</code> file, you'll see VSCode displaying red squiggles with the error "Cannot find module './App.vue' or its corresponding type declarations. ts(2307)". We need to add a shim to tell the Typescript compiler how to handle <code>vue</code> files.</p>
<pre><code class="language-bash">yarn     # recheck dependencies, specifically install @vitejs/plugin-vue
yarn dev # run vite to start the server!
</code></pre>
<p><img src="/images/vite-localhost3000vue.png" alt="&#x22;HSMercs Helper&#x22; heading"></p>
<h3>Final Housekeeping</h3>
<p>In order to have this code hosted somewhere, you'll want to run the build command. It does all kinds of magic to take the various bits and pieces we've written, combine it with the Vue library, and make it as small as possible, and dump it into a <code>dist</code> folder. By convention, the script call is <code>build</code>.</p>
<h4>package.json</h4>
<pre><code class="language-diff">  {
    "name": "hsmercs-helper",
    "version": "0.2.0",
    "private": true,
    "engineStrict": true,
    "engines": {
      "node": "^16"
    },
    "scripts": {
      "dev": "vite",
+     "build": "vite build"
    },
    "dependencies": {
      "vue": "^3.2.25"
    },
    "devDependencies": {
     "@vitejs/plugin-vue": "^2.0.1",
      "vite": "^2.7.10"
    }
  }
</code></pre>
<p>If you run the command <code>yarn build</code> (which is an alias for <code>yarn vite build</code>), git will think it needs to include the <code>dist</code> folder in the repository. We want to ignore this folder.</p>
<h4>.gitignore</h4>
<pre><code class="language-diff">  node_modules
+ dist
</code></pre>
<h2>Step 2: <a href="/posts/2022/storing-state-and-unit-testing">Storing State &#x26; Unit Testing</a></h2>
<p>In the interest of keeping hardcoded sample data out of the project, the next step will be to create a couple TypeScript interfaces, scaffold a <code>Vuex</code> store, and write the first unit tests.</p>


Rovani's Sandbox

HSMercs From Scratch

HSMercs From Scratch 4:Adding Some Style

HSMercs From Scratch 3:First Rudimentary Mercenary Components

HSMercs From Scratch 2:Storing State & Unit Testing

HSMercs From Scratch 1:HSMercs From The Beginning