Angular

Mixing Storybook with Angular with a Sprinkle of Applitools

Published Oct 28, 2019

Updated Feb 14, 2023

8 min read

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

To better understand the Applitools Storybook SDK for Angular, we will be building a small Angular application from scratch, adding some Storybook stories, and then finally performing visual regression testing using the Applitools SDK to generate snapshots for us to view and analyze.

You can find the source code for this article on GitHub by following this link storybook-angular-applitools repo.

Create Angular 7 App using the latest CLI

Make sure you have the latest Angular CLI installed. In my case, I will be using the Angular CLI v7.0.2. Create a new Angular App using the following npm command:

ng new storybook-angular-applitools

Create the ContentEditable Component

The ContentEditable component we are going to build in this section wraps an HTML <div> element and adds an HTML attribute of contenteditable=”true”. The component implements the ControlValueAccessor so that the component can be used like any other Angular form control inside HTML forms.

<div contenteditable=”true”>This is an editable paragraph.</div>

The HTML fragment above renders in the browser as an editable area that users can click and enter any text or HTML.

Create a new component file and add the following markup to contenteditable.component.html file:

<div 
 #container 
 [ngStyle]=”styles” 
 [innerHTML]=”contentValue” 
 (input)=”setContent($event)” 
 contenteditable=”true”>
 </div>

Next, add the code below to the contenteditable.component.ts file:

