Forem: jogelin

🍒 Cherry-Picked Nx v19.1 Updates

jogelin — Mon, 27 May 2024 07:48:04 +0000

[🌊 Nx Core]

Typescript declarations support for esbuild libraries

You can see two new properties in the @nx/esbuild:esbuild executor:

...
    "build": {
      "executor": "@nx/esbuild:esbuild",
      "options": {
        ...
        "declaration": true,
        "declarationRootDir": "libs/my-lib/src", // root by default
        ...
      }
    },
...

Generate declaration (*.d.ts) files for every TypeScript or JavaScript file inside your project. Should be used for libraries that are published to an npm repository.

New separator option for the result of the nx show command

https://nx.dev/nx-api/nx/documents/show

nx show projects --affected --type=app --sep ","

Target another executor in schema definitions

Angular 18 introduced a way to map one builder to another one. It is also now possible to use that approach with Nx in the executors.json:

{
  "executors": {
    // New
    "build": "@org/my-plugin:build",

    // Current
    "serve": { 
      "implementation": "...",
      "schema": "...",
      "description": "..."
    },
  },
  ...
}

Support bun Package Manager!

First, install bun by following the documentation. Then you can generate a new Nx workspace by using:

bunx create-nx-workspace

[💫 Upgrades]

Support Angular 18

Looking for some help? 🤝Connect with me on Twitter • LinkedIn • Github

🍒 Cherry-Picked Nx v19 Updates

jogelin — Mon, 27 May 2024 07:42:07 +0000

Release Note 19 (2024–05–06)

[🌊 Nx Core]

Metadata Property in Project Configuration

Already covered in my previous blog post on v18.3, Nx introduced a new metadata property in the project.json:

{
  "name": "my-java-project",
  "metadata": {
    "technologies": ["java17"],
    "ciRunner": "ubuntu-20.04-m6a.large",
    "owners": ["backend-team"]
  },
  ...
}

In Nx v19, you’ll be able to generate these metadata directly from your plugins:

export const createMetadata: CreateMetadata = (graph) => {
  const metadata: ProjectsMetadata = {};
  metadata['my-java-project'] = {
    metadata: {
      technologies: ['java17'],
      ciRunner: 'ubuntu-20.04-m6a.large',
      owners: ['backend-team']
    }
  }
  return metadata;
}

This opens many possibilities for project customization like listing technologies or the runner you want to use on your CI.

It also helps define a project type described in my article 👥 Reproducible Nx Workspace with HugeNx’s Conventions.

Change imports for the Webpack plugin

It is always a better idea not to expose all utilities in the same index.ts especially when they are not related. It has an impact on the config loading for example.

Here is a good decision from Nx related to Webpack configurations:

Before

const { NxAppWebpackPlugin } = require('@nx/webpack');
const { NxReactWebpackPlugin } = require('@nx/react');

After

const { NxAppWebpackPlugin } = require('@nx/webpack/app-plugin');
const { NxReactWebpackPlugin } = require('@nx/react/webpack-plugin');

Global forwardAllArgs for nx:run-commands

Before, when you had multiple commands in your nx:run-commands executor, you had to specify for each command if you wanted or not to forward arguments:

    "configure-branch-environment": {
      "executor": "nx:run-commands",
      "options": {
        "commands": [
          { 
            "command": "echo \"BRANCH=$(git branch --show-current)\" > .local.env",
             "forwardAllArgs": false 
          },
          { 
            "command": "echo \"COMMIT_SHA=$(git rev-parse HEAD)\" >> .local.env",
             "forwardAllArgs": false
          },
          { 
            "command": "ls",
             "forwardAllArgs": false 
          },
          { 
            "command": "cat .local.env",
             "forwardAllArgs": false 
          }
        ],
        "cwd": "{projectRoot}"
      }
    },

Now you can specify it globally:

    "configure-branch-environment": {
      "executor": "nx:run-commands",
      "options": {
        "commands": [
          "echo \"BRANCH=$(git branch --show-current)\" > .local.env",
          "echo \"COMMIT_SHA=$(git rev-parse HEAD)\" >> .local.env",
          "ls",
          "cat .local.env"
        ],
        "cwd": "{projectRoot}", 
        "forwardAllArgs": false
      },
    },

[💎 Project Crystal]

Add generators to convert projects to inferred targets

[💫 Upgrades]

Support React 18.3

[🌐 nx.dev]

Main Navigation Menu

New Blog Page

https://nx.dev/blog

New Enterprise Page

https://nx.dev/enterprise

[☁️ Nx Cloud]

DTE v2

https://nx.dev/ci/reference/release-notes#dte-algorithm-v2-experimental-flag

NX_CLOUD_DTE_V2: 'true'

Looking for some help? 🤝Connect with me on Twitter • LinkedIn • Github

👥 Reproducible Nx Workspace with HugeNx’s Conventions

jogelin — Sun, 05 May 2024 06:13:02 +0000

After migrating multiple organizations to an Nx Monorepo and maintaining it, I discovered that with each major Nx version, I was generating a new repository on the side, mimicking my existing repo, to compare configuration files and ensure they matched the latest version of Nx.

However, recreating an entire repo to mirror my original was labor-intensive. I began using Bash scripts, then Node.js scripts, and finally, I developed HugeNx, a custom Nx preset that generates a workspace from a configuration file.

After further reflection, I realized I wasn’t just creating a file to generate a workspace; I was crafting a file that would describe workspace conventions and could be utilized for many other purposes.

jogelin / huge-nx

Huge

HugeNx is a toolkit designed to dynamically generate and manage Nx workspaces by adhering to established workspace conventions.

Getting Started

1. Define your HugeNx's conventions:

For example let's create a conventions file angular-monorepo.conventions.ts that match the default Nx angular-monorepo preset:

export default {
  version: '1.0',
  generators: {
    '@nx/angular:application': {
      bundler: 'esbuild',
    },
    '@nx/angular:library': {
      linter: 'eslint',
      unitTestRunner: 'jest',
    },
  },
  projectTypes: {
    'global:angular:application': {
      projectPattern: '*-app',
      generators: [{ generator: '@nx/angular:application' }],
    },
    'global:angular:lib:feature': {
      projectPattern: '*-feature',
      generators: [{ generator: '@nx/angular:library' }],
    },
  },
  workspace: {
    apps: {
      'my-app': 'global:angular:application',
    },
    libs: {
      'my-feature': 'global:angular:lib:feature',
    },
  },
};

2. Use create-huge-nx client to generate

…

View on GitHub

HugeNx’s Conventions

The main concept behind this library is the HugeNx’s Conventions file — a configuration file that groups all conventional decisions you’ve made about your Nx workspace. This file will describe how your workspace should look.

If HugeNx’s Conventions file contains all the information on your targeted workspace, it means you can generate a new workspace from scratch or even maintain an existing one.

ProjectTypes

The first main convention I wanted to integrate is the concept of Nx ProjectType.

When you delve into the various resources about structuring an Nx workspace, you’ll encounter extensive explanations on categorizing your library by scope or type and creating tags that establish your boundaries:

However, I always missed a centralized way to specify this list of ProjectTypes. When you generate a project you lose the link with its source generator and its related technologies.

This is why I wanted to keep that information. With the help of HugeNx’s Conventions, you can recognize your projects because they will follow the conventions you specified in them.

I already explain the importance of conventions in my article ⚡ The Super Power of Conventions with Nx.

Reproducible Generation

When you start a project with Nx, everything is clean and aligned. But after some years we apply migrations, create custom generators, manually modify configurations, etc. All of that, coupled with developer turnover, and you end up with a good Ratatouille.

This is a common challenge we try to solve in IT, especially at the infrastructure level with the concept of infrastructure as code. The usage of tools like Ansible allows us to initialize and reconfigure an entire infrastructure from scripts and configuration files.

With Nx, you can use the list of presets, but it is hardcoded. There is some flexibility for each with some options, but not enough to generate a more advanced workspace.

If you want to create a more advanced workspace, you’ll need to create your custom preset. It is useful for creating a seed but not for quickly generating a workspace for comparison, demo, or workshop; it can be cumbersome.

This is why I decided to create a custom Nx preset that can generate an Nx workspace just by using HugeNx’s Conventions. You don’t need to create or maintain your own preset!

You can regenerate your entire repository for any Nx version. This would help for comparing what changed and also for simplifying the way we currently create Nx presets.

HugeNx supports all Nx plugins so you can easily reproduce all Nx presets and even create your custom preset.

Consistent Monorepo

Generating your repository from scratch is good, but being able to maintain it for a long time is even better, right?

The main goal of HugeNx’s Conventions is to be the guardian, the housekeeper that will describe how your workspace should look and behave.

Eslint Conventions Rules:

With the help of tools like Eslint, you can read that file and create rules to enforce conventions and:

Validate that each project follows the naming conventions
Validate the workspace structure
Validate that each project is correctly related to one ProjectType
Validate the nx.json generator’s options

Project Discovering:

With the project inference provided by the Nx Project Crystal, you can easily discover your Nx project based on your naming convention.

You can also create one Nx plugin that matches the ProjectType naming convention and attach the project configuration automatically!

Migration:

Related to the fact that you can regenerate a new workspace from scratch for a specific Nx version, you can now easily generate a workspace with the latest Nx and compare it with your workspace.

huge-nx - snappify.com

A powerful design tool to animate your code snippets in various ways.

snappify.com

You can also use tools like Betterer if you want to migrate step by step your repository to your HugeNx’s Conventions.

ProjectType Generator:

There is no need to create and maintain complex custom generators. You can create a generator that will read your ProjectTypes and generate a project from it.

Stay tuned for future implementations of the HugeNx tools for consistent monorepo.

Let’s Generate Your Workspace

Let’s start with a concrete example by creating a new TypeScript file that will represent your workspace.

1. Define your conventions

You can create a file huge-angular-full-stack.conventions.ts that will contain a workspace with a full-stack application to manage a Hotel:



