Forem: Dmitriy Stepanenko

Qwik reaches the v1, so does qwik-nx!

Dmitriy Stepanenko — Wed, 03 May 2023 13:55:30 +0000

A lot has happened since we introduced the qwik-nx, an official plugin for the Qwik framework. As Qwik breaks free by reaching the v1, we’re happy to announce the release of the stable version of the Nx integration for it.

A few words about Qwik

Qwik is referred to as a next-generation framework because of its revolutionary new approaches to performance optimization, among which:

JavaScript Streaming - an ability to load and execute only the bare minimum of the code as Qwik analyses and splits your code into chunks up to a function level. Those chunks are prefetched in a separate thread, similar to "buffering" in video streaming. The prefetched code only executes upon user action;
resumability - a new rendering paradigm to bring you instantly interactive apps by serializing/deserializing your app as it goes from SSR to client without the need for hydration;

In practise this means that you get an app with O(1) size, as its initial bundle is constant at about 1kb no matter the application complexity.

This is extremely beneficial for enterprise companies, that usually want to bring an enormous amount of functionality to their users without any performance impact.

While Qwik helps to scale the application's functionality expressed via code without effort, Nx is there to make sure your codebase can be managed at any scale. And here's where qwik-nx comes into play. It provides the same experience of the generation and execution of Qwik applications in an Nx workspace that fits the standards of other Nx projects.

What's new?

In the previous article, we have talked about how you get started by initializing your Nx repository with Qwik.

Recap: you can generate a new workspace by running:

npx create-nx-workspace@latest org-workspace --preset=qwik-nx

Or add a new Qwik application to an existing workspace by running:

npm install -D qwik-nx

and then

nx generate qwik-nx:app

Today let's talk about what new opportunities does it offer:

`qwikNxVite` plugin

If you stick to using Qwik with Nx from its first days, you might have noticed that importing Qwik components from libraries does not work out of the box as all those dependencies should be configured as vendorRoots for qwikVite plugin in order for Qwik Optimizer to actually include and process them.

The good news is you don't have to do it manually any more: qwikNxVite plugin will by default analyze the Nx dependency graph and put all libraries your app uses as vendorRoots for the Qwik Optimizer to consume.

// vite.config.ts

import { qwikNxVite } from 'qwik-nx/plugins';

export default defineConfig({
  plugins: [
    qwikNxVite(), // <= that's all you need!
    qwikCity(),
    qwikVite(),
    tsconfigPaths({ root: '../../' }),
  ],
  ...
});

And this behavior can be fine-tuned even further to make sure you're including only what's intended. As an example, you can mark all Qwik-specific libraries with a specific tag and filter your vendorRoots with it. Let's see how you can leverage the usage of "framework:qwik" tag.

1) Mark libs you need with the respective tag:

// some lib's project.json
{
...
"tags": ["type:ui", "scope:products", "framework:qwik"]
}

2) Configure the plugin

// app's vite.config.ts
qwikNxVite({ 
  // filter out all projects that does not have this tag
  // use "tags", "name", "path" regex 
  // or even "customFilter" to achieve desired filtering logic
  includeProjects: { tags: ["framework:qwik"] } 
  debug: true // <= put this to see what projects are included
})

This configuration will make qwikNxVite plugin to load only libraries that have respective tag AND are recognized by Nx as your app's dependency.

Pro tip

You can configure the Nx Console to always put the tag you want as a default value for the tags field for the qwik-nx:library generator. This can be achieved by setting that default value in the build options of nx.json

{
  "generators": {
    "qwik-nx:library": {
      "tags": "framework:qwik"
    }
  }
}

Automatic versions migrations

One of the biggest benefits of using Nx to manage the codebase is their seamless migration process: with a single command nx migrate latest Nx CLI will analyze the workspace and provide the set of migrations written by Nx team to update versions of your dependencies and mutate all necessary bits of code. This is a great capability that allows large codebases to always stay up to date without investing weeks of refactoring.