import { Component, ChangeDetectionStrategy, Input, forwardRef, OnChanges, SimpleChanges, ElementRef, Renderer2, ViewChild } from '@angular/core';
import { ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';

@Component({
  // tslint:disable-next-line:component-selector
  selector: 'editable',
  templateUrl: `./contenteditable.component.html`,
  styles: [],
  changeDetection: ChangeDetectionStrategy.OnPush,
  providers: [
    {
      provide: NG_VALUE_ACCESSOR,
      useExisting: forwardRef(() => ContentEditableComponent),
      multi: true
    }
  ],

})
export class ContentEditableComponent
  implements ControlValueAccessor, OnChanges {
  @ViewChild('container') container;
  private _styles: any;
  private _contentValue: any;

  propagateChange: (value: any) => void = () => {};

  @Input()
  set styles(style: any) {
    this._styles = style;
  }

  get styles(): any {
    return this._styles;
  }

  get contentValue(): any {
    return this._contentValue;
  }

  set contentValue(val: any) {
    if (this._contentValue !== val) {
      this._contentValue = val;
      this.propagateChange(val);
    }
  }

  writeValue(value: any) {
    if (value !== this._contentValue) {
      this.contentValue = value;
    }
  }

  registerOnChange(fn: (value: any) => void) {
    this.propagateChange = fn;
  }

  registerOnTouched(fn: () => void) {}

  setContent($event: any): void {
    // this._contentValue = $event.target.innerHTML;
    this.propagateChange($event.target.innerHTML);
  }

  ngOnChanges(changes: SimpleChanges): void {}
}

The component is straightforward and follows the best practices in building a ControlValueAccessor. It defines a single @Input() property to allow the consumer of this component to control its styling.

If you want to fully understand how ControlValueAccessor works in Angular check out Max’s article titled Never again be confused when implementing ControlValueAccessor in Angular.

Next, add the following HTML snippet to the app.component.html file:

<section class="section">
 <h2>Two-way Data-binding</h2>
 <editable name="editable2" [styles]="styles()" [(ngModel)]="content1"></editable>
 <pre>{ content1 | json }</pre>
</section>

Define the styles() method inside the AppComponent class:

styles() {
 return {
  "background-color": "yellow",
   margin: "10px auto",
  "max-width": "60%",
  "line-height": "25px",
  padding: "10px"
 };
}

And now run the application. You should see something similar to this below.

You can start typing in the yellow editable rectangle and you will see whatever you type underneath.

Let’s switch gears and add Storybook to the application.

Add Storybook packages

We need to add Storybook for Angular to your application. The Storybook website offers a detailed installation guide on Storybook for Angular. Once installed, apply the following changes, so that Storybook runs correctly with your Angular 7 application.

Open the src/app/tsconfig.app.json file and make sure the exclude property has the following values:

"exclude": [
  "test.ts",
  "**/*.spec.ts",
  "stories"
 ]

Open the .storybook/tsconfig.json file and paste the following:

{
 "extends": "../src/tsconfig.app.json",
 "compilerOptions": {
    "types": [
    "node"
  ]
 },
 "exclude": [
    "../src/test.ts",
    "../src/**/*.spec.ts",
    "../projects/**/*.spec.ts"
 ],
 "include": [
    "../src/**/*",
    "../projects/**/*"
 ]
}

Create and run a few Storybook stories

Add the following Storybook stories into the file located at src/app/stories/index.stories.ts:

storiesOf('ContentEditable Component', module)
 .add(
   'with yellow background',
   withNotes('Testing the background color for the editable area and setting it to yellow')(() => ({
     component: ContentEditableComponent,
     props: {
       styles: { 'background-color': 'yellow', 'padding': '20px' },
       ngModel: 'The content goes here',
       ngModelChange: action('ngModelChange')
     }
   }))
 )
 .add(
   'with red background',
   withNotes('Testing the background color for the editable area by setting it to red')(() => ({
     component: ContentEditableComponent,
     props: {
       styles: { 'background-color': 'red', 'color': '#fff', 'padding': '20px' },
       ngModel: 'The content goes here',
       ngModelChange: action('ngModelChange')
     }
   }))
 );

The first story renders the ContentEditable component with a yellow background. While the second renders the component with a red background.

Run the Storybook tool to view and test your stories by issuing the following CLI command:

npm run storybook

You should be able to see something similar to this:

Now that we are sure the Storybook stories are up and running, let’s set up Applitools to use these stories and run our visual automated tests.

Add and run Applitools Storybook SDK for Angular

To add Applitools Storybook SDK for Angular to this application issue the following CLI command:

npm install @applitools/eyes.storybook --save-dev

Make sure to grab an Applitool API Key and store it on your machine. For a complete tutorial on how to install and run Applitools Storybook SDK for Angular, you may check this link: Storybook Angular Tutorial.

To run the Storybook stories and send the snapshots to the Applitools Server, issue the following command:

npx [eyes-storybook](https://github.com/applitools/eyes.storybook)

The command simply opens the Storybook stories, runs them one by one, and then sends all the DOM snapshots to the Applitools Server. Let’s have a look at the test results inside Applitools Test Manager.

Review test results on Applitools Test Manager

We can see the results of the tests we just ran from the Applitools Test Manager. To access the Applitools Test Manager, navigate to https://www.applitools.com. Sign in to get onto the Dashboard. For a detailed look at the Applitools Test Manager, you can check my article on Applitools — The automated visual regression testing framework

The results for running the Storybook tests show the following:

The test manager lists the test runs or batches (as referred to by Applitools) on the left- hand side. Clicking on any of the batches displays all of the snapshots for all of the Storybook stories in your application.

Click on the first snapshot (the red color) to expand and review it in detail:

A rich toolbox is available to zoom in/out on the snapshot and compare this snapshot to any previously taken, known as the baseline. In this case, since this is the first time we are running the stories, there won’t be any baseline set. Therefore, Applitools Test Manager sets these snapshots as a baseline for upcoming regression test cycles.

Next, we’re going to simulate what happens when we have a visual regression in one of our components. To do this most easily, we’ll change one of our Storybook stories to render our component in a way that will be different from the baseline images we took earlier. Then, when we re-run the visual testing, we should see a discrepancy appear that we’ll have to resolve.

To do this, let’s assume that the story named in the red background above, has the ngModel value changed and now reads as follows:

.add(
  'with red background',
  withNotes('Testing the background color for the editable area by setting it to red')(() => ({
    component: ContentEditableComponent,
    props: {
      styles: { 'background-color': 'red', 'color': '#fff', 'padding': '20px' },
      ngModel: 'The red content goes here',
      ngModelChange: action('ngModelChange')
    }
  }))
 )

Now run this command:

npx eyes-storybook

The command gives you a detailed test result every time you run it. Check the following results:

Using @applitools/eyes.storybook version 2.1.9.

√ Storybook was started
√ Reading stories
√ Done 2 stories out of 2

[EYES: TEST RESULTS]:

ContentEditable Component: with yellow background [1024x768] — Passed

ContentEditable Component: with red background [1024x768] — Failed 1 of 1

A total of 1 difference was found.

See details at [https://eyes.applitools.com/app/test-results/00000251861893628194?accountId=D9XKRBVuYUmBxXpWWWsB3g~~](https://eyes.applitools.com/app/test-results/00000251861893628194?accountId=D9XKRBVuYUmBxXpWWWsB3g~~)

Total time: 36 seconds

Running the second story fails, as expected because we changed the content that was initially displayed inside the ContentEditable component. The test result output provides you with a link to check the discrepancies online. Click on the link to open the issues directly in the Applitools Test Manager:

A new batch is displayed on the left-hand side with a status of Unresolved. The Unresolved status indicates that the Applitools Test Manager discovered a discrepancy between the two test runs. This will require your input in order to resolve the discrepancy. Either approve the difference, and create a new baseline, or reject it to keep the original baseline.

Notice the blue square above indicating the Not Equal sign. This means the second snapshot test run has some differences to the first test run snapshot (the baseline). Clicking on the first snapshot reveals the differences between both snapshots. The current one and the baseline. The differences in content are highlighted in blue. You can also compare the new snapshot with the baseline by selecting both:

This should display both side by side and all differences are highlighted for you. You may spend more time at the Applitools Test Manager to explore all the rich features provided for you to do a thorough analysis on running the story tests.

Conclusion

This article touched the surface on how you can mix together Storybook and Angular together in one application. By means of Applitools Storybook SDK for Angular, you can provide automated visual UI testing by running the Storybook stories and generate snapshots that are then sent to the Applitools AI Server to compare and analyze and prepare the test results for you.

You can grab the code for this article by cloning the repository on GitHub.

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

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

About the author(s)

Bilal Haidar
Author, Developer, and Mentor: Professional ASP.NET 3.5 Security, Membership, and Role Management with C# and VB | A Complete Guide to VueJS
@bhaidar @bhaidar

4 Angular Component Libraries That are Perfect for Beginners

For beginners starting with Angular, the journey can feel daunting, especially when it comes to setting up projects from scratch. However, there is a range of outstanding Angular component libraries that alleviate this initial hurdle: ready-made toolkits, empowering newcomers to start building Angular applications without the complexities of bootstrapping their projects. Let’s take a look! Angular Material Angular Material is a UI component library by Google for Angular applications. It provides a variety of pre-built components following the Material Design guidelines, offering customization options, responsive design, and accessibility features. It's seamlessly integrated with Angular and offers extensive documentation and community support. NG-ZORRO NG-ZORRO is an Angular UI component library based on Ant Design by Alibaba. It offers a variety of customizable components for building modern web applications. With seamless Angular integration, responsive design, and accessibility features, NG-ZORRO simplifies development while following Ant Design principles. NG Bootstrap NG Bootstrap is a library for Angular developers to easily incorporate Bootstrap components into their applications without relying on jQuery. It offers Angular-specific directives and components, ensuring compatibility and performance within Angular projects while maintaining Bootstrap's responsive design and customization options. Clarity Design System Clarity is an open-source design system by VMware that offers a set of Angular components for building enterprise-scale applications. It provides components specifically tailored for data-centric applications, dashboards, and complex user interfaces. Clarity Design System emphasizes clarity, consistency, and usability in its components. The beginner’s journey can be both exhilarating and challenging. However, with the advent of powerful component libraries like Angular Material, NG-ZORRO, NG Bootstrap, and the Clarity Design System, the path becomes significantly smoother. These libraries offer pre-built components and design systems that eliminate the need to bootstrap projects from scratch. As beginners embark on their Angular journey, these libraries provide a sturdy foundation, allowing them to dive into development with confidence. By harnessing the capabilities of these libraries, beginners can not only expedite their learning curve but also craft exceptional Angular applications with ease and efficiency....

Mar 14, 2024

2 mins

Angular

SSR Finally a First-Class Citizen in Angular?

I am sure you've already heard about server-side rendering (SSR). Generally, it's a technique used to deliver the HTML content generated by the server to the client. The client-side JavaScript framework then hydrates that HTML content to provide a fully interactive application. SSR provides numerous benefits if used correctly, including improved initial load times, better content indexing by search engines, and improved performance on lower-tier devices. Driven by the need for faster, more efficient web applications, with the rise in popularity of Node.js and, thus, server-side JavaScript, SSR has become a de facto standard in modern web development frameworks. At first, SSR was being provided as a part of meta-frameworks like Next.js, Nuxt, or Analog.js. Then, React introduced React Server Components, which marked a significant milestone in the way we think about front-end development. We think of front-end frameworks as being effectively full-stack, and a purely SPA approach is falling out of favor. However, I'm willing to bet that if you're a developer focused mostly on Angular, you may not have heard as much about SSR as your React counterparts. For a long time, Angular has been mostly focused on the SPA approach, and while we had Angular Universal or Analog.js, it was not as widely adopted. And that makes sense, given that Angular was widely regarded as best suited for complex, interactive applications, such as SaaS products or internal company tools, where SEO and initial load times were not as critical as they are for consumer-facing applications. Nevertheless, we have been blessed with the so-called Angular Renaissance, which has, among other things, brought SSR to the forefront of Angular development with the @angular/ssr package. Let's look at what Angular SSR is, how it works, and how you can get started. @angular/ssr The @angular/ssr package is not new; it was written from scratch. It's still Angular Universal. However, it's been pulled into the Angular CLI repository, and the appropriate schematics have been added to make it easier to use. What that means is that you can now add SSR to your Angular application with a single command: ` and you can generate a new SSR application with: ` And to make SSR a first-class citizen, the Angular team is planning to make it the default in the next version. But surely, it's not only rebranding and some CLI commands, you may say. And you're right. You may remember that hydration in Angular Universal has not been optimal as it was destructive and required essentially a complete re-render of the application, thus pretty much negating the benefits of SSR. With the introduction of non-destructive hydration in Angular 16 and its stability in Angular 17, the Angular team has taken a significant step forward in making SSR a first-class citizen. How to Make an SSR-capable Angular Application Let's look at how to use Angular SSR in practice by creating a simple SSR app. First, we need to create a new Angular application with SSR support: ` That will generate a few server-specific files: - server.ts, which is an Express server configured to handle Angular SSR requests by default but can also be extended to handle API routes, or anything else that Express can handle. - src/app/app.config.server.ts provides configuration for the server application similar to your app.config.ts, which defines the configuration for your client application. Both export an instance of ApplicationConfig - src/main.server.ts bootstraps the server application in a similar way to what main.ts does for your client app by calling the bootstrapApplication function. You should have an SSR application ready just like that. You can verify that by running ng serve. The terminal output should show you information about the server bundles generated, and you should be able to see the default app when going to http://localhost:4200. Open the Developer Tools and check the console to see that hydration is enabled. You'll see a message with hydration-related stats, such as the number of components and nodes hydrated. Speaking of hydration... Client Hydration If you open the src/app/app.config.ts in your new SSR application, you'll notice one interesting provider: provideClientHydration(). This provider is crucial for enabling hydration - a process that restores the server-side rendered application on the client. Hydration improves application performance by avoiding extra work to re-create DOM nodes. Angular tries to match existing DOM elements to the application's structure at runtime and reuses DOM nodes when possible. This results in a performance improvement measured using Core Web Vitals statistics, such as reducing the Interaction To Next Paint (INP), Largest Contentful Paint (LCP), and Cumulative Layout Shift (CLS). Improving these metrics also positively impacts SEO performance. Without hydration enabled, server-side rendered Angular applications will destroy and re-render the application's DOM, which may result in visible UI flicker, negatively impact Core Web Vitals like LCP, and cause layout shifts. Enabling hydration allows the existing DOM to be reused and prevents flickering. Event Replay and Improved Debugging With Angular 18, event replay, a feature that significantly enhances the SSR experience, came into developer preview. Event replay captures user interactions during the SSR phase and replays them once the application is hydrated. This ensures that user actions, such as adding items to a cart, are not lost during the hydration process, providing a seamless user experience even on slow networks. To enable event replay, you can add withEventReplay to your provideClientHydration call: ` Furthermore, Angular 18 takes another step towards making SSR a first-class citizen by enhancing the debugging experience with Angular DevTools. Now, DevTools include overlays and detailed error breakdowns, empowering developers to visualize and troubleshoot hydration issues directly in the browser. Constraints However, hydration imposes a few constraints on your application that are not present without hydration enabled. Your application must have the same generated DOM structure on both the server and the client. The hydration process expects the DOM tree to have the same structure in both environments, including whitespaces and comment nodes produced during server-side rendering. Direct DOM Manipulation The fact that server and client DOM structures must match means that components that manipulate the DOM using native DOM APIs or use innerHTML or outerHTML will encounter hydration errors. The errors are thrown because Angular is unaware of these changes and cannot resolve them during hydration. Examples include accessing the document, querying for specific elements, and injecting additional nodes using appendChild. Detaching DOM nodes and moving them to other locations will also cause errors. Direct DOM manipulation is generally considered bad practice in Angular, so I recommend refactoring your components to avoid it regardless of hydration. However, in warranted cases where refactoring is not feasible, you can use the ngSkipHydration attribute until a hydration-friendly solution can be implemented. You can use it directly in a template: ` or as a host binding: ` > Note: The ngSkipHydration attribute forces Angular to skip hydrating the entire component and its children. So use this attribute carefully, as, for example, applying it to your root application component would effectively disable hydration for the entire application. Valid HTML Structure Another constraint is that invalid HTML structures in component templates can result in DOM mismatch errors during hydration. Common issues include: - without a - inside a - inside an - inside another Again, if you have an invalid HTML, you should fix this regardless of hydration. If you are unsure about your HTML's validity, you can use the W3 validator to check it. Zoneless apps or custom Zone.js Hydration relies on a signal from Zone.js when it becomes stable. Custom or "noop" Zone.js implementations may thus disrupt the timing of this event, triggering the serialization or cleanup process too early or too late. This configuration is not yet fully supported. While Zoneless is already available in developer preview and we could assume this issue will be resolved when it lands as stable, there is no explicit ETA mentioned in the official roadmap. I18n One of the biggest blockers for adoption of client hydration was the lack of support for internationalization with hydration. By default, Angular 17 skipped hydration for components that used i18n blocks, re-rendering them from scratch. In Angular 18, however, hydration for i18n blocks got into developer preview. To enable hydration for i18n blocks, you can add withI18nSupport to your provideClientHydration call. ` Third-Party Libraries with DOM Manipulation The last thing to consider is third-party libraries that manipulate DOM, such as D3 charts. They could cause DOM mismatch errors when hydration is enabled. You can use the ngSkipHydration attribute to skip hydration for components rendered using these libraries. Conclusion The Angular team has been doing great work to make the framework more modern and competitive, hearing the community feedback and adjusting the roadmap accordingly. And SSR is an excellent example of that. With the introduction of non-destructive hydration in Angular 16 and making it stable in Angular 17, the Angular team has taken a significant step forward in making SSR a first-class citizen in Angular. The @angular/ssr package is now part of the Angular CLI, making adding SSR to your Angular application easier. The Angular team plans to make SSR the default in the next version, further solidifying its position in the Angular ecosystem. However, as with any new feature, there are some constraints and best practices to follow when using SSR with Angular. You should be aware of hydration's limitations and ensure your application is compatible with it. However, if you follow the guidelines provided by the Angular team, you should be able to take advantage of the benefits of SSR without any significant issues....

Jun 26, 2024

8 mins

AngularJavaScriptExpress.js

Take your App to the Next Level with Vue 3

Vue 3 has now officially launched and you are probably wondering how you are going to start migrating your existing Vue 2 apps to Vue 3. I will be honest with you: a framework migration is always the most tedious and painstaking task you will ever encounter. The good news is that migrating from Vue 2 to Vue 3 is not that difficult and complicated. As you may know, Vue 3 source code has been written from scratch. However, the maintainers of the framework made sure not to change the API too much. In other words, we will benefit from all the goodies Vue 3 brings, with minimal change. How awesome is that?! Vue 3 Official Migration Guide The Vue documentation website has been refreshed to reflect the latest changes. The Vue community has maintained the best documentation to help us learn and use Vue. The Vue documentation dedicates a section on Vue 3 Migration making mention of the new features, the breaking changes for Vue 2 apps, the supporting libraries like Vue CLI, Vuex, Vue Router and others. The website explicitly states that the team is still working on a dedicated migration guide from Vue 2 to Vue 3. Meanwhile, until an official migration guide is released, let’s get a little insight on what could possibly be involved if you were to tackle this for yourself. What to consider before upgrading to Vue 3? As Vue 3 is still new, there will be some things to keep in mind. There are thousands of applications and third-party libraries created for Vue 2 and even Vue 1.5. It’s going to be a lengthy and time consuming effort to migrate all those libraries to support Vue 3. Before you attempt any migration process, make sure all the libraries you use are supported by Vue 3. For instance, Vuetify isn't. You can read more about this here. In addition, if you use any of the third-party libraries, they need to be checked or you might find they have upgraded already. Moreover, the Vue 3 reactivity system has been rewritten to utilize the new language features in ES2015. Vue 3 uses proxies for its reactivity system instead of the Object.defineProperty() function. JavaScript proxies are supported by most modern browsers. Unfortunately, Proxies cannot be polyfilled for older browsers; therefore, Vue 3 offers two implementations of it’s reactivity system. One implementation will use proxies for the most recent and modern browsers. The other one will fall back to the Vue 2 way of implementing reactivity to support the older browsers. Step by Step Migration - Demo In this section, we'll go through migrating the This Dot - Vue Meetup website. The existing website is built with Vue 2. It’s essential to follow the steps below as is. Of course, depending on the features you’ve used, you will adjust this workflow to fit your needs and migrate more features in your apps. Let's start! Step 1: Create a new Git branch It’s important to start off with a brand new branch to play around with the migration. This way your main branches, like master or dev, will remain intact without disrupting any live code. Let’s assume we are branching from the master branch. Run the following command to create a new branch: ` Step 2: Install the latest Vue CLI version Currently, as of the time of writing this article, the latest version of the Vue CLI is 4.5.6. To install the latest version, run the following command: ` Verify the installation by running the following command and making sure it reads as @vue/cli 4.5.6: ` Upgrading the Vue CLI not only helps in upgrading the existing application, but it also gives you the chance to scaffold a new Vue 3 app in the future. Step 3: Upgrade the Vue libraries The next step is to upgrade the Vue NPM packages and all other packages used inside the package.json file. To start with, open the package.json file and make sure to amend the Vue libraries with the following versions: ` Now, let’s upgrade the rest of the libraries using the Vue CLI. Run the following command to start upgrading the libraries: ` The command goes through all the libraries you are using inside the package.json file and tries to upgrade them to the latest compatible version. For example, when I run this command, the Vue CLI detects the Vue libraries that need to be upgraded and prompts for confirmation: Type Y to continue with the upgrade. In summary, the upgrade reported the following packages changes, additions, and removal. While the CLI is upgrading the @vue/cli-plugin-eslint it will also upgrade the current ESLint version installed on your computer. The latest Vue CLI supports ESLint v6. Once again, the Vue CLI prompts for confirmation before upgrading ESLint. Type Y to continue with the upgrade. ` The numbers will definitely be different for you and depending on the app. It’s now time to run the app and make sure you don’t have missing libraries or other problems. In my case, I ran the app and got a few ESLint issues. Luckily, the Vue CLI comes packaged with a command to auto fix ESLint issues. In this case, you run the npm run lint and the Vue CLI handles the rest for you! Step 4: Add the @vue/compiler-sfc NPM package The @vue/compiler-sfc package contains lower level utilities that you can use if you are writing a plugin / transform for a bundler or module system that compiles Vue single file components into JavaScript. It is used in the vue-loader. This is an essential component if you are using Single File Components which is the case in most of the Vue apps. Let’s install this package by running the following command: ` Let’s move on and start upgrading the source code to use the latest APIs offered by Vue 3. Step 5: Upgrade the main.js file Vue 3 changes the way an application is created by introducing the createApp() function. Back in Vue 2 and earlier versions, we used to create a global Vue instance. This approach had several disadvantages. The main one had third-party libraries to making changes to our Vue single App instance. By introducing createApp(), you can instantiate multiple Vue apps side by side. It creates a context or boundary for your app instance where you do all the registration as you will see shortly. Typically, a Vue app is started inside the main.js file. Let’s visit this file and make the necessary changes to upgrade to Vue 3. ` This is a slimmed down version of the original main.js file in the app. Let’s dissect the file one line at a time and upgrade accordingly. ` Replace the line above with: ` Let’s replace the code that’s creating the app using the Vue 3 createApp() function. ` Replace with: ` The app variable now holds a new Vue app instance for us. The router instance will be registered separately. Let’s update the Vue component registration. ` Replace with: ` With Vue 3, you register components at the app instance level and not globally. Let’s update the Vue mixin registration. ` Replace with: ` Now register the router on the app instance as follows: ` Now let’s register the vue-analytics plugin on the app instance. ` Replace with: ` The plugin is now installed on the app instance rather than the global Vue instance. This is also valid for any other plugin out there. Make sure to remove the line below as it’s not needed anymore in Vue 3 apps: ` Finally, let’s mount the app instance by using the following: ` The final version of the upgrade main.js file looks like this: ` That’s it! Step 6: Upgrade the router.js file The Vue Router has undergone changes and it’s now under v4.0. Let’s review what the current router.js file looks like: ` Replace the import statements with the following line: ` Instead of creating a new instance of the Router object, we will be using the new function provided by Vue Router which is createRouter(). ` The router.js file now exports an instance of the Router object using the createRoute() function. This function expects an input parameter of type object. The routes and history properties are the minimum accepted to pass into this object. The routes array is still the same as in Vue 2. It’s an array of routes, nothing has changed here. The createWebHashHistory() function is now used to specify a Hash History mode in the Vue Router. As a side note, depending on what you are using in your app, there is also the createWebHistory() function that sets the mode to HTML 5. You can read more about History Modes. Next, we will update the scrollBehavior() function as it has undergone some major changes. Replace the existing function with the following: ` You can read more about Scroll Behavior in the Vue Router 4.0. Now, let’s run the app and see if everything works as expected. When I run the app, I get the following warning in the Dev Tools: ` This warning has to do with Vue Router and the Transition component. You can read more about the Transitions in Vue Router. Let’s navigate to the App.vue component and check what the current source code is: ` In Vue Router v4.0, you can no longer nest a component inside a component. The fix is simple and provided to you in the documentation. Replace the above with the following: ` These were all the steps needed to upgrade the Vue Meetup app. Others I’d like to draw your attention to a few more things when upgrading your apps to Vue 3. One of the components in the app had a single slot; that is, the default slot. The way it was used in the Vue 2 app was: ` When I ran the app, the component was showing nothing, an empty screen! It seems Vue 2 was more tolerant by not forcing me to specify the name of the slot, even though this is the default slot. The quick fix in Vue 3 is as follows: ` Something else I didn’t mention is the Vuex v4.0. The same steps that we followed to upgrade the Vue Router can be followed here. The approach is similar. You can read more about the Vuex v4.0 Breaking Changes. Conclusion I am pretty sure we will all face more issues and encounter different hiccups while upgrading our apps. It will all depend on the features of your Vue 2. Remember, everything has a solution! While we wait for the Vue team to share an official migration guide, start trying to upgrade and see how you go. If you get stuck, feel free to drop me a message on twitter using my Twitter handle @bhaidar....

Sep 30, 2020

9 mins

Vue

Introduction to Zod for Data Validation

As web developers, we're often working with data from external sources like APIs we don't control or user inputs submitted to our backends. We can't always rely on this data to take the form we expect, and we can encounter unexpected errors when it deviates from expectations. But with the Zod library, we can define what our data ought to look like and parse the incoming data against those defined schemas. This lets us work with that data confidently, or to quickly throw an error when it isn't correct. Why use Zod? TypeScript is great for letting us define the shape of our data in our code. It helps us write more correct code the first time around by warning us if we are doing something we shouldn't. But TypeScript can't do everything for us. For example, we can define a variable as a string or a number, but we can't say "a string that starts with user_id_ and is 20 characters long" or "an integer between 1 and 5". There are limits to how much TypeScript can narrow down our data for us. Also, TypeScript is a tool for us developers. When we compile our code, our types are not available to the vanilla JavaScript. JavaScript can't validate that the data we actually use in our code matches what we thought we'd get when we wrote our TypeScript types unless you're willing to manually write code to perform those checks. This is where we can reach for a tool like Zod. With Zod, we can write data schemas. These schemas, in the simplest scenarios, look very much like TypeScript types. But we can do more with Zod than we can with TypeScript alone. Zod schemas let us create additional rules for data parsing and validation. A 20-character string that starts with user_id_? It's z.string().startsWith('user_id_').length(20). An integer between 1 and 5 inclusive? It's z.number().int().gte(1).lte(5). Zod's primitives give us many extra functions to be more specific about *exactly* what data we expect. Unlike TypeScript, Zod schemas aren't removed on compilation to JavaScript—we still have access to them! If our app receives some data, we can verify that it matches the expected shape by passing it to your Zod schema's parse function. You'll either get back your data in exactly the shape you defined in your schema, or Zod will give you an error to tell you what was wrong. Zod schemas aren't a replacement for TypeScript; rather, they are an excellent complement. Once we've defined our Zod schema, it's simple to derive a TypeScript type from it and to use that type as we normally would. But when we really need to be sure our data conforms to the schema, we can always parse the data with our schema for that extra confidence. Defining Data Schemas Zod schemas are the variables that define our expectations for the shape of our data, validate those expectations, and transform the data if necessary to match our desired shape. It's easy to start with simple schemas, and to add complexity as required. Zod provides different functions that represent data structures and related validation options, which can be combined to create larger schemas. In many cases, you'll probably be building a schema for a data object with properties of some primitive type. For example, here's a schema that would validate a JavaScript object representing an order for a pizza: ` Zod provides a number of primitives for defining schemas that line up with JavaScript primitives: string, number, bigint, boolean, date, symbol, undefined, and null. It also includes primitives void, any, unknown, and never for additional typing information. In addition to basic primitives, Zod can define object, array, and other native data structure schemas, as well as schemas for data structures not natively part of JavaScript like tuple and enum. The documentation contains considerable detail on the available data structures and how to use them. Parsing and Validating Data with Schemas With Zod schemas, you're not only telling your program what data should look like; you're also creating the tools to easily verify that the incoming data matches the schema definitions. This is where Zod really shines, as it greatly simplifies the process of validating data like user inputs or third party API responses. Let's say you're writing a website form to register new users. At a minimum, you'll need to make sure the new user's email address is a valid email address. For a password, we'll ask for something at least 8 characters long and including one letter, one number, and one special character. (Yes, this is not really the best way to write strong passwords; but for the sake of showing off how Zod works, we're going with it.) We'll also ask the user to confirm their password by typing it twice. First, let's create a Zod schema to model these inputs: ` So far, this schema is pretty basic. It's only making sure that whatever the user types as an email is an email, and it's checking that the password is at least 8 characters long. But it is *not* checking if password and confirmPassword match, nor checking for the complexity requirements. Let's enhance our schema to fix that! ` By adding refine with a custom validation function, we have been able to verify that the passwords match. If they don't, parsing will give us an error to let us know that the data was invalid. We can also chain refine functions to add checks for our password complexity rules: ` Here we've chained multiple refine functions. You could alternatively use superRefine, which gives you even more fine grained control. Now that we've built out our schema and added refinements for extra validation, we can parse some user inputs. Let's see two test cases: one that's bound to fail, and one that will succeed. ` There are two main ways we can use our schema to validate our data: parse and safeParse. The main difference is that parse will throw an error if validation fails, while safeParse will return an object with a success property of either true or false, and either a data property with your parsed data or an error property with the details of a ZodError explaining why the parsing failed. In the case of our example data, userInput2 will parse just fine and return the data for you to use. But userInput1 will create a ZodError listing all of the ways it has failed validation. ` ` We can use these error messages to communicate to the user how they need to fix their form inputs if validation fails. Each error in the list describes the validation failure and gives us a human readable message to go with it. You'll notice that the validation errors for checking for a valid email and for checking password length have a lot of details, but we've got three items at the end of the error list that don't really tell us anything useful: just a custom error of Invalid input. The first is from our refine checking if the passwords match, and the second two are from our refine functions checking for password complexity (numbers and special characters). Let's modify our refine functions so that these errors are useful! We'll add our own error parameters to customize the message we get back and the path to the data that failed validation. ` Now, our error messages from failures in refine are informative! You can figure out which form fields aren't validating from the path, and then display the messages next to form fields to let the user know how to remedy the error. ` By giving our refine checks a custom path and message, we can make better use of the returned errors. In this case, we can highlight specific problem form fields for the user and give them the message about what is wrong. Integrating with TypeScript Integrating Zod with TypeScript is very easy. Using z.infer<typeof YourSchema> will allow you to avoid writing extra TypeScript types that merely reflect the intent of your Zod schemas. You can create a type from any Zod schema like so: ` Using a TypeScript type derived from a Zod schema does *not* give you any extra level of data validation at the type level beyond what TypeScript is capable of. If you create a type from z.string.min(3).max(20), the TypeScript type will still just be string. And when compiled to JavaScript, even that will be gone! That's why you still need to use parse/safeParse on incoming data to validate it before proceeding as if it really does match your requirements. A common pattern with inferring types from Zod schemas is to use the same name for both. Because the schema is a variable, there's no name conflict if the type uses the same name. However, I find that this can lead to confusing situations when trying to import one or the other—my personal preference is to name the Zod schema with Schema at the end to make it clear which is which. Conclusion Zod is an excellent tool for easily and confidently asserting that the data you're working with is exactly the sort of data you were expecting. It gives us the ability to assert at runtime that we've got what we wanted, and allows us to then craft strategies to handle what happens if that data is wrong. Combined with the ability to infer TypeScript types from Zod schemas, it lets us write and run more reliable code with greater confidence....

Nov 15, 2024

7 mins

JavaScriptZod

Let's innovate together!

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

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

Mixing Storybook with Angular with a Sprinkle of Applitools

Create Angular 7 App using the latest CLI

Create the ContentEditable Component

Add Storybook packages

Create and run a few Storybook stories

Add and run Applitools Storybook SDK for Angular

Review test results on Applitools Test Manager

Conclusion

Bilal Haidar

You might also like

4 Angular Component Libraries That are Perfect for Beginners

SSR Finally a First-Class Citizen in Angular?

Take your App to the Next Level with Vue 3

Introduction to Zod for Data Validation

Let's innovate together!

You might also like

4 Angular Component Libraries That are Perfect for Beginners

SSR Finally a First-Class Citizen in Angular?

Take your App to the Next Level with Vue 3

Introduction to Zod for Data Validation