DEV Community: Dominik Pieper

Nx plugin development - Build your own Vite plugin

Dominik Pieper — Fri, 02 Dec 2022 16:57:25 +0000

Overview

An Nx plugin is an npm package to extend Nx itself. The most significant parts of that are generators and executors. Generators are the way to create files from templates, and executors are runners for something like the build process to package your application. It’s easy to get started.

With the upcoming Vite integration, let us build our own simple Vite package (for educational purposes).

Getting started

Let's start a new Nx workspace for our plugin development. Nx comes with two scripts to easily scaffold a whole workspace. These are create-nx-workspace and create-nx-plugin. The first one creates a new Nx workspace, so you probably used it already if you have ever used Nx. The second script creates an empty workspace with a new Nx plugin. Let's get started:

npx create-nx-plugin awesome-plugins --pluginName vite

It will create a new Nx workspace with the new plugin. The file structure looks like this:

A Nx plugin is just a regular npm package with some special marker files referred in the package.json. Here is our package.json:

{
    "name": "@awesome-plugins/vite",
    "version": "0.0.1",
    "main": "src/index.js",
    "generators": "./generators.json",
    "executors": "./executors.json"
}

It's generated into our Vite project and will be part of the package. It is just a regular package.json, except for the additional fields generators and executors. A generator is how Nx generates files, and an executor executes tasks like build or test. With these config files referred to in the package.json, Nx can find out what our plugin can do and what Nx can run with it.

Generators

Let's start with generators. Generators are the way to generate files in Nx. They are easy to use because they are plain Typescript with helper functions from the Nx devkit. The generator from @nrwl/nx-plugin (loop closed, you created an Nx plugin with an Nx plugin) created a generator called vite for us.


...

export default async function (tree: Tree, options: ViteGeneratorSchema) {
  const normalizedOptions = normalizeOptions(tree, options);
  addProjectConfiguration(tree, normalizedOptions.projectName, {
    root: normalizedOptions.projectRoot,
    projectType: 'library',
    sourceRoot: `${normalizedOptions.projectRoot}/src`,
    targets: {
      build: {
        executor: '@awesome-plugins/vite:build',
      },
    },
    tags: normalizedOptions.parsedTags,
  });
  addFiles(tree, normalizedOptions);
  await formatFiles(tree);
}

The shown function is the primary function of our generator. Generators are functions with a given signature. The first parameter is tree from type Tree. The Tree object is an abstraction of the filesystem and has methods to read, write and delete files. The second parameter here is specific to the generator. Besides the generator.ts the nx-plugin package created two files, the schema.d.ts and the schema.json. The schema.d.ts looks like this:

export interface ViteGeneratorSchema {
    name: string;
    tags?: string;
    directory?: string;
}

It's the Typescript inteface matching our generator parameters. A generator can have any number of parameters. If you call the generator like this:

nx generate @awesome-plugins/vite:vite --name=my-lib

The Nx cli will call your generator function and creates the object with type ViteGeneratorSchema filled with all your parameters. The second file is the schema.json and looks like this:

{
    "$schema": "http://json-schema.org/schema",
    "cli": "nx",
    "$id": "Vite",
    "title": "",
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "description": "",
            "$default": {
                "$source": "argv",
                "index": 0
            },
            "x-prompt": "What name would you like to use?"
        },
        "tags": {
            "type": "string",
            "description": "Add tags to the project (used for linting)",
            "alias": "t"
        },
        "directory": {
            "type": "string",
            "description": "A directory where the project is placed"
        }
    },
    "required": ["name"]
}

The schema.json is the cli configuration for your interface. You can set descriptions, default values, aliases, and so on for all parameters. Furthermore, it's possible to configure which parameters are required and which are optional. The Nx cli will use this file to show the descriptions to the user of our plugin and show errors, if required and the $default configuration for the name field allows to leave the --name parameter and just use the first parameter for it, like this:

nx generate @awesome-plugins/vite:vite my-lib

Now we know how to push parameters into our function, let's see what we can do with them. The vite generator does two main things, add some files and add a project configuration for the project generated by your generator. Let's take a look at the files first. In your generator there's a function called named addFiles(). This function is defined in the same file and looks like this:

function addFiles(tree: Tree, options: NormalizedSchema) {
    const templateOptions = {
        ...options,
        ...names(options.name),
        offsetFromRoot: offsetFromRoot(options.projectRoot),
        template: '',
    };

    generateFiles(
        tree,
        path.join(__dirname, 'files'),
        options.projectRoot,
        templateOptions
    );
}

