Build a Single Page Web3 App with Vue 3, Vite and Pinia

Introduction Created in 2014, is undoubtedly one of the leading frontend frameworks at the moment. With a growing community and expanding ecosystem and it seems it will stay that way for quite some time. I have worked with Vue 2 several years ago for a few projects and I found it a delightful experience. Vue.js In a bid to keep up with evolving trends, I figured that now is the time to upgrade my tool-set to the latest version and also with newer tools like and . Vite Pinia This guide will cover in detail, the steps to create a ‘functional example bookstore single-page application’ using Vue 3 and running it using Vite. It also includes details on how to add, state management using Pinia (the successor), and routing using . Vuex Vue Router The core concepts that will be covered are: Creating a single page application using Vue 3 Vite Managing routes with Vue Router Managing application state with Pinia Running, building, and deploying the app with Vite Writing and running Vue component tests Writing and running automated end-to-end tests with Nightwatch.js This may seem like a lot, but I think it’s perfectly possible to go through all of it in less than 20 minutes. Some of the topics listed above could be expanded into entire tutorials of their own, but for now, I will only cover what’s needed to have everything up and running. One last thing that needs to be mentioned is that the backend is not covered in this tutorial. There is no server-side component per se, although the data is loaded using the browser Fetch API (the successor of XHR), so a backend component could be easily added. For all accounts and purposes, the application we’ll build here can be deployed as a static website. If you're eager to get right down to coding and you'd like to jump into it right away, you can just get the project up and running with: git clone https://github.com/beatfactor/middlemarch npm install npm run dev Or fork the project on Github at: https://github.com/beatfactor/middlemarch Step 1 – Setting Up the Application with the Scaffolding Tool create-vite We’re going to use the official ‘create-vite’ scaffolding tool to set up the project structure. Make sure you have Node 12+ installed with NPM 6+. They also support Yarn and PNPM as package managers, but we’ll only cover NPM. The ‘create-vite’ tool will also create the project folder for you, so just make sure to cd into the parent folder first: cd ~/workspace Install and initialise the project with: Vite npm init vite@latest Then you’ll be prompted to enter the project name and select the library which you want to use. From the list, choose : vue ~/workspace % npm init vite@latest npx: installed 6 in 1.051s ✔ Project name: … vue-bookstore ? Select a framework: › - Use arrow-keys. Return to submit. vanilla ❯ vue react preact lit svelte Then select as the variant, since we’ll not be using TypeScript: vue ? Select a variant: › - Use arrow-keys. Return to submit. ❯ vue vue-ts You should see the following output: npx: installed 6 in 1.051s ✔ Project name: … vue-bookstore ✔ Select a framework: › vue ✔ Select a variant: › vue Scaffolding project in /Users/andrei/workspace/vue-bookstore... Done. Now run: cd vue-bookstore npm install npm run dev Once we have followed the above instructions, we’ll get the following output from Vite telling us that the app is running: vite v2.7.7 dev server running at: > Local: http://localhost:3000/ > Network: use `--host` to expose ready in 611ms. Let’s visit the localhost:3000 URL. The welcome page looks like this: Step 2 – Routing with Vue Router and State Management with Pinia Let’s review the project’s directory structure created by the tool: create-vite vue-bookstore/ ├── public/ | ├── favicon.ico ├── src/ | ├── assets/ | | └── logo.png | ├── components/ | | └── HelloWorld.vue | ├── App.vue | └── main.js ├─── package.json ├─── README.md └─── vite.config.js In this section of our guide, we’ll be adding two new dependencies to our project: and . Let’s go ahead and install them from NPM. Vue-router pinia Vue Router Vue Router is the official router for Vue.js. We’ll need to install version 4 which is compatible with Vue 3: npm install vue-router@4 --save Pinia is one of the newest projects to emerge from the Vue ecosystem and it’s the new official state management tool for Vue.js apps. Its API is very similar to Vuex (its predecessor) and it is designed to be faster and more lightweight. Pinia You can install pinia from NPM with: npm install pinia --save Routing Set-up If you’re unfamiliar with state management or routing in a single-page application, don’t worry; both of these concepts are very easy to understand and will be easy to grasp once you see how it works. Also, remember that we are just building a tutorial here and the goal is to have everything up and running in 20 minutes and that doesn’t require learning all there is to know about Vue.js. It doesn’t even require understanding everything we’ll be doing. What is a Single Page Application? Since we’re building a single-page application here, it might be useful (though not essential) to consider what that means and why is it a single page. A single page application, simply put, is a web application that doesn’t reload the page when you navigate to another of its sub-pages. Although, the URL of the browser is modified to look as if the page has been reloaded, and that's done using the HTML5 . History API Working with Vue Components in Vite The scaffolding created using the tool adds a very basic Vue component, located in . It is then used in the main application component, located in . create-vite src/components/HelloWorld.vue src/App.vue There are two other important files to take note of: index.html src/main.js The index.html file is what the browser sees when it navigates to our application’s page, and the main.js is the entry point for the Vue.js app. Here’s what these files look like: index.html Vite App src/main.js import { createApp } from 'vue' import App from './App.vue' createApp(App).mount('#app') Adding Routes It’s time now to create our application’s main routes. In Vue, every route must correspond to a component. For this application, we’ll consider a component per subpage, like so: - our bookstore homepage Homepage - the shopping cart and check out page Cart - the user sign-in page Sign-In Since this is only an example, other pages like user sign-up or product detail page, have been left out. Also, the sign-in page only contains a mock sign-in. For basic HTML and CSS, I’ve also used for things like UI dropdowns and forms, but of course, you can use whatever UI library you want. Bootstrap 5 We’ll move on to creating empty page components for now so we can set up the routing. The new src directory structure will look like this (after removing the boilerplate code): src/ ├── components/ | └── TopNavbar.js ├── lib/ | ├── router.js | └── store.js ├── pages/ | ├── cart/ | | ├── cart.css | | ├── cart.html | | └── Cart.vue | ├── home/ | | ├── home.css | | ├── home.html | | └── Home.vue | ├── sign-in/ | | ├── sign-in.css | | ├── sign-in.html | | └── SignIn.vue | └── routes.js ├── App.vue └── main.js We’ve added three pages, each of which we’ll keep very basic. We’ll just add components to make the navigation work without page reloads. TobNavbar Add the following for , and : src/pages/cart/Cart.vue src/pages/home/Home.vue src/pages/sign-in/SignIn.vue import TopNavbar from '../../components/TopNavbar.vue'; export default { components: { TopNavbar }, computed: {}, mounted() { }, data() { return { }; }, }; The component located in will contain just the navigation links. TopNavbar src/components Notice how the router-link component which is part of the appears: vue-router Home Cart Sign In The file contains all the route declarations for the application. Here’s how it looks: pages/routes.js import {createRouter} from 'vue-router' import Homepage from './home/Home.vue'; import SignIn from './sign-in/SignIn.vue'; import Cart from './cart/Cart.vue'; const routes = [ { path: '/', component: Homepage }, { path: '/sign-in/', component: SignIn }, { path: '/cart/', component: Cart }, ] export default function (history) { return createRouter({ history, routes }) } Before we’re ready to see the in action, we need to do 2 more things: vue-router Create the router and add it to the main Vue application instance, in : 1) src/main.js import { createApp } from 'vue' import { createWebHistory } from 'vue-router' import createRouter from './pages/routes.js' import App from './App.vue' const router = createRouter(createWebHistory()) const app = createApp(App) app.use(router).mount('#app') Add the component in : 2) src/App.vue Now re-run if needed and then navigate to where you’ll have a routing-enabled Vue 3 app. npm run dev http://localhost:3000 Setting Up State Management Using Pinia Next, we need to set up the Pinia store for our app. The store is where the application state is maintained. Pinia is a new project from the Vue.js core team and is now the recommended approach for working with the application state. If you’re already familiar with Vuex, getting used to Pinia will be straightforward. In fact, the Pinia API is slightly easier and less verbose than Vuex. With Pinia, in a Vue 3 app there is one root store and then any number of individual stores. For our bookstore app, we’re going to use only two stores: The store: a list of available books catalog The store: books that the user wants to order cart Creating a Pinia A “Pinia” is the root store that we have to create first and then pass to the Vue instance. We’ll do that in and update it to look like: src/main.js import { createApp } from 'vue' import { createWebHistory } from 'vue-router' import { createPinia } from 'pinia' import createRouter from './pages/routes.js' import App from './App.vue' const store = createPinia() const router = createRouter(createWebHistory()) const app = createApp(App) app.use(router).use(store).mount('#app') The next step is to create the individual catalog and cart stores and use them in components. Adding the Catalog Store Creating a Pinia store means two things mainly:z Defining the store Using the store in one or more components Defining the Store Like Vuex, the Pinia store contains the and two types of methods: and . state getters actions Some things to consider about a store: are synchronous functions used to retrieve data from the state Getters are functions that can also be asynchronous which are used to update the state Actions The is defined as a function returning the initial state state It’s time now to create the catalog store inside : src/stores/catalog.js import { defineStore } from 'pinia' export const useCatalog = defineStore('catalog-store', { state: () => { return { newArrivals: [], fetching: false } }, getters: { results(state) { return state.newArrivals; }, isFetching(state) { return state.fetching; } }, actions: { async fetchNewArrivals() { this.fetching = true; const response = await fetch('/data/new-arrivals.json'); try { const result = await response.json(); this.newArrivals = result.books; } catch (err) { this.newArrivals = []; console.error('Error loading new arrivals:', err); return err; } this.fetching = false; } } }) Looking at the above source code, you’ll notice we have two ‘getters’ ( and ) and one action ( ). Instead of a real backend, we have just a json file located in which contains a few books that we’ll use as our catalog. results isFetching fetchNewArrivals /data/new-arrivals.json You’ll also notice that our ‘getters’ don’t do anything special with the data and so they’re a bit unnecessary, but I they’re included to show how you can define them. Using the Store in a Template Linking the above definition to a template is also quite straightforward. Let’s create a new component called inside which we’ll use in the page component. NewArrivals src/components/NewArrivals.vue Home.vue import {useCatalog} from '../../store/catalog.js' import { mapState, mapActions } from 'pinia' export default { computed: { ...mapState(useCatalog, {newArrivals: 'results'}) }, methods: { ...mapActions(useCatalog, ['fetchNewArrivals']), addToCart() { // we'll populate this later } }, created() { // when the template is created, we call this action this.fetchNewArrivals(); } }; The component becomes: Home.vue import TopNavbar from '../../components/TopNavbar.vue'; import NewArrivals from '../../components/NewArrivals.vue'; export default { components: { TopNavbar, NewArrivals }, computed: {}, mounted() {}, data() { return {}; }, }; Here’s a diagram of how the store and the component work together in the application: I also wrote a store and a component for the cart but I will not include it in the tutorial. The mechanism is similar and you can inspect the source code in the repository which has everything included, even some extra styles. Step 3 – Testing Vue.js Components Component testing is a type of UI testing where the component is rendered in isolation, and without the rest of the app’s components, for the purpose of verifying its functionality. It’s usually a testing strategy that happens prior to the end-to-end testing step, which we’ll elaborate on in the next section. We need to install the project; the official unit testing library for Vue.js, we need the one that targets Vue 3. Vue TestUtils You can install that from NPM with: npm install @vue/test-utils@next --save-dev Installing Nightwatch.js and ChromeDriver We’ll use Nightwatch.js for both component testing and end-to-end testing. Nightwatch is already one of the recommended testing frameworks by the Vue.js team and was published around the same time as Vue.It has recently gotten support (still in beta ) for Vue component testing through the . vite-plugin-nightwatch We’ll go ahead and install Nightwatch v2 using: npm install nightwatch--save-dev And we’ll also need the mentioned earlier: vite-plugin-nightwatch npm install vite-plugin-nightwatch --save-dev Nightwatch uses the for browser automation tasks and we’ll need to install the NPM package as well, because we’re going to use Chrome to run our tests. W3C WebDriver API chromedriver npm install chromedriver --save-dev Testing the Component And with that, we have arrived at the point where we can finally start writing the actual test for our NewArrivals component. The mentioned earlier includes a test renderer page and Nightwatch already contains everything needed for running the initial test for our component. vite-plugin-nightwatch Create a folder and inside it two subfolders: test - this will hold component tests component - this will hold end-to-end tests e2e We also need a configuration file, but we can run Nightwatch directly and have the config file created for us automatically. Just make sure is also installed (and the Chrome browser, of course). nightwatch.conf.js chromedriver Make sure the current working directory is the project root and then simply run an that is bundled with Nightwatch. We’ll pick the test because it’s the fastest: example test duckDuckGo $ npx nightwatch examples/tests/duckDuckGo.js The project structure should look like this now: vue-bookstore/ ├── public/ | ├── data/ | └── favicon.ico ├── src/ ├── ... | └── main.js ├── test/ | ├── component/ | └── e2e/ ├─── nightwatch.conf.js ├─── package.json ├─── README.md └─── vite.config.js We’ll go ahead and create a new file called inside . In it, we’ll add a basic test that mounts the component and checks if the returned element can be found on the page (i.e. the component has been mounted). newArrivalsTest.js test/component describe('New Arrivals Component Test', function() { it('checks if the component has been mounted', async (browser) => { const component = await browser.mountVueComponent('/src/components/new-arrivals/NewArrivals.vue', { plugins: { router: '/src/lib/router.js' } }) expect(component).to.be.present; }); }); Nightwatch uses the same syntax as Mocha. You can even use Mocha as a test runner if you’re already familiar with it, but we’re not going to do that for now. In case you’d like to use Mocha, you only need to slip a few switches in the Nightwatch config file and there’s documentation available on the on how to do that. describe() Nightwatch website It’s time now to run the above test and for that we’ll run Nightwatch using Chrome, like so: npx nightwatch test/component/newArrivalsTest.js --env chrome This will open the Chrome browser and render the component, then perform the test. If you don’t like seeing the browser window pop up during the test, you can pass the the argument, like so: --headless npx nightwatch test/component/newArrivalsTest.js --env chrome --headless The test output should look like below: [New Arrivals Component Test] Test Suite ────────────────────────────────────────────────────────────── ℹ Connected to ChromeDriver on port 9515 (652ms). Using: chrome (97.0.4692.99) on MAC OS X. Running tests the component: ────────────────────────────────────────────────────────────── ✔ Expected element to be present (1ms) OK. 1 assertions passed. (781ms) You can of course consult all the CLI options that the Nightwatch runner provides, either by going to the or by running: docs pages npx nightwatch --help Extending the Test You may have noticed that our component test isn’t testing that much which means that the test is not as helpful as it could be. So we’ll go ahead and extend it only a little bit. We’ll just inspect the component and check if there is a property in it called , which is used in the HTML to render the results. NewArrivals newArrivals The test looks like this now. We’ve refactored the component mounting into the hook so we can only do the checks inside the test, the block. The library is provided by Nightwatch out of the box and it is based on the popular and versatile assertion library. before it expect Chai.js More info on how to use the on the website. expect Nightwatch docs describe('New Arrivals Component Test', function() { let component; before(async () => { component = await browser.mountVueComponent('/src/components/new-arrivals/NewArrivals.vue', { plugins: { router: '/src/lib/router.js' } }) }); it('checks if the component has been mounted', function(browser) { expect(component).to.be.present; expect(component).to.have.property('newArrivals'); expect(component).text.toContain('The Memory Police') expect.elements('div.col-md-6').count.toEqual(4); expect(component.property('newArrivals')).to.be.an('array').with.length(1); }); }); Step 4 – End-to-End Testing the Vue.js App We are nearing the end of this tutorial but before we can consider we have a working Vue.js app, we need to add support for end-to-end testing and set up a CI pipeline on Github Actions. Fortunately, we don’t need to insta or configure any other tools, except some fancy reporters, but for now we can get everything we need in terms of end-to-end automated testing out of Nightwatch. Besides Chrome, Nightwatch has built-in support for all major browsers, including Firefox, Edge, and Safari, all thanks to its integration with the W3C Webdriver API and Selenium. It also allows you to use distributed cloud testing platforms like , , , or . BrowserStack SauceLabs CrossBrowserTesting LambdaTest For now, we’ll keep things less complex and we’ll only focus on writing a few basic automated tests and run them in Chrome, Firefox, and Safari. Writing the Homepage End-to-end Test Let’s get started with the homepage end-to-end test and create a new file under . The syntax is the same as for the component test, but for running the end-to-end tests we’ll use the compiled build of our application. test/e2e/homePageTest.js We can of course run them against the dev build, but the established practice in software development, as far as I can tell, is to run the end-to-end tests in an environment that simulates the production with reasonable precision. This is why they’re called end-to-end tests I suppose, to run them against the end product. Running the Production Build To run the production build we have two options and each of them involves running a command, which is wrapped in NPM tasks. Vite - this will generate the index.html and the other static assets. You can use this option if you already have a local webserver set up. npm run build - this will generate a production build and run it using the built-in dev server, by default at . npm run preview http://localhost:5000 The second option is clearly more straightforward and so let’s just run the command and see what happens: preview $ npm run preview > vue-bookstore@0.0.0 preview /Users/andrei/workspace/vue-bookstore > vite preview > Local: http://localhost:5000/ > Network: use `--host` to expose Writing the Test Script Now that we have a production-ready build running, we can start writing the actual test in . test/e2e/homePageTest.js We’ll start small, with just the below: describe('Homepage End-to-end Test', () => { it('tests if homepage is loaded', browser => { browser .navigateTo('http://localhost:3000') .assert.visible('#app .new-arrivals-panel') .expect.elements('#app .new-arrivals-panel .col-md-6').count.toEqual(4) }); it('adds 2 volumes of "Rhinoceros and Other Plays" to cart', browser => { browser .click('.new-arrivals-panel .col-md-6:nth-child(2) button.add-to-cart') .click('.new-arrivals-panel .col-md-6:nth-child(2) button.add-to-cart') .assert.textEquals('.shopping-cart .badge', '2'); }); after(browser => browser.end()); }); The test verifies if the New Arrivals panel is displayed on the page and that it contains all 4 entries which we’ve already seen. Running the Test Script in Chrome To run this in Chrome, the command is very similar to the one for the component test: npx nightwatch test/e2e/homePageTest.js --env chrome And the output will be: [Homepage End-to-end Test] Test Suite ────────────────────────────────────────────────────────────── ℹ Connected to ChromeDriver on port 9515 (2454ms). Using: chrome (97.0.4692.99) on MAC OS X. Running tests the homepage: ────────────────────────────────────────────────────────────── ✔ Testing if element is visible (157ms) ✔ Expected elements count to equal: "4" (18ms) OK. 2 assertions passed. (765ms) Running the Test Script in Firefox If we’d want to also run our end-to-end tests in the Firefox browser, we only need to install the (the Firefox specific implementation of the W3C WebDriver API). No other config is necessary to get it working unless you would like to customize it further. GeckoDriver So let’s go ahead and install it from NPM: npm i geckodriver --save-dev And then run Nightwatch with the following command: npx nightwatch test/e2e/homePageTest.js --env firefox And the output: [Homepage End-to-end Test] Test Suite ────────────────────────────────────────────────────────────── ℹ Connected to GeckoDriver on port 4444 (1737ms). Using: firefox (96.0.2) on MAC (20.6.0). Running tests the homepage: ────────────────────────────────────────────────────────────── ✔ Testing if element is visible (54ms) ✔ Expected elements count to equal: "4" (6ms) OK. 2 assertions passed. (612ms) Running the Test Script in Safari If you’re using a Mac, then is probably already installed, depending on your Safari version. safaridriver You can check with using: safaridriver --help And the output should look like: Usage: safaridriver [options] -h, --help Prints out this usage information. --version Prints out version information and exits. -p, --port Port number the driver should use. If the server is already running, the port cannot be changed. If port 0 is specified, a default port will be used. --enable Applies configuration changes so that subsequent WebDriver sessions will run without further authentication. --diagnose Causes safaridriver to log diagnostic information for all sessions hosted by this instance. See the safaridriver(1) man page for more details about diagnostic logging. Before running your first test in Safari, you just need to enable automation, with the following command: safaridriver --enable And then simply run the Nightwatch test with: npx nightwatch test/e2e/homePageTest.js --env safari Running in Parallel in Multiple Browsers If you need to run your Nightwatch tests (either component or end-to-end) in more than one browser, you can. Simply pass the browsers as a comma-separated list (no spaces): Running in Firefox+Chrome npx nightwatch test/e2e/homePageTest.js --env firefox,chrome Running in Firefox+Chrome+Safari npx nightwatch test/e2e/homePageTest.js --env firefox,chrome,safari Nightwatch also supports running tests in parallel by dividing the total number of test script files over a configurable number of workers. But since we only have one file for now, we’ll skip this part. More on parallelism on the website. Nightwatch docs Step 5 – Enabling Continuous Integration with Github Actions It looks like it’s time to wrap things up and put everything together. Before we can enable continuous deployment in Github Actions, we need to create the NPM task. test Creating the “npm test” Task Now we have both component testing and end-to-end testing in our example project. Of course, it is only at a minimum level so it doesn’t cover everything, but it’s a good start I would say. The easiest way to tell Nightwatch to run all the tests inside the test folder is to pass the folder as the second CLI argument. We’ll add that as a new NPM task called so let’s edit the and add the following, inside the “scripts” dictionary: test package.json { "test": "nightwatch ./test" } We can run the NPM task and pass Nightwatch related CLI arguments like so: npm test -- --env chrome --headless We’ll use mode in order to run the tests in Github Actions. --headless Adding the Github Action workflow Finally, we can add the Github Actions workflow so that our tests can run on every push and every pull request. Doing so it’s quite straightforward. We’ll use the Node.js template and add a few new steps in the list, for: starting the dev server in the background building the project and starting the dev server in preview mode, also in the background running both component and end-to-end tests in Chrome, in headless mode Creating the Github Actions workflow means adding a new file called in the folder which should look like below. Most of this is auto-generated when you navigate to the Actions section from your Github project and choose the Node.js template. node.js.yml .github/workflows name: Node.js CI on: push: branches: [ main ] pull_request: branches: [ main ] jobs: build: runs-on: ubuntu-latest strategy: matrix: node-version: [12.x, 14.x] steps: - uses: actions/checkout@v2 - name: Use Node.js ${{ matrix.node-version }} uses: actions/setup-node@v2 with: node-version: ${{ matrix.node-version }} - run: npm ci - name: Start vite dev server run: npm run dev & - name: Build the app run: npm run build - name: Start vite dev server in preview run: npm run preview & - name: Run Nightwatch tests run: npm test And that's it. A new build will run for each new git push or whenever a new pull request is sent. The build will be run in 2 separate environments, one for Node 12 and the other Node 14, as defined in the workflow definition. Where to Go From Here The project is available on Github at and all the code covered here and a bit more styling and imagery. It also contains the code for the shopping cart and a mock checkout page. https://github.com/beatfactor/middlemarch You can get it running on your local machine with the usual steps: git clone https://github.com/beatfactor/middlemarch npm install npm run dev Feel free to send pull requests or report issues. Getting Support Vue3, Vite, and Pinia The Vue.js core team provides community support for Vue3, Vite, and Pinia on the following channels: chat server on Discord VueLand Vue Forum on Github Vite Discussions on Github Pinia Discussions Nightwatch.js For support with everything Nightwatch testing related, we have the following channels: Github Discussions on Discord Nightwatch.js chat server First published here