export default {
  version: '1.0',
  generators: {
    '@nx/angular:application': { //<-- Generator Identifier
      linter: 'eslint', //<-- List of options
      style: 'css',
      unitTestRunner: 'jest',
      bundler: 'esbuild',
      e2eTestRunner: 'playwright',
      inlineStyle: true,
      inlineTemplate: true,
    },
    '@nx/angular:library': {
      linter: 'eslint',
      unitTestRunner: 'jest',
    },
    '@nx/angular:component': {
      style: 'css',
    },
    '@nx/js:lib': {
      bundler: 'swc',
    },
  },
  projectTypes: {
    'global:angular:app': { //<-- ProjectType Identifier
      projectPattern: '*-app', //<-- Pattern matching your naming convention
      generators: [{ generator: '@nx/angular:application' }], //<-- List of generators used to generate that type of project
    },
    'backend:api': {
      projectPattern: '*-api',
      generators: [{ generator: '@nx/nest:application' }],
    },
    'global:angular:lib:data-access': {
      projectPattern: '*-data-access',
      generators: [{ generator: '@nx/angular:library' }],
    },
    'global:angular:lib:feature': {
      projectPattern: '*-feature',
      generators: [{ generator: '@nx/angular:library' }],
    },
    'global:angular:lib:ui:storybook': { //<-- This ProjectType generates a library then a storybook configuration
      projectPattern: '*-ui',
      generators: [{ generator: '@nx/angular:library' }, { generator: '@nx/storybook:configuration', options: { uiFramework: '@storybook/angular' } }],
    },
    'global:ts:lib:utils': {
      projectPattern: '*-utils',
      generators: [{ generator: '@nx/js:lib', options: { bundler: 'swc' } }],
    },
  },
  workspace: { //<-- The workspace is structured by folders and projects
    apps: {
      //<-- Generates a folder apps
      'hotel-app': 'global:angular:app', //<-- Generates a project hotel-app by using the project type global:angular:app
      'hotel-api': { //<-- Generates a project hotel-api by using the project type backend:api and extra options
        projectType: 'backend:api',
        options: {
          '@nx/angular:remote': { frontendProject: 'hotel-app' },
        },
      },
    },
    libs: { //<-- Generates a folder libs
      guest: { //<-- Generates a folder guest
        'data-access': 'global:angular:lib:data-access', //<-- Generates a project guest-data-access by using the project type global:angular:lib:data-access
        'booking-feature': 'global:angular:lib:feature', //<-- Generates a project guest-booking-feature by using the project type global:angular:lib:feature
        'feedback-feature': 'global:angular:lib:feature', //<-- Generates a project guest-feedback-feature by using the project type global:angular:lib:feature
      },
      room: { //<-- Generates a folder room
        'data-access': 'global:angular:lib:data-access',
        'list-feature': 'global:angular:lib:feature',
        'request-feature': 'global:angular:lib:feature',
      },
      shared: { //<-- Generates a folder shared
        ui: { //<-- Generates a project shared-ui by using the project type global:angular:lib:ui:storybook and extra options
          projectType: 'global:angular:lib:ui:storybook',
          options: {
            '@nx/storybook:configuration': { project: 'shared-ui' },
          },
        },
        utils: 'global:ts:lib:utils',
      },
    },
  }
};

The Default Generator Options
This is nothing new and is already available in Nx by configuring your nx.json file. You can define default options for each generator that you are using in your workspace.

All Nx options can be found in the Nx API Documentation.

The List of ProjectTypes
Here you’ll define your list of ProjectType based on the technologies, the domain, the type of library, the team, etc.

For each ProjectType, you’ll specify which generators should be used and all conventions around them. It will use the Default Generator Options, and you can add extra options if needed.

Your Workspace Structure

Finally, you’ll define your list of projects inside a workspace layout. Each project will be linked and described by a specific ProjectType.

That section is required for the generation but not required for the maintenance.

2. Use create-huge-nx CLI

If you want to generate your workspace, you can now use the HugeNx CLI by calling:



npx create-huge-nx@latest my-workspace --hugeNxConventions=./huge-angular-full-stack.conventions.ts --nxCloud skip

It will generate a workspace that will look like:



my-workspace/
├─ apps/
│   ├─ hotel-api/
│   ├─ hotel-api-e2e/
│   ├─ hotel-app/
│   └─ hotal-app-e2e/
├── libs/
│   ├─ guest/
│   │   ├─ data-access
│   │   ├─ booking-feature
│   │   └─ feedback-feature
│   ├─ room/
│   │   ├─ data-access
│   │   ├─ list-feature
│   │   └─ request-feature
│   └─ shared/
│       ├─ ui
│       └─ utils
├─ nx.json
├─ package.json
├─ jest.config.json
└─ huge-nx.conventions.ts

By default, the latest version of Nx will be used but you can generate a workspace with a specific Nx version with --nxVersion:



npx create-huge-nx@latest my-workspace --nxVersion 17 --hugeNxConventions=./huge-angular-full-stack.conventions.ts --nxCloud skip

More presets

It’s now straightforward to create various types of repositories simply by introducing a new huge-nx.conventions.ts file. This approach not only encompasses all Nx presets but also allows you to describe each type of project in detail, as outlined in the library types section of the Nx documentation.

For instance, you can define the types from the @angular-architects/ddd package and then use this definition to generate a workspace. This flexibility allows for a highly customized setup that caters to the specific needs of your project, leveraging Nx's powerful and extensible tooling ecosystem.

I also used ChatGPT to generate my convention files. I just provided an example of the file and specify:

It represents an Nx workspace
Should use Angular generators
Represent Hotel Business
Should be a full-stack app

Final Thoughts

HugeNx’s Conventions aim to provide a useful tool in the Nx landscape, particularly for those managing large and evolving monorepos.

By automating and standardizing workspace setups, it helps reduce the complexity often associated with project generation and maintenance. For me, this approach helped me save time and effort in my migration process.

I am looking forward to improving HugeNx based on your feedback. I hope it will be a valuable addition to your development toolkit. Your insights and experiences are crucial to refining this tool, so please share your thoughts.

Stay tuned! 🚀

jogelin / huge-nx

Huge

HugeNx is a toolkit designed to dynamically generate and manage Nx workspaces by adhering to established workspace conventions.

Getting Started

1. Define your HugeNx's conventions:

For example let's create a conventions file angular-monorepo.conventions.ts that match the default Nx angular-monorepo preset:

export default {
  version: '1.0',
  generators: {
    '@nx/angular:application': {
      bundler: 'esbuild',
    },
    '@nx/angular:library': {
      linter: 'eslint',
      unitTestRunner: 'jest',
    },
  },
  projectTypes: {
    'global:angular:application': {
      projectPattern: '*-app',
      generators: [{ generator: '@nx/angular:application' }],
    },
    'global:angular:lib:feature': {
      projectPattern: '*-feature',
      generators: [{ generator: '@nx/angular:library' }],
    },
  },
  workspace: {
    apps: {
      'my-app': 'global:angular:application',
    },
    libs: {
      'my-feature': 'global:angular:lib:feature',
    },
  },
};

2. Use create-huge-nx client to generate

…

View on GitHub

Looking for some help? 🤝
**Connect with me on Twitter • LinkedIn • Github

🍒 Cherry-Picked Nx v18.3 Updates

jogelin — Sun, 21 Apr 2024 06:36:10 +0000

Release Note 18.3 (2024–04–16)

https://github.com/nrwl/nx/releases/tag/18.3.0

[Core] Metadata Property in Project Configuration

This new metadata property was introduced in Nx 18.2. Initially, it was specified only at the project level. For example, for a project using Cypress, the technologies and the targetGroups were defined.

The targetGroups is used for sharding tests.

In Nx v18.3, you can specify themetadata property at either a project level or a target level. It is also more generic; any property name can be specified within it:

{
  "name": "my-app-e2e",
  "metadata": {
    "targetGroups": {
      "E2E (CI)": ["e2e-ci--src/e2e/app.cy.ts", "e2e-ci"]
    }
  },
  "targets": {
    "e2e": {
      ...
      "metadata": {
        "technologies": ["cypress"],
        "description": "Runs Cypress Tests"
      }
    },
    "e2e-ci--src/e2e/app.cy.ts": {
      ...
      "metadata": {
        "technologies": ["cypress"],
        "description": "Runs Cypress Tests in src/e2e/app.cy.ts in CI"
      }
    },
    "e2e-ci": {
      ...
      "metadata": {
        "technologies": ["cypress"],
        "description": "Runs Cypress Tests in CI"
      }
    }
  }
}

For the moment it is used for Cypress, Playwright, and Jest.

If you want to add extra information to your projects, such as Java technologies or others, I guess this is the correct place!

[Core] List Crystal Plugin in Nx Report

For debugging purposes, you can now see the list of registered plugins in the nx report result:

[Jest] Ability to Split Jest Tests

Jest can also be used for e2e tests! Just as we do with Cypress or Playwright for splitting and distributing the tests, we can now do the same for Jest.

Please check the documentation about Splitting e2e Tests For Jest

[nx.dev] Various nx.dev Improvements

It’s also important to highlight that the Nx team is continually improving its website.

Remember selected tabs

One notable feature is the ability to remember selected tabs. When you select a specific tab on a page, all other tabs on the page with the same name will also be selected. This selection will persist during your next visit to nx.dev.

For example, if you are working with yarn, when you select the yarn tab on the Installation Page, all pages will adapt and display yarn commands by selecting yarn tabs.

New Contact Page

Looking for some help? 🤝
**Connect with me on Twitter • LinkedIn • Github

🍒 Cherry-Picked Nx v18.2 Updates

jogelin — Fri, 05 Apr 2024 07:48:35 +0000

Release Note 18.2 (2024–03–28)

https://github.com/nrwl/nx/releases/tag/18.2.0

[Angular] Support Angular 17.3

As usual, Nx is up to date with the latest version of Angular!

What’s new in Angular 17.3? | Ninja Squad

Angular 17.3 is out!

blog.ninja-squad.com

Meet Angular’s new output() API. Angular v17.3 introduces the improved… | by Paul Gschwendtner | Mar, 2024 | Angular Blog

Angular v17.3 introduces the improved API for declaring outputs as a developer preview.

blog.angular.io

[Core] Scope Nx Plugin Project Crystal 💛💛💛

feat(core): add ability to scope plugins #22379

FrozenPandaz posted on Mar 18, 2024

Current Behavior

There is no way to users to filter where plugins are applied. Only by the plugin author.

This means that errors thrown make the plugin unusable and more modifications to the project graph are made than desired.

Expected Behavior

Plugins can be scoped via include and exclude which are both lists of file patterns.

{
  plugins: [
    {
      plugin: '@nx/jest/plugin',
      include: ['packages/**/*'],
      exclude: ['e2e/**/*']
    }
  ]
}

This will scope running the plugin to processing only those config files.

Related Issue(s)

Fixes #

View on GitHub

In my previous article, “⛔ Target Exclusions in Nx Project Crystal,” I introduced alternatives for excluding certain projects from specific plugins.

For instance, you might not want a test target in an e2e project simply because there’s a jest.config.ts file present.