qwik-nx aims to provide the same feature for its users to make sure your Qwik apps are updated. This means you don't have to update the app's dependencies manually anymore, just run
nx migrate qwik-nx@latest and you are done: it will update all breaking changes and bump versions of Qwik packages.

React integration

Qwik offers a great capability to qwikify$ React components - reuse existing React components and libraries within Qwik applications. Not only does this open the world of using existing UI libraries (Material UI, Threejs, React Spring, etc.) and utilities that were developed for React over time within Qwik applications, but also this turns out to be a powerful migration strategy, as you can migrate your existing React applications chunk by chunk, preserving large parts of functionality in the old syntax without a need to rewrite everything at once.

As React and Qwik components can not be mixed in the same file, if you check your project right after adding React integration to a plain Qwik app, you will see a new folder src/integrations/react/, and its recommended to place all React components there.

qwik-nx gives you more control over structuring your "qwikified" react code by defining 2 approaches for you:

use a react-in-app generator, that behaves in the same manner as native Qwik integration. It will add integrations/react folder in the existing Qwik app
react-library generator, which will create a separate library to keep qwikified components in it. This means you can now structure your React code as you need and still be able to use it within Qwik apps.

In the Qwik repository there're opened PRs for Angular, Vue and Svelte integrations. As soon as they're available, you will also be able to generate separate libraries for components of those frameworks.

Storybook integration

qwik-nx now supports adding storybooks for your apps and libs! We get you covered in all scenarios:

run nx g qwik-nx:storybook-configuration to add storybook to your existing libs and apps
generate a new library with a preconfigured storybook and stories for newly generated components by running nx g qwik-nx:library mylib --storybookConfiguration
add a new component along with a story for it by running nx g qwik-nx:component --generateStories

Deployments

Qwik offers a variety of ways to deploy your app with its CLI, such as Netlify, Cloudflare Pages, Azure, Vercel, etc. With qwik-nx, we already provide support for Cloudflare Pages with Netlify and other integrations on their way.

To try it out, all you have to do is run nx g qwik-nx:cloudflare-pages-integration myapp. This will create a Cloudflare adapter and add necessary targets to preview and deploy your website with Wrangler (Cloudflare CLI tool).

Build executor

As you probably know, Qwik builds your code twice, running a client build first and an SSR one after that. In the Nx world, each step of the process is supposed to be a separate target of the application, so that you can keep full control of what you're building.

To achieve this, we're exposing real build steps and wrapping them into our custom build executor.

{ 
 "targets": [
    "build": {
      "executor": "qwik-nx:build",
      "options": {
        "runSequence": [
          "myapp:build.client", 
          "myapp:build.ssr"
        ],
        "outputPath": "dist/apps/myapp"
      }
    },
    "build.client": {
      "executor": "@nrwl/vite:build",
      "options": {
        "outputPath": "dist/apps/myapp",
        "configFile": "apps/myapp/vite.config.ts"
      }
    },
    "build.ssr": {
      "executor": "@nrwl/vite:build",
      "options": {
        "outputPath": "dist/apps/myapp"
      }
    }
  ]
}

The cool thing with this build executor is that you can customize and add additional targets to the build process if that's needed. For example, you can add "myapp:i18n" target to the runSequence property in order to process your translations after building the app.

Oh, and keep in mind that build executor has another important purpose: it runs type checks for your app before building it!

Micro frontends

Qwik is able to render multiple application instances within the page as it can be attached to an HTML element, that becomes the root of the application. Inspired by this awesome article, we've added micro-frontend support to the Qwik apps. As of now this functionality is in beta

The intent is to bring the same level of convenience as what you get with Nx's tooling to generate and run Module Federation setup with React and Angular.

qwik-nx provides all necessary generators and executors to use it with ease.

To get started, run the following:

nx g qwik-nx:host shell --remotes=products,settings, which will scaffold the host application and 2 remotes for it
nx g qwik-nx:remote myanotherremote --host=shell to add a new remote application to your existing setup