The function generateFiles comes from the @nrwl/devkit package. The Nx devkit brings some useful functions you usually need to create plugins. (The @nrwl packages like @nrwl/angular or @nrwl/react also use them, so they're battle-tested by Nx.)

The generateFiles function takes the tree object into which the files should be generated. The other three parameters are the folder where the templates for the files are taken from, here the files directory in the same directory as the generator. The files directory contains a src dir with a file index.ts__template__.

The notation __template__ is the syntax for variables in filenames. Variables for templates are taken from the templateOptions object. It is just a plain Typescript object and every matching field from the object replaces the variable. The __template__ will be replaced with an empty string. Let's rename the file. We change the filename from index.ts__template__ to __name__.ts__template__. The name parameter used to set the name of your generated project now also is used to define the filename of the first file. After that, we create a new file index.html__template__ directly into the files directory and add the following content:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <title><%= name %></title>
    </head>
    <body>
        <div id="app"></div>
        <script type="module" src="/src/<%= name %>.ts"></script>
    </body>
</html>

The variable syntax for templates is <%= name %>. Again, they will be replaced while generating the files from the templateOptions object. After that, our generator directory looks like this:

Our generator is now prepared to create the files we want. Let's look at the configuration of our newly generated project. Our generator contains the following snippet:

addProjectConfiguration(tree, normalizedOptions.projectName, {
    root: normalizedOptions.projectRoot,
    projectType: 'library',
    sourceRoot: `${normalizedOptions.projectRoot}/src`,
    targets: {
        build: {
            executor: '@awesome-plugins/vite:build',
        },
    },
    tags: normalizedOptions.parsedTags,
});

The function addProjectConfiguration will exactly do what it is named. For our Nx workspace, it will create the project.json file for us. The created file will contain the following:

{
  "$schema": "../../node_modules/nx/schemas/project-schema.json",
  "name": "mygeneratedlib",
  "projectType": "library",
  "sourceRoot": "libs/mygeneratedlib/src",
  "targets": {
    "build": {
      "executor": "@awesome-plugins/vite:build"
    }
  },
  "tags": []
}

This is the configuration for our generated project. The whole project after you use your new plugin will be like this:

The configuration contains essential pieces of information like the sourceRoot and projectType, together with the targets. Possible targets are something like build and test, but they can be whatever you need. To be able to call Vite, we need to be sure it is added into the package.json. To do this, add the following into the generator, right after the addFiles call:

...
addDependenciesToPackageJson(tree, {}, {
    vite: '^3.2.4'
});
...

Again, this is a function from the nx devkit that helps add dependencies and install them. It will read the package.json from the Tree and add dependencies and devDependencies.

Now we have our dependency installed, let's implement our own build target for Vite.

Executors

As already said, executors are the Nx way to do something with your project. Parameters are identical to the generators configured. There is a schema.json file and a schema.d.ts file for them. The created Vite project already contains a build executor, which logs something and returns success:true.

export default async function runExecutor(options: BuildExecutorSchema) {
    console.log('Executor ran for Build', options);
    return {
        success: true,
    };
}

If you now used the generator to create mygeneratedlib, you can use:

nx build mygeneratedlib

The cli will log the message and exit. That's it. But we want to create our great Vite package, so we need to adjust things a little. First, we add the second parameter context: ExecutorContext to our function signature. Now we can look into the ExecutorContext with useful pieces of information about the workspace.
From the context, we can take the projectDir path we need for the Vite build process. Vite itself exposes a build function to start the build process, and we need to add the root where the process should be started. After that we choose an proper outDir to match the Nx file structure.

export default async function runExecutor(options: BuildExecutorSchema, context: ExecutorContext) {
    console.log('Executor ran for Build', options);

    const projectDir = context.workspace.projects[context.projectName].root;
    const distDir = joinPathFragments(`dist/${projectDir}`);

    await build({
        root: `${context.root}/${projectDir}`,
        build: {
            outDir: relative(projectDir, distDir)
        }
    });

    return {
        success: true,
    };
}

This is all we need to add a working Vite build process. Vite is just an example, but if you can run something from typescript, you can run it from an nx executor. Start to integrate whatever you want into Nx.

A demo workspace can be found here.

Testing

In the second part we will talk about how to test your plugin features.

Framework agnostic component libraries with StencilJs and Nx

Dominik Pieper — Mon, 07 Feb 2022 21:31:00 +0000

Why Stencil and WebComponents?

Web components are a collection of web standards that allow to create modular and reusable HTML elements. Common features of large frameworks like component lifecycles and dynamic are natively supported. Since they are standards-based only, you don't need a framework to run them; a modern browser is enough.

Web components primarily consist of the following 4 APIs from the web standards:

Custom Elements

The Custom Elemets standard gives us the possibility to define our own HTML elements.

Shadow DOM

The Shadow DOM allows us to encapsulate stylesheets and markup from the rest of the markup so that they no longer affect each other.

HTML Templates

With HTML Templates you can define reusable snippets. Within an HTML template, no scripts are executed, stylesheets are applied, or images are loaded. As long as it is not applied, it is not a regular part of the current document.

ES Modules

The ES Modules specification defines a standard way to import and reuse Javascript files in the most performant way.

Stencil building blocks

Stencil is a web component compiler developed by the team around the Ionicframework. Stencil is not the next framework but a compiler whose output format is standard-compliant web components. There are a few other compilers and frameworks that do this. There is the possibility to work without such a compiler, but this is quite bulky in handling and makes little sense, especially for a larger codebase.

import { Component, Prop, h } from '@stencil/core';

@Component({
    tag: 'my-component',
    styleUrl: 'my-component.css',
    shadow: true,
})
export class MyComponent {

    @Prop() name: string;

    render() {
        return <div>Hello, World! I'm ${this.name}</div>;
    }
}

Depending on personal experience with different frontend frameworks, at first glance, a Stencil component looks something like a mix of Angular and React.
Stencil uses TSX (JSX in Typescript) for templating and Typescript as the leading language for development. Common stylesheet preprocessors like Sass are supported as well as Less and PostCSS.

Hands-on with Nx

For a small example, we now create an empty Nx monorepo:

npx create-nx-workspace --preset=empty

And install the plugins that are important for us:

npm install --save-dev @nrwl/angular @nxext/stencil

With the Stencil plugin we now create a new library.

npx nx g @nxext/stencil:lib core --style='css' --buildable

Framework Integration

Stencil has support to generate extra wrappers for frameworks like Angular, React, Vue and Svelte. Although most of these frameworks can handle web components, they still feel like foreign bodies in the application. I'm using Angular as an example in the examples here.

Using the Stencil Nx plugin, you can generate the outputconfig with the corresponding Angular library.

npx nx g @nxext/stencil:add-outputtarget core --outputType='angular'

This adds the following to stencil.config.ts:

...
angularOutputTarget({
    componentCorePackage: '@agnostic-library/core',
    directivesProxyFile: '../../../libs/core-angular/src/generated/directives/proxies.ts',
    valueAccessorConfigs: angularValueAccessorBindings,
}),
...

After this, we created the following folder structure within the "libs" directory:

|
|-libs|-core
|       |-core-angular
|-...

With each build of the "core" library, wrapper components are now generated with Angular for each stencil component in the "core-angular" library folder. This is an Angular library without its own components, which only contains an Angular module for the export and the generated wrappers.

So that the new Angular library now also makes the components usable, these must be exported. For this, the new Angular module is extended and the new component is made known and usable in applications:

...
import { MyComponent } from '../generated/directives/proxies';

const components = [
   MyComponent
]

@NgModule({
    imports: [CommonModule],
    declarations: components,
    exports: components
})
export class CoreAngularModule {}

An Angular application can now import and use the library, but the Web Components must be made known to the browser for everything to work. Before that, we face the problem that the components are not rendered in the browser. For this, we enter the following into the main.ts of the Angular application:

import { defineCustomElements } from '@agnostic-library/core/loader';

defineCustomElements();

The generated Angular components use the original Web Components and make them feel like native Angular components.

This in itself does not sound very spectacular at first. I have observed over the years, especially in large companies, that the frameworks used for the frontend are changed from time to time, or several are used in parallel by different teams. If you now create component libraries via standards such as Web Components, which correspond to the corporate design, for example, these can be adapted quite quickly for all frameworks. This allows efforts to be bundled because a "build once, use everywhere" approach can be used. Not every component has to be rewritten in every framework, but they can be shared. As a small bonus and since Web Components only need a browser as an environment, they can also be used without a framework, e.g., on the company website or landing pages.

On Github is a small example and in the Nxext Demo a somewhat larger repository with more extensive components, an Angular application with backend.