Now, an official method is available for excluding or including plugins for a specific project. Within your nx.json file, you can now specify the exclude or include options:

{
  "plugins": [
    {
      "plugin": "@nx/jest/plugin",
      "options": {
        "targetName": "test",
        "exclude": ["my-lib-e2e/**/*"]
      }
    }
  ]
}

[Gradle] New Gradle Integration

@nx/gradle | Nx

The Nx Plugin for Gradle allows Gradle tasks to be run through Nx

nx.dev

You can now leverage the new Gradle integration with the @nx/gradle:init generator. To initialize, simply run:

nx g @nx/gradle:init

This initialization will also add the @nx/gradle/plugin to your nx.json:

{
  "plugins": [
    {
      "plugin": "@nx/gradle/plugin",
      "options": {
        "testTargetName": "build",
        "classesTargetName": "test",
        "buildTargetName": "classes"
      }
    }
  ]
}

This plugin will:

Integrate your Gradle projects into the Nx Dependency Tree by scanning all Gradle configurations.
Discover your projects by scanning the Gradle configuration matching the pattern **/build.{gradle.kts,gradle}, and then assign the targets build, test, and classes.

[Cypress] New target `open-cypress` is added by the @nx/cypress/plugin

feat(testing): infer open-cypress task #22556

leosvelperez posted on Mar 28, 2024

Infer a new task named open-cypress, which runs the command cypress open from the project root.

Current Behavior

Expected Behavior

Related Issue(s)

Fixes #22389

View on GitHub

If you’re working with Nx Project Crystal and have a Cypress project that includes a cypress.config.* file, the @nx/cypress/plugin will automatically add related targets to your project.

A new target, open-cypress, will now be added to your project configuration:

"open-cypress": {
  "command": "cypress open",
  "options": {
    "cwd": ".",
  },

You have the flexibility to use a different name by specifying the new plugin option openTargetName:

{
  "plugins": [
    {
      "plugin": "@nx/cypress/plugin",
      "options": {
        "targetName": "e2e",
        "ciTargetName": "e2e-ci",
        "componentTestingTargetName": "component-test",
        "openTargetName": "open-cypress" // <-- NEW
      }
    }
  ]
}

Looking for some help? 🤝
**Connect with me on Twitter • LinkedIn • Github

🩹 Nx Crystal Plugin Picking the Essentials

jogelin — Sat, 23 Mar 2024 11:26:27 +0000

As specified in my article, ⛔ Target Exclusions in Nx Project Crystal, there are use cases that necessitate extending the Nx Project Crystal. However, it is not possible to hook only a specific part of the plugin. You either take it all or you don’t use it at all. Only the createNode function is exposed, but that function does more than one thing.

I started a discussion on GitHub concerning that subject: Design Nx Plugin Project Crystal

But there is a solution, don’t forget that nothing is impossible in JavaScript! If you want to access a library’s internal function, just patch it 😅

My Use Case

I pursued this solution because I appreciate the Nx Project Configuration inference and, especially, the no-configuration idea. Yeah yeah, Nx will probably implement that, but I cannot wait 😬.

However, with the current plugins, it is not possible because they enforce that only projects containing a project.json will be taken into account. For example, I would like to keep the benefit of dynamic test target assignment from the @nx/jest/plugin but without the filter on the project.json.

You can check the section Create Your Cyrstal Plugin of my article 💎 Discovering Nx Project Crystal’s Magic if you want to know what I am talking about 🙃

So, if I want to use the @nx/jest/plugin for the generation of the test target, I’ll need to expose the internal function buildJestTargets. To do so, I'll need to patch the @nx/jest/plugin library 😈

Patch Nx Plugins

Be careful, the following content may offend your sensibility 🙃

Patching your packages is supported by default for yarn and pnpm. But if you are using other package managers, you can always use the library patch-package.

In my case, I am using pnpm, so I first ran:

pnpm patch @nx/jest

You can now edit the following folder: /private/var/folders/6c/qvy5njbd5z92xgwvcnmpmgcm0000gn/T/9504b5672db3b12b750d6825857fbbb4

Once you're done with your changes, run "pnpm patch-commit '/private/var/folders/6c/qvy5njbd5z92xgwvcnmpmgcm0000gn/T/9504b5672db3b12b750d6825857fbbb4'"

pnpm will copy the library into a temporary folder and tell you what step you should follow next.

So, I can edit the plugin located at /private/.....57f/src/plugins/plugin.js and add an export in front of the internal function buildJestTargets:

export async function buildJestTargets(...

I should also inform TypeScript of the exposition by adding the declaration to the file /private/.....57f/src/plugins/plugin.d.ts:

export declare async function buildJestTargets(
    configFilePath: string,
    projectRoot: string,
    options: JestPluginOptions,
    context: CreateNodesContext
): Promise<Record<string, TargetConfiguration>>;

Then I run the patch command to apply my modification to my repository:

pnpm patch-commit '/private/var/folders/6c/qvy5njbd5z92xgwvcnmpmgcm0000gn/T/9504b5672db3b12b750d6825857fbbb4'

Then I see that pnpm updated my package.json to override the library with:

{
  "pnpm": {
    "patchedDependencies": {
      "@nx/jest@18.0.6": "patches/@nx__jest@18.0.6.patch"
    }
  }
}

and I can see that I have a new patch file patches/@nx__jest@18.0.6.patch:

diff --git a/src/plugins/plugin.d.ts b/src/plugins/plugin.d.ts
index 1976aa9371ddcc675643d8d13c38c5fdc73e9356..4416e2279b73e4623284fb6a0ec2d275a9bb131c 100644
--- a/src/plugins/plugin.d.ts
+++ b/src/plugins/plugin.d.ts
@@ -4,3 +4,9 @@ export interface JestPluginOptions {
 }
 export declare const createDependencies: CreateDependencies;
 export declare const createNodes: CreateNodes<JestPluginOptions>;
+export declare async function buildJestTargets(
+    configFilePath: string,
+    projectRoot: string,
+    options: JestPluginOptions,
+    context: CreateNodesContext
+): Promise<Record<string, TargetConfiguration>>;
\ No newline at end of file
diff --git a/src/plugins/plugin.js b/src/plugins/plugin.js
index 5e4162dc41c30b8b1649cd3e3d4661d1b7dccc6c..3de56fef3129d97c85a383e770f0031a68134121 100644
--- a/src/plugins/plugin.js
+++ b/src/plugins/plugin.js
@@ -60,7 +60,7 @@ exports.createNodes = [
         };
     },
 ];