That is it! You can now run either nx serve shell or nx preview shell and see both host and remotes built and served together. This is because qwik-nx's executors for serve and preview are able to process all remotes for you with 0 configuration.

Excited? Go try it out!

The package already provides a solid way of working with Qwik applications within Nx workspaces. Our main goal is to eventually reach feature parity with Qwik CLI.

So feel free to try it out and let us know how it works out for you!

You are welcome to join the Qwikifiers and Qwik Discord servers to keep track of any updates or find any help you need.

We are also looking forward to see any new contributions to the package itself https://github.com/qwikifiers/qwik-nx

Last but not least, we'd like to extend a heartfelt thank you to Ryan Hutchison and ASI Central for their unwavering support of our project.

Need Help?

At Valor Software, we are passionate about staying at the forefront of technology and are integration partners with the creators of Qwik, Builder.io. If you have any questions or need assistance with your project, don't hesitate to contact us at sales@valor-software.com.

Avoiding common pitfalls with ControlValueAccessors in Angular

Dmitriy Stepanenko — Sat, 14 Jan 2023 15:55:43 +0000

One of the biggest advantages of Angular is the variety of tools and solutions that are brought to developers out of the box. One of them is the @angular/forms package, which brings the solid experience of working with any kind of UI controls.
But have you ever wondered, how exactly this works under the hood? The only thing that needs to be done in order to tie FormControl with, let's say, a plain input is using a "formControl" binding on the input element, pointing that UI element to the instance of a FormControl.



<input type="text" [formControl]="ctrl" />

And voila, everything works.

But obviously, there should be a component or directive that Angular uses to make everything happen. And that "something" can be found here: Angular brings a set of directives like default_value_accessor.ts, select_control_value_accessor.ts, checkbox_value_accessor.ts, etc. All of them implement the ControlValueAccessor interface, which, according to docs, "Defines an interface that acts as a bridge between the Angular forms API and a native element in the DOM."

This means any component can be easily defined as a form control by implementing this interface and registering itself as an NG_VALUE_ACCESSOR provider. In practice, it requires you to define 4 methods:



interface ControlValueAccessor {
  writeValue(obj: any): void
  registerOnChange(fn: any): void
  registerOnTouched(fn: any): void
  setDisabledState(isDisabled: boolean)?: void
}

*although setDisabledState is optional, there’re only a few rare scenarios when it’s indeed not needed

To understand how exactly everything works, let’s have a look at the very basic counter component:



<lib-counter [formControl]="counter"></lib-counter>
<div>Counter Value: {{ counter.value }}</div>

Here’s the code of the component itself:



import { ChangeDetectionStrategy, ChangeDetectorRef, Component, forwardRef } from '@angular/core';
import { ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';

const COUNTER_CONTROL_ACCESSOR = {
    provide: NG_VALUE_ACCESSOR,
    useExisting: forwardRef(() => CounterControlComponent),
    multi: true,
};

@Component({
    selector: 'lib-counter',
    template: `
        <button (click)="down()" [disabled]="disabled">Down</button>
        {{ value }}
        <button (click)="up()" [disabled]="disabled">Up</button>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    providers: [COUNTER_CONTROL_ACCESSOR],
})
export class CounterControlComponent implements ControlValueAccessor {
    disabled = false;
    value = 0;

    protected onTouched: () => void;
    protected onChange: (value: number) => void;

    constructor(private _cdr: ChangeDetectorRef) {}

    up() {
        this.setValue(this.value + 1, true);
    }

    down() {
        this.setValue(this.value - 1, true);
    }

    registerOnChange(fn: (value: number) => void) {
        this.onChange = fn;
    }

    registerOnTouched(fn: () => void) {
        this.onTouched = fn;
    }

    setDisabledState(isDisabled: boolean) {
        this.disabled = isDisabled;
    }

    writeValue(value: number) {
        this.setValue(value, false);
        this._cdr.markForCheck();
    }

    protected setValue(value: number, emitEvent: boolean) {
        const parsed = parseInt(value as any);
        this.value = isNaN(parsed) ? 0 : parsed;
        if (emitEvent && this.onChange) {
            this.onChange(value);
            this.onTouched();
        }
    }
}

As you see here we’re implementing 4 methods and providing COUNTER_CONTROL_ACCESSOR. This is needed in order to let Angular know it deals with an instance of a form control.

So what’s happening with control is:

Once FormControl is initialised, it invokes writeValue, registerOnChange and registerOnTouched methods on the counter component. This syncs the initial state of the FormControl with our counter and also passes onTouched and onChanged methods into the counter, so it can talk back to the FormControl when the user interacts with it.
When the value is changed, FormControl invokes the writeValue method, so counter updates its internal state without triggering the onChange/onTouched methods.
When the user interacts with our counter, it’s required to not only update the internal state but also notify parent FormControl about this state change, thus onChange/onTouched methods are invoked.

Although that’s not really a lot going on here, it is worth taking a look at a few important implementation details. And this is actually what this article is about

Common pitfalls with CVAs and how to avoid them

`onChange` should be only triggered by an internal event

It’s important to keep in mind that these methods should only be used to notify FormControl about the change that was triggered in the component internally. In other words, if FormControl changes the value of the component, it should never notify FormControl back about this change. This is a quite common mistake as it won’t break anything at the first glance, instead you’ll be able to notice it by subscribing to valueChanges of the bound FormControl:



export class AppComponent {
  readonly animal = new FormControl(‘rabbit’);

  constructor() {
    ctrl.valueChanges.subscribe(console.log);
    animal.setValue(‘hare’);
    animal.setValue(‘cat’);
  }
}

In the normal scenario by executing the code above you will see only 2 logs: ‘hare’, ‘cat’. However, if your writeValue method ends up invoking onChange you will see doubled console logs in the output: ‘hare’, ’hare’, ‘cat’, ‘cat’.

Here’s a modified code of CounterComponent where this issue can be seen, when FormControl invokes writeValue we notify it back with the onChange method:



// ... code of CounterComponent
writeValue(value: number) {
    // it's convenient to reuse existing "setValue" method, right?
    // however, this will lead to the incorrect behavior
    this.setValue(value);
    this._cdr.markForCheck();
}

protected setValue(value: number) {
    const parsed = parseInt(value as any);
    this.value = isNaN(parsed) ? 0 : parsed;
    if (this.onChange) {
        this.onChange(value);
        this.onTouched();
    }
}

`onChange` and `onTouched` should not always be called together

onChange/onTouched methods actually serve completely different purposes. While onChange is used to pass data when a component’s state changed internally, onTouched should be invoked after the user interacts with the component. This doesn’t always mean the component’s value is changed.

onTouched method is used in 2 cases:

by FormControl to update its touched state
when you set up your control to use updateOn: “blur" https://angular.io/api/forms/AbstractControl#updateOn, FormControl uses it to properly identify this blur event to apply the value to itself

For the CounterComponent both touch and change events are combined because the only way to interact with it is by clicking the button. However, with other components, the flow will be different. For instance, a plain <input /> element with a tied FormControl (with DefaultValueAccessor under the hood) is expected to be marked as touched when the user interacts with the input even by focusing it. Thus, for this kind of components onTouched emission should be tied to the blur event from the input.

Handling nulls properly

With an introduction of typed forms, form controls can now either infer a type from the default value or be typed explicitly. There’s an interesting thing, though: if we define a control const control = new FormControl<string>() and then check its type, it will be string | null. And you might wonder: why does the type of this control include null? This is because the control can become null at any time, by calling the reset() method on it. Here’s an example from angular docs:



const control = new FormControl('Hello, world!');
control.reset();
console.log(control.value); // null

Although this becomes quite obvious with typed forms, this behavior was inherent in forms from the very beginning. And while new handy types may catch issues with control’s values, it doesn’t really save you from any issues with nulls inside your CVA. Moreover, since CVA component doesn’t have any control over the form it’s being used within and there’s no way to enforce certain types of control on the form, it’s possible to actually pass literally any value into the control. Hence this value will end up passing into the writeValue, which can potentially break your component.

Let’s change our CounterComponent as follows:



// ... code of CounterComponent
writeValue(value: number) {
    // it's convenient to reuse existing "setValue" method, right?
    // however, this will lead to the incorrect behavior
    this.setValue(value, false);
    this._cdr.markForCheck();
}

protected setValue(value: number, emitEvent: boolean) {
    this.value = value;
    if (emitEvent && this.onChange) {
        this.onChange(value);
        this.onTouched();
    }
}

CounterComponent is too simple to have big issues with null because JavaScript will cast null into 0 (null + 1 = 1), but as you can see component is visually broken after reset() is called. So it’s very important to keep in mind this behavior and implement some value protections for the writeValue method.

Standardising your custom UI form components with ControlValueAccessor Test Suite

Even if you keep in mind all the potential pitfalls listed above, there’s always a chance something will go wrong due to some change or enhancement in the future. The best way to maintain the valid behavior of a component is to have extensive unit test coverage. However, it might be annoying to write the same list of tests for all CVA components or some use cases can be accidentally left without coverage. So it should be much better to have one unified testing solution, that can keep your components safe.

And there’s one called ngx-cva-test-suite. It’s a small npm package, that provides an extensive set of test cases, ensuring your custom controls behave as intended. It is designed and tested to work properly with both Jest and Jasmine test runners.

Among the main features:

ensures the correct amount of calls for the onChange function (incorrect usage may result in extra emissions of valueChanges of formControl)
ensures correct triggering of onTouched function (is needed for touched state of the control and updateOn: 'blur' strategy to function properly)
ensures that no extra emissions are present when control is disabled
checks for control to be resettable using AbstractControl.reset()

It is quite easy to be configured, here’s the usage scenario for the CounterComponent we looked into within this article:



import { runValueAccessorTests } from 'ngx-cva-test-suite';
import { CounterControlComponent } from './counter.component';

runValueAccessorTests({
    /** Component, that is being tested */
    component: CounterControlComponent,
    /** 
     * All the metadata required for this test to run. 
     * Under the hood calls TestBed.configureTestingModule with provided config.
     */
    testModuleMetadata: {
        declarations: [CounterControlComponent],
    },
    /** Whether component is able to track "onBlur" events separately */
    supportsOnBlur: false,
    /** 
     * Tests the correctness of an approach that is used to set value in the component, 
     * when the change is internal. It's optional and can be omitted by passing "null"
     */
    internalValueChangeSetter: null,
    /** Function to get the value of a component in a runtime. */
    getComponentValue: (fixture) => fixture.componentInstance.value,
    /** When component is reset by FormControl, it should either get a certain default internal value or "null" */
    resetCustomValue: { value: 0 },
    /** 
     * This test suite applies up to 3 different values on the component to test different use cases. 
     * Values can be customized using this configuration option.
     */
    getValues: () => [1, 2, 3],
});

You can learn more about usage examples in the package’s repository or get inspiration by looking at a few CVA components that are placed within the repository here.

Introducing Qwik integration for Nx

Dmitriy Stepanenko — Fri, 30 Dec 2022 14:00:55 +0000

Intro

While the Qwik framework itself confidently continues its way to v1, it feels like an exactly right time to introduce the Nx plugin for it, which is named qwik-nx. The main functionality that this plugin provides is the generation and execution of Qwik applications in an Nx workspace that fits the standards of other Nx applications.
Since Qwik itself uses Vite as a build tool, this Nx plugin leverages the functionality of the brand new @nrwl/vite package to build and run your Qwik applications.

Getting started

The first thing to be done in order to get started is to generate an Nx workspace. qwik-nx plugin is one of the first that uses Nx’s custom interactive presets, so all you need to do is simply run npx create-nx-workspace@latest --preset=qwik-nx. You will firstly be prompted with generic questions like what workspace name to use and whether to enable Nx Cloud and after short initialization it will proceed with Qwik specific questions.

Once done, you will end up with a pretty much regular Nx repository with a Qwik application with Qwik city and all relevant dependencies installed.

At this point it is only possible to create a basic app with Qwik City, but we are planning to include all other starters that standard Qwik CLI provides.

Creating new applications, libraries and components

Upon setting up the workspace, we will get access to a bunch of neat generators that the qwik-nx plugin has prepared. It’s highly recommended to use Nx console plugins for VS Code and Webstorm, since they do the perfect job visualizing all configuration options and actual changes with dry runs.

Generating new apps

In VS Code’s Nx Console by clicking generate => qwik-nx - application you will see the following options

Alternatively you can run npx nx generate qwik-nx:application <name> with the same options you see on the screenshot above. With everything left as-is we will end up with exactly the same application as what was created during the initialization process.

There is a lot of excitement around tailwind as well, so it is worth mentioning that it’s possible to include tailwind configuration for the app that is being created using the tailwind option. If you haven’t done so, you can always do it later by running npx nx generate qwik-nx:setup-tailwind –project=<application name>.

Generating libs

qwik-nx:library generator is built upon the standard Nx library generator, so it does pretty much what you would expect from it: there’re generic options for Nx libs along with Qwik specific ones.

Generating components

qwik-nx plugin also provides an ability to qwikly (you got this one, right?) scaffold a new component for your app. All you have to do is run the qwik-nx:component generator and select the project for the new component to be placed in. It is also highly configurable as per options shown on the screenshot below.

As of now there's no "route" generator, but expect to see it added soon.

Running and building the code

qwik-nx plugin replaces direct invocation of build, serve and test commands with Nx generators to standardize these tasks in a consistent and predictable manner. Plugin relies on executors provided by the @nrwl/vite package. Here’s the list of commands available for the Qwik application:

serve - uses @nrwl/vite:dev-server executor to run the app in the development mode with hot reloads
build - uses @nrwl/vite:build executor to generate the bundle for the client side app
build-ssr - also uses @nrwl/vite:build executor to generate code needed for Vite preview server
preview - wraps up build commands above in order to run the app simulating production mode https://qwik.builder.io/docs/getting-started/#running-in-production
test - uses @nrwl/vite:test executor that relies on vitest
lint - just a regular @nrwl/linter:eslint executor

Wrapping up

Nx by itself is an awesome tool with great capabilities of managing code in distributed fashion with one or more applications in the repository. With the qwik-nx plugin, Qwik applications and libraries can fit seamlessly into an Nx monorepo, making it easier for developers to achieve their goals.
Being focused on speed and performance, Qwik framework promises to be the next revolutionary solution in web development. As we move forward, qwik-nx plugin will evolve and become more capable and feature-rich as Qwik itself does.

Forem: Dmitriy Stepanenko

Qwik reaches the v1, so does qwik-nx!

A few words about Qwik

What's new?

qwikNxVite plugin

Pro tip

Automatic versions migrations

React integration

Storybook integration

Deployments

Build executor

Micro frontends

Excited? Go try it out!

Need Help?

Avoiding common pitfalls with ControlValueAccessors in Angular

Common pitfalls with CVAs and how to avoid them

onChange should be only triggered by an internal event

onChange and onTouched should not always be called together

Handling nulls properly

Standardising your custom UI form components with ControlValueAccessor Test Suite

Introducing Qwik integration for Nx

Intro

Getting started

Creating new applications, libraries and components

Generating new apps

Generating libs

Generating components

Running and building the code

Wrapping up

Need Help?

`qwikNxVite` plugin

`onChange` should be only triggered by an internal event

`onChange` and `onTouched` should not always be called together