-async function buildJestTargets(configFilePath, projectRoot, options, context) {
+export async function buildJestTargets(configFilePath, projectRoot, options, context) {
     const config = await (0, jest_config_1.readConfig)({
         _: [],
         $0: undefined,

That means each time I run pnpm install, the patch will be applied along with the modification. Now, let's delve into crafting your custom plugin.

Craft Your Custom Plugin Now

You’re now set to develop your custom Jest plugin without the filter. Here’s a prototype plugin, tools/nx-plugins/my-jest-plugin.ts:

import { CreateNodes } from '@nx/devkit';
import { dirname } from 'node:path';
import { createNodes as createJestNodes, JestPluginOptions } from '@nx/jest/plugin';

// IT IS AVAILABLE YEAAAH
import { buildJestTargets } from '@nx/jest/src/plugins/plugin';

export const createNodes: CreateNodes<JestPluginOptions> = [
  createJestNodes[0],
  async (configFilePath, options, context) => {
    const projectRoot = dirname(configFilePath);

    // SAME PLUGIN BUT WITHOUT THE PROJECT.JSON CONDITION

    return {
      projects: {
        [projectRoot]: {
          root: projectRoot,
          targets: await buildJestTargets(configFilePath, projectRoot, options, context),
        },
      },
    };
  },
];

And then, in the nx.json, it should replace @nx/jest/plugin with:

{
  "plugins": [
    // HERE, REPLACE "@nx/jest/plugin" WITH YOUR CUSTOM PLUGIN
    {
      "plugin": "./tools/nx-plugins/my-jest-plugin.ts",
      "options": {
        "targetName": "test"
      }
    }
  ]
}

⚠️ Cautions

This is a temporary tip. Nx Crystal is still a baby, a powerful baby! Keep an eye on Nx updates to ensure this approach is still valid!
Do you need it? You are exposed to breaking change!
The patch is strictly linked to the version. If you update Nx, you’ll have to validate the patch.
In my example, I remove the memoization of the plugin; I recommend implementing one each time you are implementing a custom plugin.
“But this is stupid; you can directly remove the filter on the existing plugin by using the same approach!”. This is an example; I am doing other stuff too. 😉

In Conclusion

Got more ideas? Feel free to share, and I’ll eagerly incorporate them. Let’s keep the conversation going and make Nx Project Crystal even more versatile.

🚀 Stay Tuned!

Looking for some help?🤝

Connect with me on Twitter • LinkedIn • Github

⛔ Target Exclusions in Nx Project Crystal

jogelin ・ Mar 21

#nx #typescript #angular #react

📤 Local Library Development with Nx Release and Verdaccio

jogelin — Thu, 21 Mar 2024 08:12:48 +0000

Nx offers everything you need to develop and publish your NPM packages efficiently. It provides a structured environment and essential tooling, including Verdaccio for local publishing and the innovative Nx Release system.

In my previous article, 🍒 Cherry-Picked Nx v18.1 Updates, I highlighted how the custom publish.mjs will now be replaced by the Nx Release for managing publishable libraries.

Nx Release is mainly achieving three main phases:

For those unfamiliar with Nx Release, I recommend:

Reading Juri Strumpflohner’s article: Versioning and Releasing Packages in a Monorepo.
Check Nx Documentation: Feature, Recipe and Api

In that short article, I wanted to share insights on utilizing the new system alongside Verdaccio for the local development of publishable libraries.

Practical Use Case

To begin, create an empty Nx Workspace with the following command:

npx create-nx-workspace@latest myorg --preset empty --workspaceType integrated --nxCloud skip && cd myorg

Next, add the @nx/js plugin feature:

nx add @nx/js

Finally, create the publishable library you wish to develop:

nx g @nx/js:lib my-lib --publishable --importPath=@myorg/my-lib

What happened?

Upon generating the publishable library, Nx installs and configures all necessary tooling for your workspace, preparing it for publication.

Verdaccio Setup

Nx automatically configures Verdaccio on your workspace using @nx/js:setup-verdaccio, resulting in a root project.json with the following configuration:

{
  "name": "@my-org/source",
  "$schema": "node_modules/nx/schemas/project-schema.json",
  "targets": {
    "local-registry": {
      "executor": "@nx/js:verdaccio",
      "options": {
        "port": 4873,
        "config": ".verdaccio/config.yml",
        "storage": "tmp/local-registry/storage"
      }
    }
  }
}

This configuration enables the local Verdaccio registry to run on port 4873, using the specified storage and configuration paths. You can start Verdaccio using:

nx run local-registry

Nx Global Configuration

Nx also sets up the Nx Release globally in your nx.json:

{
  "release": {
    "version": {
      "preVersionCommand": "npx nx run-many -t build"
    }
  }
}

The preVersionCommand ensures that builds or other tasks are completed before version updating.

Project Configuration

Finally, your library project configuration will include Nx Release-specific settings and a target nx-release-publish for running the release:

{
  "name": "my-lib",
  "targets": {
    "build": {...},
    "nx-release-publish": {
      "options": {
        "packageRoot": "dist/{projectRoot}"
      }
    }
  },
  "release": {
    "version": {
      "generatorOptions": {
        "packageRoot": "dist/{projectRoot}",
        "currentVersionResolver": "git-tag"
      }
    }
  }
}

You can now seamlessly publish your library using:

nx release

Local Development Flow

If you want to test your library locally, on another local repository, for example, you will have to follow the steps:

Start Verdaccio: nx run local-registry
Build your Libraries: Automated by Nx Release using the preVersionCommand in nx.json.
Update Versions in Outputs: Automated by Nx Release with the generator @nx/js:release-version.
Publish Library on Verdaccio: Automated by Nx Release using @nx/js:release-publish and the generated target nx-release-publish.
Install your Libraries: npm install @my-org/my-lib@latest

Working locally can become repetitive and tedious, especially when needing to create a unique version each time; otherwise, Nx Release will refuse to publish the same version again. Additionally, I prefer not to complicate my workflow by including an unpublish step.

In the Nx documentation, two particularly interesting examples are highlighted: Using the programmatic API for Nx release and Update Your Local Registry. These examples demonstrate how you can craft a custom script to enhance the standard Nx Release process.

To cover the entire process mentioned above, I implemented a custom script tools/scripts/publish-local.ts:

// Related to the target generated in the root project.json
const localRegistryTarget = '@myorg/source:local-registry';

// Callback used to stop Verdaccio process
let stopLocalRegistry = () => {};

(async () => {
  // Get Options From Execution
  const options = await yargs
    .version(false) // don't use the default meaning of version in yargs
    .option('version', {
      description:
        'Explicit version specifier to use, if overriding conventional commits',
      type: 'string',
      default: `0.0.0-local.${Date.now()}`, // the version will be always unique
    })
    .option('targetPath', {
      description:
        'Relative path to the repo where to install the published libraries',
      type: 'string',
      default: '',
    })
    .parseAsync();

  /**
   * Step 1: Start Verdaccio
   */
  stopLocalRegistry = await startLocalRegistry({
    localRegistryTarget,
    verbose: false,
  });

  /**
   * Step 2: Build your Libraries
   * Step 3: Update Versions in Outputs
   */
  const { projectsVersionData } = await releaseVersion({
    specifier: options.version,
    stageChanges: false,
    gitCommit: false,
    gitTag: false,
    firstRelease: true,
    generatorOptionsOverrides: {
      skipLockFileUpdate: true,
    },
  });

  /**
   * Step 4: Publish Library on Verdaccio
   */
  const publishStatus = await releasePublish({
    firstRelease: true,
  });

  /**
   * Step 5: Install your Libraries
   */
  // Get All published Npm packages that should be installed
  const packagesToInstall = Object.entries(projectsVersionData).map(
    ([projectName, { newVersion }]) => {
      const project = readCachedProjectGraph().nodes[projectName];

      const packageJson = JSON.parse(
        readFileSync(
          resolve(process.cwd(), project.data.root, `package.json`)
        ).toString()
      );

      return `${packageJson.name}@${newVersion}`;
    }
  );

  // Prepare the install command
  const targetPath = resolve(process.cwd(), options.targetPath);
  const installCommand = `${getInstallCommand(
    targetPath
  )} ${packagesToInstall.join(' ')} --registry=http://localhost:4873`;

  console.log(installCommand);

  // Locate to target dir and run the install command
  process.chdir(targetPath);
  execSync(installCommand);

  /**
   * Final: When installation is done, no need to have Verdaccio
   */
  stopLocalRegistry();

  process.exit(publishStatus);
})().catch((e) => {
  // If anything goes wrong, stop Verdaccio
  console.error(e);
  stopLocalRegistry();
  process.exit(1);
});

// Used to define which install command should be used on the targetPath
function getInstallCommand(targetPath: string): string {
  const siblingFiles = readdirSync(targetPath);

  if (siblingFiles.includes('yarn.lock')) {
    return 'yarn add';
  }
  if (siblingFiles.includes('package-lock.json')) {
    return 'npm install';
  }
  if (siblingFiles.includes('pnpm-lock.yaml')) {
    return 'pnpm add';
  }
  throw new Error(
    `No package manager found for target repository: ${targetPath}`
  );
}

You can now publish your packages locally just by running:

npx ts-node ./tools/scripts/publish-local.ts --targetPath ../app-using-my-lib

Final Thoughts

It is always difficult when you want to test a publishable library locally. Nx provides all the tooling you need to support you in that process.

However, it is up to everyone to decide whether you want to use that tooling manually or simply automate it by using a custom script.

In this article, I propose one way, but I highly recommend adapting it to create your own way.

🚀 Stay Tuned!

Looking for some help?🤝

Connect with me on Twitter • LinkedIn • Github

🍒 Cherry-Picked Nx v18.1 Updates

jogelin — Thu, 21 Mar 2024 08:09:40 +0000

[Core] Activate/Deactivate Project Crystal

Until now you could use the environment variable NX_ADD_PLUGINS to activate or deactivate the inferred targets. A new property useInferencePlugins: false was added to the nx.json to do the same:

NxJsonConfiguration | Nx

Nx is a build system with built-in tooling and advanced CI capabilities. It helps you maintain and scale monorepos, both locally and on CI.

nx.dev

[Angular] Support Angular 17.2

Angular v17.2 is now available. We rarely write blog posts about minor… | by Minko Gechev | Feb, 2024 | Angular Blog

We rarely write blog posts about minor releases, but today we have a few surprises for you — experimental support for Material 3, signal…

blog.angular.io

[Angular] New “extract-i18n” Executor

@nx/angular:extract-i18n | Nx

Extracts i18n messages from source code.

nx.dev

[Remix] Add Remix Presets in “`create-nx-workspace"`

[Remix] Plugin Remix uses CLI directly

create-nx-workspace - CLI command | Nx

Create a new Nx workspace

nx.dev

[Gradle] New Gradle Plugin

It is not documented yet but there is a new plugin for supporting Gradle:

feat(core): add gradle plugin #21055

xiongemi posted on Jan 09, 2024

Current Behavior

Expected Behavior

Related Issue(s)

Fixes #

View on GitHub

[Rollup] Crystalize Rollup

It will look for look for rollup.config.{js,mjs,cjs} files and add a build target automatically:

feat(bundling): crystalize rollup #22045

Coly010 posted on Feb 28, 2024

Current Behavior

Rollup does not have a Crystal Plugin

Expected Behavior

Rollup has a Crystal Plugin:

It will look for rollup.config.{js,mjs,cjs} files.
It will add a build target
It will use `rollup -c {rollupConfigFileName}
It will read the config file using rollup's loadConfigFile util
It will parse the output of the config to determine the outputs that will be created and use them for Nx caching

Tested on: https://github.com/freeCodeCamp/freeCodeCamp/tree/main/tools/ui-components

Related Issue(s)

Fixes #

View on GitHub

[Release] Use Nx release instead of custom publish script

Versioning and Releasing Packages in a Monorepo | by Juri Strumpflohner | Feb, 2024 | Nx Devtools

When it comes to publishing NPM packages, there are a bunch of libraries and utilities out there that help with the process. Many of them…

blog.nrwl.io

[CI] Group CI Logs with NX_SKIP_LOG_GROUPING

Environment Variables | Nx

Nx is a build system with built-in tooling and advanced CI capabilities. It helps you maintain and scale monorepos, both locally and on CI.

nx.dev

Looking for some help? 🤝
**Connect with me on Twitter • LinkedIn • Github

⛔ Target Exclusions in Nx Project Crystal

jogelin — Thu, 21 Mar 2024 08:02:05 +0000

UPDATE 2024–04-03:

An official way now exists to exclude or include plugins for a specific project:

feat(core): add ability to scope plugins #22379

FrozenPandaz posted on Mar 18, 2024

Current Behavior

There is no way to users to filter where plugins are applied. Only by the plugin author.

This means that errors thrown make the plugin unusable and more modifications to the project graph are made than desired.

Expected Behavior

Plugins can be scoped via include and exclude which are both lists of file patterns.

{
  plugins: [
    {
      plugin: '@nx/jest/plugin',
      include: ['packages/**/*'],
      exclude: ['e2e/**/*']
    }
  ]
}

This will scope running the plugin to processing only those config files.

Related Issue(s)

Fixes #

View on GitHub

If we take the example below, you can now use the approach:

{
  "plugins": [
    {
      "plugin": "@nx/jest/plugin",
      "options": {
        "targetName": "test",
        "exclude": ["my-lib-e2e/**/*"]
      }
    }
  ]
}

Since the release of Nx 18, many repositories have started the adoption of Nx Project Crystal. As it’s still the beginning, the feature to exclude some projects from the dynamic target assignment is not supported yet.

In this article, I want to share workarounds and ideas until the Nx team implements something internally.

If you’re looking to understand how Nx assigns targets to projects dynamically, I first recommend reading my article:

💎 Discovering Nx Project Crystal’s Magic

jogelin ・ Feb 26

#nx #react #angular #typescript

Workarounds

Let’s specify the context by mentioning that you have a project named my-lib-e2e and you don't want that project to have a test target even if it contains a jest.config.ts. However, you still want to get the benefit of the @nx/jest/plugin for your other 1000 Nx projects 😋.

Manually Override the “test” Target with `nx:noop`

In your my-lib-e2e/project.json:

{
  "name": "my-lib-e2e",
  "targets": {
    "test": {}
  }
}

Given that project.json takes precedence over all plugins, the inferred test target from the @nx/jest/plugin will be overridden.

Dynamically Override Any Target with `nx:noop`

You can also develop a plugin to automatically assign nx:noop on any target. For instance, I crafted a plugin located at tools/nx-plugins/targets-noopify.ts:

import { CreateNodes, ProjectConfiguration, readJsonFile } from '@nx/devkit';
import { dirname, join } from 'node:path';

interface TargetsNoopifyOptions {
  projectName: string;
  targets: string[];
}

export const createNodes: CreateNodes<TargetsNoopifyOptions> = [
  '**/project.json',
  async (configFilePath, options, { workspaceRoot }) => {
    const projectRoot = dirname(configFilePath);

    // get project name from porject.json
    const projectJson = readJsonFile<ProjectConfiguration>(
      join(workspaceRoot, configFilePath)
    );
    const projectName = projectJson.name;

    // check if the target of the project should be noopified
    const targetsToStub = options[projectName];
    if (!targetsToStub) {
      return {};
    }

    // override the targets
    const targets = targetsToStub.reduce(
      (acc, targetName) => ({
        ...acc,
        [targetName]: {},
      }),
      {}
    );

    return {
      projects: {
        [projectRoot]: {
          root: projectRoot,
          targets: targets,
        },
      },
    };
  },
];

This plugin should then be listed last in nx.json:

{
  "plugins": [
    {
      "plugin": "@nx/jest/plugin",
      "options": {
        "targetName": "test"
      }
    },
    // MAKE SURE THIS COMES AFTER THE PLUGIN YOU WISH TO OVERRIDE
    {
      "plugin": "./tools/nx-plugins/targets-noopify.ts",
      "options": {
        "my-lib-e2e": ["test"]
      }
    }
  ]
}

Create Your Custom `@nx/jest/plugin` and Skip the Projects

Alternatively, you could implement your custom Jest plugin that filters projects. Here’s an example plugin tools/nx-plugins/skip-jest-plugin.ts:

import {
  CreateNodes,
  joinPathFragments,
  ProjectConfiguration,
  readJsonFile,
} from '@nx/devkit';
import { dirname, join } from 'node:path';
import {
  JestPluginOptions,
  createNodes as createJestNodes,
} from '@nx/jest/plugin';
import { readdirSync } from 'fs';

export const createNodes: CreateNodes<
  JestPluginOptions & { skipProjects: string[] }
> = [
  createJestNodes[0],
  async (configFilePath, options, context) => {
    const projectRoot = dirname(configFilePath);

    const siblingFiles = readdirSync(join(context.workspaceRoot, projectRoot));
    if (!siblingFiles.includes('project.json')) {
      return {};
    }

    const path = joinPathFragments(projectRoot, 'project.json');
    const projectJson = readJsonFile<ProjectConfiguration>(path);
    const projectName = projectJson.name;

    if (options.skipProjects.includes(projectName)) {
      return {};
    }

    return createJestNodes[1](configFilePath, options, context);
  },
];

And then, in the nx.json, it should replace @nx/jest/plugin with:

{
  "plugins": [
    // HERE, REPLACE "@nx/jest/plugin" WITH YOUR CUSTOM PLUGIN
    {
      "plugin": "./tools/nx-plugins/skip-jest-plugin.ts",
      "options": {
        "targetName": "test",
        "skipProjects": ["my-lib-e2e"]
      }
    }
  ]
}

Ideas

As Max Kless commented, they are open to ideas, so I jumped into it 🙂

// Detect dark theme var iframe = document.getElementById('tweet-1768391696235073759-907'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1768391696235073759&theme=dark" }

Skip projects per plugin

This is related to the last workaround described above but integrated into Project Crystal. For example, you would have an nx.json like:

{
  "plugins": [
    {
      "plugin": "@nx/jest/plugin",
      "options": {
        "targetName": "test",
        "skipProjects": ["my-lib-e2e"] // Could be a pattern instead
      }
    }
  ]
}

✅ Specific per plugin

⛔ Duplication in each plugin

⛔ If the plugin adds multiple targets, it is not possible to filter only one

Add “projects” property on targetDefaults

This strategy takes a leaf from the Nx Release workflow, applies it to targetDefaults for more granular control:

{
  "$schema": "./node_modules/nx/schemas/nx-schema.json",
  "targetDefaults": {
    "test": {
      "cache": true,
      "inputs": ["production", "^production"],
      "projects": ["*", "!my-lib-e2e"]
    },
  }
}

✅ Specific per target

✅ Centralized

✅ Re-use existing from Release

⛔ Cannot be specified by executor because the uses Nx Command

⛔ It does not reflect what you can specify in your Project Configuration

In Conclusion

Got more ideas? Feel free to share, and I’ll eagerly incorporate them. Let’s keep the conversation going and make Nx Project Crystal even more versatile.
🚀 Stay Tuned!

Looking for some help?🤝

Connect with me on Twitter • LinkedIn • Github

🩹 Nx Crystal Plugin Picking the Essentials

jogelin ・ Mar 23

#nx #monorepo #angular #react

⏰ It’s time to talk about Import Map, Micro Frontend, and Nx Monorepo

jogelin — Mon, 11 Mar 2024 08:03:40 +0000

In this article, I am sharing about an architecture that has profoundly changed my perception of software development for large enterprises with complex infrastructure and team organization.

I’ve been eager to write this article for a long time, and now’s the time! I’ve always valued sticking to standards, and I believe the ecosystem is now ready to properly handle this architecture with the latest tools.

The advent of esbuild, the native support for ES Modules in browsers, the widespread adoption of import map, the emergence of tools like Native Federation, and the Nx ecosystem all combine to forge a flexible and well-maintained Micro Frontend Architecture.

I’ll cover:

Real Story!

Just to give you more context, I led the migration of several AngularJS applications to the newer Angular Framework. My client finally decided to make that move following the AngularJS deprecation announcement (stay up to date please 🙏)️.

Using the usual migration process was not possible. After investigating multiple scenarios, the micro frontend architecture was chosen. As we see, it facilitates incremental migration, provides isolation, and allows the integration of apps from multiple teams into one unified platform.

At that time, the micro frontend architecture was not yet popular and only the single-spa library was mature enough. It supports many frameworks, including AngularJS and Angular, making it a perfect choice for us!

Single-spa orchestrates the micro frontend by toggling between AngularJS or Angular implementations based on a feature flag:

Using single-spa has significantly enhanced my understanding of implementing micro frontend architecture, particularly highlighting the substantial benefits of utilizing import maps and micro frontend overrides. These tools have greatly improved my experience in local development, testing, and deployment.

I highly recommend having a look at the single-spa documentation to understand the concepts of micro frontend and import map.

A short reminder about browsers

To grasp the following subjects, I believe it’s crucial first to recall the basics of the web, focusing on the primary flow of a browser running a web application:

The first action is always to get an index.html file, which has everything needed to start the application.
Then, the browser loads all the files that the index.html says it should. This often includes the main files for the application, like JavaScript and stylesheets.
After that, the application or the user interaction leads to more requests being made, for example, calling APIs or loading parts of the site as needed.

The browser’s job is simply to load these files or assets and put them together into the web application.

Micro frontend architecture in a nutshell

Let’s start with a short definition: the micro frontend architecture involves breaking down a frontend application into smaller, more manageable pieces — each responsible for a distinct feature or domain of your application. It’s often compared to the microservices concept but at the frontend layer.

Determining the exact point at which an application adheres to micro frontend architecture can be challenging, like defining the ideal size for a microservice.

The key aspect is having a platform capable of plugging in and combining multiple pieces of functionality to produce a unified application. Whether these pieces are lazy-loaded components or micro frontend, the principle remains essentially the same.

In which situation it suits you well?

There are many use cases where the micro frontend architecture can be useful:

Multiple Frameworks: The most common use case involves integrating various technologies into a single product, particularly useful for unifying disparate systems.
Team Decentralization: When teams operate independently, within a monorepo or different repositories, micro frontends make it easier to merge their work into one cohesive product.
Separation of Concerns: Ideal for structuring your application into isolated domains and features for better organization.
Complex Infrastructure: The ability to plug a micro frontend into an existing environment can significantly enhance the development experience! We’ll delve into this reason further later on.

Don’t use micro frontend architecture if you don’t need it

Major Concepts

In a micro-frontend architecture, we distinguish various types of entities, each adhering to a distinct concept:

The Micro Frontend (or micro app) is loaded by the Host upon navigation or routing. Each micro frontend is responsible for a distinct feature or domain within the application. Like any app, it can contain child routes and multiple components.
The Parcel (also referred to as a component or expose) is loaded independently on-demand. It can be a shared component or a shared service and can be plugged in anywhere.

Tools/Frameworks

There are several implementations of the micro frontend architecture, and I’ll delve into three notable ones here:

Single-spa: This framework keeps things simple and works with many technologies. However, its simplicity might mean you have to do more work if you’re using just one technology.
Webpack Module Federation: Almost everyone uses Webpack, and its module federation feature makes micro frontends easy for these users. But, if you’re using a different tool, you might need to find another solution.
Native Federation: This method combines the ease of Webpack’s approach with newer tools like esbuild or Vite, fitting well with modern development practices while supporting micro frontend architecture.

What is an Import Map?

Let’s begin with the most intriguing aspect. In my opinion, the import map is an underappreciated browser technology. It is compatible with all browsers and plays a role in directly supporting JavaScript modules in the browser.

For full compatibility and extra features, we usually use the library es-module-shims.

How does it work?

The principle is quite straightforward. Since the introduction of the ES module into our JavaScript ecosystem, we’ve all started using syntax like:

import moment from "moment";
import { partition } from "lodash"

However, when using ES modules natively in a browser, you need to specify the full path to the JS file, something like:

import moment from "https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.30.1/moment.min.js";
import { partition } from "https://cdnjs.cloudflare.com/ajax/libs/lodash.js/4.17.21/lodash.min.js";

This approach isn’t very readable or maintainable, is it? Therefore, the import map was created to map a library name to a URL:

<script type="importmap">
{
  "imports": {
    "moment": "https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.30.1/moment.min.js",
    "lodash": "https://cdnjs.cloudflare.com/ajax/libs/lodash.js/4.17.21/lodash.min.js"
  }
}
</script>

It functions similarly to TypeScript’s path mapping but directly in your browser. Now, you can use the same syntax whether loading modules locally or in the browser.

This import map can be specified inline or as an external file, like:

<script type="importmap" src="assets/shared.importmap.json"></script>
<script type="importmap" src="assets/remotes.importmap.json"></script>

For more information, I recommend checking out the MDN Web Docs and the proposal’s GitHub repository.

How is it related to the micro frontend architecture?

As I mentioned, the micro frontend architecture is a just a way for dynamically loading bundles from the browser and integrating them into the actual apps.

This orchestration is the role of the Host. However, when the host needs to load an ES module, it can simply utilize the JS import system and, with the aid of the import map, map the module to its location

Similarly, for Parcels, when you need to load a component on demand, the import map will map your JS import to the current location.

Import Maps are overridable!

You can declare multiple import maps in the same HTML. This means that if two import maps declare the same key, the last one will override the previous one.

By injecting a new import map into your HTML, you can hook/remap any bundle. Thus, you can replace a micro frontend, a component, or even a shared library!

I recommend the library import-map-override which allows you to manage the import map directly in your browser.

Security

Overriding an import map in a web application does not inherently reduce its security, as all frontend assets are public and can be modified client-side. However, for applications that load assets from multiple servers, configuring a Content-Security-Policy (CSP) is crucial.

CSP helps whitelist trusted domains, significantly reducing the risk of Cross-Site Scripting (XSS) and other security threats. This security measure ensures that even if client-side modifications are possible, the application’s integrity and user safety are maintained.

Exploring the Full Potential of Import Maps and Overrides

Now that we understand the principles of the import map and the fact that we can override the bundles loading directly in the browser, let’s see how we can get the advantage of that concept within our development process:

Local Development

Setting up a complex local environment in a large organization often involves:

Spending more than a day to set up your local machine.
Installing a wide range of software, like backend systems, local databases or connections to external environments, local queuing systems, etc.
Adjusting settings for multi-tenants.
Take coffee breaks while you wait for your local environment to bootstrap in the morning, hoping it stays stable throughout the day.

This complexity can be quite frustrating, especially when you only need to make a minor UI adjustment. This is the exact challenge I aimed to tackle through the adoption of micro frontend architecture in combination with the import map overrides.

Instead of running an entire complex ecosystem, you can just plug your local environment into an external environment where all of the complexity is already in place.

To do so, you just need to serve your micro frontend locally and use the import map override principle on the distant environment:

After the reload, the micro frontend loaded by the browser will be not the one on the distant server but the one on your local machine.

One crucial aspect is that you are directly integrating your code into a real environment that contains the latest main branch. This means we can move past the infamous “It Works On My Machine!” scenario.

This approach showcases true Continuous Integration

Pull Request

When you’ve completed your implementation (and tested it 😋), you typically create a pull request to merge your code into the shared codebase.

Facilitate Reviews

You can once again leverage the advantage of import map overriding to make the review process easier, allowing reviewers to validate your changes without needing to deploy or clone the code locally:

At this stage, the CI will build your app and generate new bundles for the modified micro frontend. Additionally, you can generate an affected importmap.json with the updated bundles.

Simplify UI e2e tests

You can also use the affected import map for your UI tests (mocks). In this scenario, the affected importmap.json generated can be injected into tools like Playwright or Cypress to directly test the affected micro frontends.

Acceptance

This step signifies the moment when you need to confirm that your code is ready for production deployment. It can be automated on CI or manually (please automate 🙏).

Typically, this is run several times per day with the most recent codebase in an environment that mirrors production. In this scenario, you’ll generate an importmap.json that includes the latest versions of all bundles:

If the latest importmap.json generated proves successful, it can then become a release candidate for production.

Production

When your release is validated and ready, you can consider deploying it to production. Here, too, having an importmap.json offers significant advantages.

Deploy in a Sec
You can deploy/upload your bundles to production at any time. Until the importmap.json references them, they will not be loaded. Thus, deployment involves merely modifying and uploading the latest import map. This deployment process takes a mere second, requires no freeze, and is completely transparent to the user.

You should have a look to them import-map-deployerlibrary which enable to update animportmap.json directly on the server

Keep Previous Bundles in Cache

It’s also important to note that the importmap.json can still reference bundles with previous versions. In fact, if some micro frontends have not been modified, there’s no need to generate a new version for them.

This means that users won’t have to reload these existing versions because they are probably already cached in their browser. On the other hand, the importmap.json should never be cached!

Canary Deployment & A/B Testing

One last, and not negligible, benefit of the importmap.json is that it can be generated dynamically. This means you can decide whether a micro frontend should load an old version or a new one.

As a result, you can easily conduct A/B testing or canary deployments based on feature flags or authenticated user criteria!

Nx Enables Scalable Micro Frontend Architecture

I won’t delve into all the benefits of Nx, a topic I’ve extensively covered in previous writings. I’ll encourage you to have a look at the Nx website for more detailed information.

My conviction in the value Nx brings to not just JavaScript/TypeScript repositories but to any codebase is unwavering. Its strengths in enhancing sharing, visibility, performance, and adherence to conventions are universally applicable.

Monorepo and Micro Frontend aren’t the opposite?

Not at all! A monorepo adds value through enhanced code maintenance, build, and integration processes. Conversely, micro frontend architecture delivers benefits at runtime.

Both strategies advocate for separation of concerns and reusability, showcasing significant advantages in incorporating micro frontends within a monorepo.

Monorepos | Nx

Nx is a build system with built-in tooling and advanced CI capabilities. It helps you maintain and scale monorepos, both locally and on CI.

nx.dev

Nx still delivers value even if you don’t use a monorepo.

Affected micro frontends

A pivotal concept in Nx is the ability to execute tasks solely on the affected code. This feature significantly simplifies working on a single micro frontend at a time in a remote environment, streamlining local development.

By limiting actions like build, lint, and testing to impacted micro frontends, the efficiency of your CI/CD processes can be markedly improved. Utilizing an affected importmap.json that lists the affected micro frontends can enhance various processes, including testing PRs on existing environments, running e2e tests, and facilitating incremental deployments.

Run Only Tasks Affected by a PR | Nx

Nx is a build system with built-in tooling and advanced CI capabilities. It helps you maintain and scale monorepos, both locally and on CI.

nx.dev

Single Version Policy

While independence and isolation are cornerstone principles of micro frontend architecture, sharing some services and components across all instances is inevitable.

The monorepo approach, coupled with a single version policy, ensures by design that micro frontends remain compatible with one another, fostering a cohesive ecosystem.

Dependency Management | Nx

Nx is a build system with built-in tooling and advanced CI capabilities. It helps you maintain and scale monorepos, both locally and on CI.

nx.dev

What about Native Federation?

Like I said at the beginning, I think now the ecosystem is mature enough to apply the same principles by using Angular, or other frameworks using esbuild, and Native Federation within an Nx monorepo.

I encourage you to have a look at the blog post announcing Native Federation

Unfortunately, I was unable to implement the import map overrides in conjunction with Native Federation. However, this issue is currently under discussion on GitHub:

Use more importmap default behaviours #489

jogelin posted on Mar 04, 2024

Hi there,

As usual, it's a great library 👏. I appreciate the fact that the lesser-known importmaps standard is utilized ;)

Goal

I've previously employed importmaps in one of my micro-frontend projects alongside single-spa and the importmap overrides library. This approach significantly enhances the developer experience in complex environments by allowing direct integration of a local server into an integration server (more info in the YouTube video from Joel Denning).

It also proves beneficial for testing, enabling the generation of an affected importmap on PRs and its use to override bundles in an existing environment without the need for cloning or deploying anything.

It also facilitates incremental and canary deployment.

Issue

My intention was to apply the same strategy with native federation due to its utilization. However, I found it unfeasible due to a globalCache that does not account for potential modifications to the importmaps overrides. This capability is a default feature and it is supported by the es-module-shims library.

Propositions

First, let's examine the current behavior:

flowchart TD
    subgraph Remote [On Load Remote Module]
        1[loadRemoteModule on routing or in component]
        2[getRemote Infos From Cache]
        3[importShim from remote url]

        1 --> 2
        2 --> 3
    end

    subgraph Host [On Host Initialization]
        direction TB
        a[initFederation In Host]
        b[Fetch federation.manifest.json]

        h[Load remoteEntry.json of the host]
        i[Generate importmap with key/url]

        y[Combine Host importmap and remotes importmaps]
        z[Write importmaps in DOM]

        a --> b
        a --> A
        b --> B

        subgraph A [hostImportMap]
            direction TB
            h[Load remoteEntry.json]
            i[Generate importmap with key/url]

            h --> i
        end

        subgraph B [remotesImportMap]
            direction TB
            c[Load remoteEntry.json]
            d[Generate importmap with key/url]
            e[Add remote entry infos to globalCache]

            c --> d
            c --> e
        end

        A --> y
        B --> y
        y --> z
    end

    Cache((globalCache))

    e .-> Cache
    2 .-> Cache

1. Allow importmap overrides in the `es-module-shims` library

 <script type="esms-options">
 {
   "shimMode": true
   "mapOverrides": true
 }
 </script>

2. Import the importmap directly as a file in the `index.html` instead of runtime code in `initFederation`

The browser can combine directly multiple importmaps and load them for us. I would suggest that instead of executing runtime code, integrating all importmap already generated at compile time directly in the index.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>host</title>
    <base href="/" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link rel="icon" type="image/x-icon" href="favicon.ico" />

    <script type="importmap-shim" src="assets/host-shared.importmap.json"></script>
    <script type="importmap-shim" src="assets/remotes.importmap.json"></script>

  </head>
  <body>
    <nx-nf-root></nx-nf-root>
  </body>
</html>

3. Ensure that when we `loadRemoteModule`, we obtain the actual version from the `importmap`

By listening to the DOM mutation like es-module-shim and refreshing the cache

  new MutationObserver((mutations) => {
    for (const { addedNodes, type } of mutations) {
      if (type !== 'childList') continue;
      for (const node of addedNodes) {
        if (node.tagName === 'SCRIPT') {
          if (node.type === 'importmap-shim' || node.type === 'importmap') {
            const remoteNamesToRemote = globalcache.remoteNamesToRemote;
            // TODO: should update the remoteNamesToRemote by changing the base url
          }
        }
      }
    }
  }).observe(document, { childList: true, subtree: true });

The challenge here is that the cache is grouped per remote and only maintains a single base URL, so overriding one exposes would change the URL for others as well.

By directly reading the `importmap`

The impact on performance is uncertain. Having an API library to manipulate importmaps would be advantageous.

Work Around

I have succeeded in overriding the loadRemoteModule function:

export function getImportMapOverride(importMapKey: string): string | undefined {
  // @ts-ignore
  const imports = window?.importMapOverrides?.getOverrideMap()?.imports;
  return imports && imports[importMapKey];
}

export async function loadRemoteOverrideUtils<T = any>(
  remoteName: string,
  exposedModule: string
): Promise<T> {
  const remoteKey = `${remoteName}/${exposedModule}`;

  const importMapOverrideUrl = getImportMapOverride(remoteKey);

  // If override found for remoteKey, load it separately
  // Else, use the default function
  return importMapOverrideUrl
    ? importShim<T>(importMapOverrideUrl)
    : loadRemoteModule(remoteName, exposedModule);
}

But I don't like the fact that the globalCache of native federation is still invalid.

full code here https://github.com/jogelin/nx-nf/tree/poc-load-remote-overrides

What about directly overriding the `federation.manifest.json`?

In my opinion, it is the best approach because overriding only one exposes does not make sense. Usually, we want to override an entire remote URL.

By using a custom approach

I implemented an easy way, but custom, but it keeps the globalCache in sync:

If you have that override in your localStorage:

Directly in the main.ts you can use:

initFederation('/assets/federation.manifest.json')
  .then(() => initFederationOverrides()) // <-- HERE
  .catch((err) => console.error(err))
  .then((_) => import('./bootstrap'))
  .catch((err) => console.error(err));

utilities functions:

import { processRemoteInfo } from '@angular-architects/native-federation';
import { ImportMap } from './import-map.type';

const NATIVE_FEDERATION_LOCAL_STORAGE_PREFIX = 'native-federation-override:';

export function initFederationOverrides(): Promise<ImportMap[]> {
  const overrides = loadNativeFederationOverridesFromStorage();
  const processRemoteInfoPromises = Object.entries(overrides).map(
    ([remoteName, url]) => processRemoteInfo(url, remoteName)
  );

  return Promise.all(processRemoteInfoPromises);
}

function loadNativeFederationOverridesFromStorage(): Record<string, string> {
  return Object.entries(localStorage).reduce((overrides, [key, url]) => {
    return {
      ...overrides,
      ...(key.startsWith(NATIVE_FEDERATION_LOCAL_STORAGE_PREFIX) && {
        [key.replace(NATIVE_FEDERATION_LOCAL_STORAGE_PREFIX, '')]: url,
      }),
    };
  }, {});
}

But why not using an `importmap` to load the `remoteEntry.json` files?

The federation.manifest.json would then appear as:

{
    imports: {
        "host": "http://localhost:4200/remoteEntry.json",
    "mfAccount": "http://localhost:4203/remoteEntry.json",
    "mfHome": "http://localhost:4201/remoteEntry.json",
    "mfLogin": "http://localhost:4202/remoteEntry.json"
    }
}

and directly integrate it into the index.html:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>host</title>
    <base href="/" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link rel="icon" type="image/x-icon" href="favicon.ico" />

    <script type="importmap-shim" src="assets/federation.manifest.json"></script>

  </head>
  <body>
    <nx-nf-root></nx-nf-root>
  </body>
</html>

and in the initFederation, we just need to use:

import('mfAccount').then((remoteEntry) => // same as before, inject exposes to inline importmap)

In this way: ✅ It is standard ✅ We use importmap everywhere ✅ We can use default override behaviour ✅ It allows to override a full remote AND exposes separately

What do you Think?

Do you want to make a PR?

Yes of course after discussion :)

View on GitHub

However, the underlying principles remain unchanged. Rather than directly utilizing the importmap.json, I have the option to override the federation.manifest.json. This requires the creation of custom code within the application to enable the overrides of the bundles.

Do you want to try it?

First, clone my GitHub repository:

git clone git@github.com:jogelin/nx-nf.git && cd nx-nf

2. Begin by installing the packages:

pnpm install

3. Next, you can start one micro frontend, for example, mf-admin:

npx nx run mf-admin:serve

4. Then, access the URL https://nx-nf-a2d7c.web.app/admin where I have already deployed the application. You should see the application:

5. Now, open your favorite browser debugging tool and connect your local server to the remote application by adding this entry in the local storage:

localStorage.setItem('native-federation-override:mfAdmin', 'http://localhost:4203/remoteEntry.json') // override mfAdmin with you local server

6. Then, make modifications to the mf-admin micro frontend. For example, change the message from "Welcome to the Admin Page" to “Welcome to the LOCAL Admin Page”

7. After you make changes, reload the page, and you should see your modifications reflected on the remote server immediately!

8. To revert the changes, simply remove the entry from the local storage and refresh the page to see the original state again.

localStorage.removeItem('native-federation-override:mfAdmin');

You can override any micro frontend using this approach. However, as I mentioned, the method involving native federation is not entirely native yet because it doesn’t utilize the default behavior of import maps.

You can find all the code utilizing Native Federation, Angular, and Nx in my GitHub repository.

jogelin / nx-nf

POC repository showing Nx Native Federation and Importmap Override Configurations

NxNf

⏰ It’s time to talk about Import Map, Micro Frontend, and Nx Monorepo

How leveraging native import map overrides can significantly benefit your micro frontend architecture

View on GitHub

Final Thoughts

This exploration reveals the power of the native JavaScript ecosystem in browsers, highlighting how native support for ES modules enhances our development experience beyond faster build times.

The simplicity and effectiveness of the import map principle show us a way to solve complex issues with elegant solutions. It hints at a future where reliance on custom framework implementations diminishes in favor of native browser features, making development smoother and more intuitive.

Moreover, the use of Nx as part of this ecosystem offers a powerful toolkit that enables developers to approach complex projects with enhanced agility and precision.

The hope for more native features like these grows, promising a simpler, yet more powerful development landscape. With Nx and advancements in browser capabilities, we’re moving towards a future where building sophisticated web applications becomes more accessible and efficient.

🚀 Stay Tuned!

Credits

Joel Denning

Joel Denning is the visionary behind single-spa, boasting profound insights into the true mechanics of the web and is, in my view, a pioneer in micro frontend architecture. I highly recommend checking the single-spa website and his YouTube channel. While the videos might appear dated at first glance, rest assured, Joel is ahead of his time, and the content remains incredibly relevant today.

Engineer, Architect, Speaker, Trainer, Consultant, and Author, Manfred knows what he is talking about. For everyone, not just Angular, interested in micro frontends and web architecture in general, I encourage you to have a look at his book Enterprise Angular: Micro Frontends and Moduliths with Angular and the blog of the Angular Architect team.

Start a Collaboration?

Connect with me on Twitter • LinkedIn • Github.

💎 Discovering Nx Project Crystal’s Magic

jogelin — Mon, 26 Feb 2024 17:01:51 +0000

Overview

After delving into this feature in my previous articles:

I’m excited to discuss again one of my favorite Nx features: “The Inferred Project Configurations.” The Nx team now introduces a unified approach known as Nx Project Crystal 💎.

In this article, I’ll cover:

· The Origin
· Project Crystal in a Nutshell
· How it works
· Create Your Cyrstal Plugin
· A Multitude of Benefits
· Cautions

The Origin

To grasp the concept of Nx Project Crystal 💎, let’s revisit the Nx team’s journey in project configuration.

1. angular.json

“In the beginning, there was nothing”. The Nx team began defining a monorepo structure for apps and libs using angular.json, tied to Angular CLI:

However, this initial approach was specific to Angular, lacking generality and extensibility.

2. workspace.json

A v2 schema introduced theworkspace.json files*.* Some concepts were generalized such as the executors (instead of a builder) or the generators (instead of schematics).

The new format proved useful due to its extensibility and generality. However, maintaining a large codebase within a single file presented challenges. Consequently, the demand for greater flexibility and project-specific specifications increased.

3. project.json

Thus, the concept of distributed configuration emerged with the project.json (or package.json) file. It maintained the same format but was divided and specified at the root of each project.

Defining a project has become straightforward — simply add that file, and you’re done. However, the proliferation of files implies challenging maintenance due to significant duplication. This situation necessitated the development of migration scripts to manage these configurations effectively.

Additionally, there emerged a requirement to support technologies not adhering to Nx’s standards, enabling the integration of Nx benefits into existing repositories and accommodating various technologies, including .Net, among others.

4. Inferred configuration

Then, project inference appeared, introducing the possibility of assigning project configurations simply through glob pattern matching. An Nx plugin exposes specific functions that are automatically loaded by the Nx core, and voilà, you have dynamic configuration :)

It began with Plugin v1, which only assigned a list of targets for existing projects (see 🚡 Nx Targets Elevated).

Then came Plugin v2, offering the ability to dynamically add project nodes with full configuration, even if they do not exist in your codebase (see ✌️ Nx Plugin v2: Dynamic Project Configurations).

And finally, a consolidated approach to that concept was integrated into Nx:

Project Crystal in a Nutshell

The Nx Project Crystal offers the ability to utilize Nx plugins that automatically add tasks to your projects based on the configuration files of various tools.

I recommend watching the great video Nx — Project Crystal and reading the related article What if Nx Plugins Were More Like VSCode Extensions by Juri Strumpflohner.

The Nx team likes to compare it to a simple plugin that you’ll add to your favorite IDE. You don’t need to do anything else; the plugin activates functionalities automatically because it recognizes specific configurations or patterns in your workspace.

For example, if you want to use Vite to build your application, you simply need to add the @nx/vite plugin to your Nx workspace by using:

nx add @nx/vite

Automatically, all projects that contain a vite.config.* file will have new tasks assigned. You will be able to use build, preview, test, serve and serve-static directly:

This is true for Vite, but it is also applies to many other plugins, such as:

@nx/webpack → build, preview, serve and serve-static
@nx/cypress → e2e, e2e-ci and component-test
@nx/playwright → e2e, e2e-ci
@nx/detox → build, start and test
@nx/eslint → lint
@nx/expo → start, serve, run-ios, run-android, export, prebuild, install, build and submit
@nx/jest → test
@nx/next → build, dev, start and serve-static
@nx/nuxt → build, test and serve
@nx/react-native → start, pod-install, bundle, run-ios, run-android, build-io and build-android
@nx/remix → build, serve, start and typecheck
@nx/storybook → build-storybook, storybook, test-storybook and static-storybook

Why don’t I see the main plugins like @nx/angular or @nx/react?

Your Angular/React project configurations have already been simplified through the removal of common targets like lint or test.

However, it’s challenging to generalize targets like build or serve because they involve many specifications unique to your app.

IMO, it’s only a matter of time before the Nx team proposes a solution for this :).

How it works

Let’s take a look behind the scenes to understand how we can benefit from this feature.

As you can see, Nx computes the project graph configuration by loading configurations from multiple places:

First, it iterates over the plugin list declared in your nx.json and calls the createNodes function for each.
Then, it reads targetDefaults in the nx.json file and it applies the default configuration to the corresponding targets.
Finally, it uses the configuration from the project.json (or package.json), if specified at the root of the project.

How do I know which task is available at the end?

Nx provided a solution for that too! You can explore your Nx workspace and see the consolidated configuration simply by running the command:

nx show project myreactapp --web

And you will be able to visualize all of the configurations for your project

This is also visible in the Nx console plugin in your IDE!

Create Your Cyrstal Plugin

Let’s explore how quickly you can implement your plugin, injecting your configurations and behaviors into your workspace.

Nx Plugin

The first step is to create an Nx plugin and configure it in your nx.json.

It can be a simple *.ts file located anywhere in your workspace that you register in your nx.json:

{
  "plugins": [..., "./tools/plugins/my-plugin.ts"],
}

Or you can use the plugin generator by executing the command:

nx g @nx/plugin:plugin my-plugin

And again, you’ll need to register your plugin in your nx.json configuration file:

{
  "plugins": [..., "@my-org/my-plugin"]
}

You can also provide options to your plugin by using the following syntax in your nx.josn:

{
  "plugins": [
    ...,
    {
      "plugin": "@my-org/my-plugin",
      "options": {
        "targetName": "build"
      }
    }
  ],
}

Export the createNodes from your plugin

Then, you can begin implementing your plugin. I highly recommend examining some existing Nx plugin implementations:

For simplicity, look at @nx/eslint or @nx/jest.
For more advanced task distribution, consider @nx/cypress or @nx/playwright.
For custom implementations, check out @nx-dotnet/core

I chose the @nx/vite plugin to illustrate the mechanism:

Many functions are omitted because they are specific to the plugin and not necessary to grasp the main structure of the plugin.

I divided the code into three main parts:

A. The plugin options contract: Typically used to define the names of the targets you wish to generate, but it can be used for anything.

B. The targets memoization: Since generating the configuration graph is resource-intensive, the memoization pattern is essential to prevent unnecessary computation when nothing changes.

C. The main createNodes function: This function is invoked by Nx and returns new project configurations.

The createNodes function is a pair consisting of a glob pattern to determine when the plugin should be activated and a function that receives the activation context as a parameter and can return a project configuration.
The configFilePath contains the path matching the glob pattern, representing the project’s root path.
Even if the glob pattern matches, it’s possible to filter out and skip execution if it doesn’t meet a specific criterion. Here, the criterion is to assign tasks only to existing projects.
Since the options are optional, they simply provide a way to set default values for target names.
This forms the core of the function, generating all tasks or retrieving them from the cache if they exist.
It then creates and returns the project configuration to be incorporated into the global project configuration graph.

A Multitude of Benefits

You’ll gain from project inference and creating your plugin in several compelling use cases.

Remove duplication of configurations

Adhering to the “Don’t Repeat Yourself” principle becomes straightforward. If your workspace is cluttered with redundant project.json configurations, creating plugins to inject common elements significantly eases long-term maintenance.

Centralize your workspace conventions

As I discussed in my previous article ⚡ The Super Power of Conventions with Nx, for teams managing large codebases, enhancing the development experience through established conventions is invaluable. These can be rules or best practices, encapsulated within an Nx plugin to uniformly apply across your workspace.

Speed up the Nx adoption on the existing repository!

That’s one of my favorite use cases, just add Nx and plugins to your existing repo, and you’ll access many functionalities automatically.

But before having the possibility to execute tasks, you need to ensure that Nx can see your projects. The first reflex is to create a project.json file everywhere you want to declare a project.

However, it will be difficult if you have to define hundreds of project.json with the same configuration. It can also be projects that are not even related to JavaScript projects. In that case, the creation of custom plugins will facilitate that definition in a short time.

For example, if you have a huge list of themes containing only *.scss files like:

.
├── apps/
└── libs/
    └── themes/
        ├── core/
        ├── blue/
        │   ├── components/
        │   ├── colors.scss
        │   ├── variables.scss
        │   └── index.scss
        ├── dark/
        │   └── ...
        ├── light/
        │   └── ...
        ├── yellow/
        │   └── ...
        └── pink/
            └── ...

If you want to see the dependencies between the applications and the themes, you can simply create a plugin that will expose the themes as projects in Nx:

export const createNodes: CreateNodes = [
  'libs/themes/**/index.scss',
  (configFilePath, options, context) => {
    const name = toProjectName(configFilePath);
    return {
      projects: {
        [`theme-${name}`]: {
          name,
          root: dirname(configFilePath),
          targets: {
            build:{
              // ...
            }
          }
        },
      },
    };
  },
];

Automatically, without having to create any project.json file, you will see them in your dependency graph and gain the benefit of Nx features such as affected, caching, boundaries, etc.

Task Distributions on CI

Another interesting use case is the dynamic creation of tasks to parallelize executions that could be time-consuming.

By dividing long-running tasks into multiple tasks, you can benefit from the Nx Distribution Task Execution on CI and parallelize all tasks.

For example, Nx has implemented this approach for Cypress or Playwright by automatically splitting E2E tasks by file.

If you are interested in technical details, you can also read my article ⚡ Distributed e2e Task Execution with Nx for Playwright and Cypress

Less complex generators and migrations

When I started using the project inference, the main concern was “It will break the migration process of Nx!”

Indeed! But before Nx Project Crystal, project inference was only used for specific use cases with custom executors not covered by Nx migrations.

🤯 Previously, supporting advanced project configurations required creating complex generators for complex project.json files.

Maintaining these was challenging. With every change, we needed to update the generator and create a migration script to apply modifications across all projects.

This was time-consuming and frustrating, especially when migrations were buggy.

😎 Now, with the project inference approach, you can centralize your specific configurations. If something changes, you simply update your plugins, and the changes are automatically applied to all projects.

No need for complex generators or migrations anymore!

Cautions

Plugins Order Matters!

As highlighted in the flow chart, configurations are not deeply merged, meaning if two plugins configure the same target name, only the last one will take precedence.

For instance, if your nx.json includes:

{
  "plugins": ["@nx/cypress/plugin", "@nx/playwright/plugin"]
}

And a project contains both Cypress and Playwright tests, Nx will first invoke @nx/cypress and then @nx/playwright.

To address this, you can rename one of the targets using the plugin options in nx.json:

{
  "plugins": [
    {
      "plugin": "@nx/cypress/plugin",
      "options": {
        "targetName": "e2e-legacy"
      }
    },
    "@nx/playwright/plugin"
  ]
}

This allows you to run both targets:

Configs Order Matters!

It’s also important to note that targetDefaults configurations in your nx.json take precedence over plugins.

For example, if a plugin returns a configuration like:

{
  "my-app": {
    "build": {
      "executor": "@angular-devkit/build-angular:application",
      "dependsOn": ["^build", "generate-api"]
    },
    "generate-api": {
      "executor": "..."
    }
  }
}

But in your nx.json, you’ve specified targetDefaults like:

{
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"]
    }
  }
}

Then your generate-api target won’t be executed because the targetDefaults will override the dependsOn configuration.

I would recommend being specific in your targetDefaults to prevent conflicts with the plugins.

{
  "targetDefaults": {
    "@angular-devkit/build-angular:application": {
      "dependsOn": ["^build", "generate-api"]
    }
  }
}

Final Thoughts

The journey the Nx team embarked on to bring Project Crystal to life has been truly inspiring. From the early days of Angular-specific setups to the seamless approach offered by Project Crystal, every step has shown their dedication to making our lives as developers easier.

Looking ahead, the idea of Zero Configuration repositories sounds like an exciting leap forward. It promises a future where setting up and managing projects will be a breeze, giving us more time to focus on what we love: building awesome software.

So let’s embrace tools like Nx Project Crystal with open arms. They’re here to help us work smarter, not harder, and together, we can unlock endless possibilities for innovation and creativity in our development journeys.

Your feedback and suggestions are always welcome! 🚀 Stay Tuned!

Twitter — LinkedIn — Github

Forem: jogelin

🍒 Cherry-Picked Nx v19.1 Updates

[🌊 Nx Core]

Typescript declarations support for esbuild libraries

New separator option for the result of the nx show command

Target another executor in schema definitions

Support bun Package Manager!

[💫 Upgrades]

Support Angular 18

Related

🍒 Cherry-Picked Nx v19 Updates

Release Note 19 (2024–05–06)

[🌊 Nx Core]

Metadata Property in Project Configuration

Change imports for the Webpack plugin

Global forwardAllArgs for nx:run-commands

[💎 Project Crystal]

Add generators to convert projects to inferred targets

[💫 Upgrades]

Support React 18.3

[🌐 nx.dev]

Main Navigation Menu

New Blog Page

New Enterprise Page

[☁️ Nx Cloud]

DTE v2

Related

👥 Reproducible Nx Workspace with HugeNx’s Conventions

jogelin / huge-nx

Huge

Getting Started

1. Define your HugeNx's conventions:

2. Use create-huge-nx client to generate

HugeNx’s Conventions

ProjectTypes

Reproducible Generation

Consistent Monorepo

Let’s Generate Your Workspace

1. Define your conventions

2. Use create-huge-nx CLI

More presets

Final Thoughts

jogelin / huge-nx

Huge

Getting Started

1. Define your HugeNx's conventions:

2. Use create-huge-nx client to generate

🍒 Cherry-Picked Nx v18.3 Updates

Release Note 18.3 (2024–04–16)

[Core] Metadata Property in Project Configuration

[Core] List Crystal Plugin in Nx Report

[Jest] Ability to Split Jest Tests

[nx.dev] Various nx.dev Improvements

Remember selected tabs

New Contact Page

🍒 Cherry-Picked Nx v18.2 Updates

Release Note 18.2 (2024–03–28)

[Angular] Support Angular 17.3

[Core] Scope Nx Plugin Project Crystal 💛💛💛

Current Behavior

Expected Behavior

Related Issue(s)

[Gradle] New Gradle Integration

[Cypress] New target open-cypress is added by the @nx/cypress/plugin

Current Behavior

Expected Behavior

Related Issue(s)

🩹 Nx Crystal Plugin Picking the Essentials

My Use Case

Patch Nx Plugins

Craft Your Custom Plugin Now

⚠️ Cautions

In Conclusion

Related

⛔ Target Exclusions in Nx Project Crystal

jogelin ・ Mar 21

📤 Local Library Development with Nx Release and Verdaccio

Practical Use Case

What happened?

Verdaccio Setup

[Cypress] New target `open-cypress` is added by the @nx/cypress/plugin

[Remix] Add Remix Presets in “`create-nx-workspace"`

Manually Override the “test” Target with `nx:noop`

Dynamically Override Any Target with `nx:noop`

Create Your Custom `@nx/jest/plugin` and Skip the Projects