DEV Community: Zack DeRose

Launch Nx Week Recap!!

Zack DeRose — Thu, 15 Feb 2024 18:09:12 +0000

We just finished wrapping up Launch Nx Week, which ran from February 5-9, including a full conference on Thursday!

In this article, we're going to recap all the things launched during Launch Nx Conf, as well as all the talks given during the conference! Here's a set of links so you can fast-forward to the stuff you're most interested in if you want!

Nx 18.0 && Project Crystal
- Project Crystal - By Juri Strumpflohner
- Project Crystal + .NET in Action - By Craigory Coppola
New Plugin: @nx/nuxt
Nx Agents
- Nx Agents Walkthrough: Effortlessly Fast CI Built for Monorepos - By Rares Matei
- Solving E2E Tests - By Altan Stalker
Tusky
Nx Release
- Releasing Nx Release - By James Henry

Nx 18.0 && Project Crystal

Exciting news!! We've broken our standard release cadance of publishing a new major version every 6 months to release Nx 18, just 3 months after releasing Nx 17 in December 2024.

Juri announced launched Project Crystal with this video:

The short version is: Nx project crystal means Nx plugins make your codebases work more seemlessly with less config.

For the long version, checkout this blog post by Juri where he describes how Nx plugins are now more like VsCode Extentions!

And don't miss our two conference talks on this subject:

Conference Talk: Project Crystal

Speaker: Juri Strumpflohner | slides

Conference Talk: Project Crystal + .NET in Action

Speaker: Craigory Coppola | slides | example repo

New Plugin: @nx/nuxt

On Tuesday we launched our newest plugin, and our first plugin to be 💎crystalized💎 from it's very beginning: @nx/nuxt!

Zack explains Nuxt and how to use the new plugin in this video:

To add @nx/nuxt to your codebase, use the command:

> nx add @nx/nuxt

Huge thanks to Katerina for her work on the plugin, and Nuxt maintainer, Daniel Roe, for helping to guide the project!

Zack, Katerina, and Daniel got together to live code a working tic-tac-toe app using the new Nuxt plugin and partykit in this livestream:

Nx Agents Launched

Nx Agents are here!! We launched Nx Agents on Wednesday, and it climbed into the top 20 on Product Hunt!

We're very excited about Nx Agents because we think that in its current state, Continuous Integration/Deployment is broken, and we think that Nx paired with Nx Agents fixes Continuous Integration. Zack explains more in this video:

Be sure to also checkout the blog post from Isaac on the topic, including explanations of the Nx Agents exclusive features, like auto-detection and retrying for flaky tasks, and automatically splitting lengthy end-to-end tests!

You can signup for Nx Agents NOW, and find out more of the details in our docs!

Rares and Altan are on the team building Nx Cloud, and during the conference, they dove deeper into some of these topics:

Conference Talk: Nx Agents Walkthrough: Effortlessly Fast CI Built for Monorepos

Speaker: Rares Matei | slides | example repo | failed runs example | nx agents full run

Conference Talk: Solving E2E Tests

Speaker: Altan Stalker

Tusky

Thursday, we had a surprise announcement for our newest product on Nx Cloud: Tusky.

Tusky is an Artificial Intelligence for your codebase, and it will be available on Nx Cloud soon - starting in Spring of 2024.

In the teaser video, you can see some ways Tusky will be integrated into Nx Cloud to provide explainations on failed tasks, or cache misses.

The more exciting features of Tusky though includes the ability to perfectly optimize the number of agents used per PR - even spinning up and tearing down agents mid-pipeline! This is a huge optimization for task distribution, and will help optimize both walltime of your CI, as well as compute costs!

Tusky will also be able to provide organizational-level insights to your codebase, including automatically detecting development groups (like lines of business) inside your codebase based on commit history, and providing statistical insights on their commit patterns. We're also excited about Tusky being able to make suggestions on things you can do to further optimize your codebase - like generating a PR to introduce Codeowners to the repo!

Nx Release Is Stable

Versioning and publishing packages is always a bit tricky. Mix in the added complexity of having multiple packages - sometimes with different versioning or publishing strategies - inside the same codebase, and things can get weird quick!

For a long time, Nx has been purposefully versioning and publishing agnostic, but given our time spent as stewards of Lerna (the OG Javascript monorepo tool), we've been able to take alot of that experience and finally feel confident creating our own versioning and publishing implementation.

Therefore, we've been working on a new command to the Nx CLI: nx release. We launched this on Friday of our Launch Nx week!

Juri goes into full details in this blog post, and James Henry - our Director of Engineering and the primary engineer responsible for both maintaining Lerna and creating Nx Release - expands further in his conference talk:

Conference Talk: Releasing Nx Release

Speaker: James Henry | example repo

Wrapping up

Juri, Zack, and Victor wrapped up the week with a livestream recapping the launches from the week - including answering your questions live:

That’s all for now folks! We’re just starting up a new iteration of development on Nx, so be sure to subscribe to our YouTube channel to get updates when new features land! Until next time, KEEP WORKING HARD!

Learn more

Nx 17.2 Update!!

Zack DeRose — Wed, 20 Dec 2023 17:02:39 +0000

It's been a bit since we launched Nx 17! In this article, we'll go over some of the new developments and improvements that have landed in Nx 17.2:

Nx Closes In On 4 Million Weekly NPM Downloads!!
New Simplified Project Configuration On the Way
Rust for Speed, Typescript for extensibility
Module Federation Updates
Nx Release Updates
Angular 17 (AND NgRx 17) Support
Smart Monorepos - Fast CI
New Canary Releases

Nx Closes In On 4 Million Weekly NPM Downloads!!

2023 has been a great year for Nx! We worked with a lot of the teams out there building fantastic open source tools. And you can see the results: we made Vite a first class citizen in many of our Nx plugins, we added support for Rspack, streamlined our Node experience by adding an Nx team maintained Fastify plugin, support for Storybook interaction testing, welcomed Playwright to the family and much more, continuing our missing to push developer productivity to the limits!

And our downloads on NPM keep confirming this. We are about to cross 4 million downloads per week.

If this made you curious, keep an eye on our blog or X/Twitter as we're going to release a 2023 year recap blog post next week.

New Simplified Project Configuration On the Way

Adoption is crucial, and simplicity is the driver for adoption. Last year we heavily optimized how you can use Nx in an existing project. Just drop the nx package (or run nx init) and that's it. Nx understands your workspace and efficiently runs your package.json scripts.

Using Nx at that level is definitely useful as you get intelligent parallelization, task pipelines and caching. But it is just the tip of the iceberg of what Nx is actually capable of. Nx plugins provide much more, especially in terms of DX and developer productivity by taking away some of the burden of configuring your monorepo tooling. But many devs new to Nx found it harder to get started with them initially and incrementally migrating to Nx plugins wasn't as straightforward as we'd wanted it to be.

This is something that's gonna change drastically in 2024. And we've layed the first cornerstone for that. Nx 17.2 includes what we codename "Nx project config v3". But it is behind a feature flag still as we're streamlining the last bits. The goal?

going almost configuration-less (good defaults, you customize when you need to)
allowing easy drop-in of Nx plugins into existing workspaces (provides immediate productivity gains, but stays out of your way)

This opens up a series of possibilities which we're already super excited about. You'll hear more about this in the new year ;)

Rust for Speed, Typescript for extensibility

At Nx, we've heavily embraced Typescript from the beginning, and we've been very happy with that decision.

If you've been paying attention to previous release announcements though, you've probably noticed that we've been moving more and more of the computationally intensive and performance critical pieces of the core of Nx from Typescript to Rust.

That trend continues in Nx 17.2 with Nx using Rust for its task hashing by default. There's no adjustments needed for this change, and Nx will continue to behave the same way, just faster!

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

Module Federation Updates

Module Federation has been a particularly hot topic lately, and 17.2 is coming in with some great enhancements to Nx's already best-in-class support for Module Federation!

To start, we've greatly reduced the CPU and memory used for standing up your Module Federation "web" locally. These enhancements should be great news to larger workspaces using a Module Federation approach, where there were heavy CPU and memory costs to serving your entire federation locally.

We accomplished these improvements by batching any applications that are not being watched for changes (listed with the --devRemotes option) to a single server, rather than a unique server for each application. We also parallelized the builds of these static applications when you start up your serve! You can now use the --parallel={number} option to specify how many builds you want going at any given time.

In addition to performance improvements, we've brought the concept of dynamic federation to our React module federation support. Dynamic federation allows a host application to dynamically load remotes via the manifest file.

You can generate your react module federation workspace now to use dyanmic federation via the --dynamic flag:

nx generate @nx/react:host acme --remotes=nx --dynamic

Or you can use the utility itself by importing from @nx/react/mf:

import { loadRemoteModule } from '@nx/react/mf';

Lastly, we have an example repo available now to illustrate how to create a plugin for Module Federation using Nx with Vite! This is something that we are monitoring and may provide an out-of-the-box solution to this in a future release!

Nx Release Updates

Nx 17 launched with the new nx release capability in the Nx CLI. Since then we've been streamlining the experience, accounting for various edge cases and release scenarios. (extensive docs are being worked on rn ;)

To give you full flexibility, in 17.2, we've added a programmatic API, which will allow you to easily write custom release scripts:

import {
  releaseChangelog,
  releasePublish,
  releaseVersion,
} from 'nx/release';

(async () => {
  const { workspaceVersion, projectsVersionData } = await releaseVersion({
    specifier: 'minor'
  });
  await releaseChangelog({
    versionData: projectsVersionData,
    version: workspaceVersion,
  });
  await releasePublish();

  process.exit(0);
})();

This script above demonstrates how you can use this API to create your own script for updating your workspace's version, then creating a changelog, and then publishing your package!

We've also added first class support for independently released projects, meaning you can now target a specific project for release with the --projects command. For example, you can create a new version for just one project in your workspace with the command:

nx release version patch --project=my-project

Angular 17 (AND NgRx 17) Support

Angular is in the middle of a HUGE renaissance, between their new logo, new docs site, and introduction of some awesome features like Signals.

Nx is here to support the transition! Nx has always been a great fit for Angular, and now supports Angular 17 as well as NgRx 17.

To automatically migrate existing workspaces to Angular v17, run the commands:

> nx migrate latest
> nx migrate --run-migrations

You can also use the --interactive flag if you want to migrate your workspace to the latest version of Nx while staying on your current version of Angular:

> nx migrate latest --interactive
✔ Do you want to update to TypeScript v5.2? (Y/n) · true
✔ Do you want to update the Angular version to v17? (Y/n) · false

 >  NX   The migrate command has run successfully.

   - package.json has been updated.
   - migrations.json has been generated.

 >  NX   Next steps:

   - Run 'nx migrate --run-migrations'

Smart Monorepos - Fast CI

We just gave our Nx homepage a small facelift, including a new tagline, subtagline and illustration to better reflect Nx's mission statement.

When you enter the monorepo space, having good local development experience and tooling to support you is one thing, scaling is the other. And scaling comes with multiple challenges, from scaling teams working on the monorepo to maintaining high throughput on CI.

The latter is a common headache and we've seen companies struggle. With Nx we're moving into the direction of becoming your e2e solution for monorepos, where we don't just cover your local dev experience, but also provide robust and scalable solutions on CI.

We're super excited to have launched "Nx Agents" to Early Access. If you haven't seen Victor's video yet about how he reduced e2e tests from 90 minutes to 10, then make sure to check it out.

"Nx Agents" are the next iteration of DTE, providing a more flexible, cost effective and more performant approach to distribution on CI. This includes things like being able to dynamically allocate machines based on the size of the PR and flaky task detection and re-running. Also, it can be configured with a single line:

- name: Start CI run
  run: 'npx nx-cloud start-ci-run --distributes-on="8 linux-medium-js"'
  ...

You can run Nx Agents on any CI provider. If you're curious, sign up for early access!

New Canary Releases

We've added a new npm release tag: canary!

This canary release is created via a cron job that will regularly publish the current contents of the master branch of Nx.

You can give the canary version a try new for a new workspace using the command:

> npx create-nx-workspace@canary

This should be useful for previewing new not-yet released features!

Upcoming Release Livestream

We're going live in January with the Nx team to go over these updates as well! Be sure to click the link to get notified when we go live! And feel free to come with your questions in the chat!

Automatically Update Nx

Updating Nx and its plugins is easy as we ship an automated migration command.

npx nx migrate latest

After updating your dependencies, run any necessary migrations.

npx nx migrate --run-migrations

Wrapping up

Learn more

More Nx Release Notes:

Nx 17.0 Has Landed!!!

Zack DeRose — Tue, 24 Oct 2023 14:46:00 +0000

We're excited to announce the release of Nx version 17!

In this article, we'll cover the main things you need to know to get the most of Nx 17!

Here's a Table of Contents so you can skip straight to the updates you care about the most:

It's a Vue-tiful Day for Nx
Enhancements to Module Federation Support
More Consistent Generator Paths
The NEW Nx AI Chatbot
More Seamless Integration With Nx Cloud
nx.json Simplification
Nx Repo Begins Dog-Fooding Nx Workflows
Task Graphing Improvements
@nx/linter Renamed to @nx/eslint
New Experimental Feature: Nx Release
Experimental: Nx Project Inference API v2
20k Github Stars!!
How to Update Nx

It's a Vue-tiful Day for Nx!

Ever since we added Vite a first-class citizen to Nx workspaces (see @nx/vite) we started falling in love with the Vue commmunity. The only logical next step: Nx now provides a brand new Vue plugin that is being maintained by the Nx team! (And we're already working on a Nuxt plugin 🤫)

The first place you might notice this new support is in the create-nx-workspace script:

Selecting this option will create a brand new Nx workspace with a fresh new Vue application, all setup and ready to develop! To add new Vue projects to your existing Nx workspaces, just add our new @nx/vue package as a dev dependency to your workspace, e.g.:

npm add -D @nx/vue

And you'll have access to Nx generators so that you can generate Vue applications, libraries, components, and more in your workspace:

We're very excited for this support to land and we're eager to get it into our user's hands and see what Nx can do to help Vue developers so we can continue to refine our support and make Vue with Nx an excellent developer experience.

If you're eager to learn more, make sure to check out our new Vue standalone tutorial.

Enhancements to Module Federation Support

Nx already had really great support for Module Federation - Nx 17 improves on this support:

NEW: Typesafe Config

Projects created with Nx's generators for module federation will now be created with a module-federation.config.ts file (as opposed to a .js file). A new ModuleFederationConfig interface is now exported from the @nx/webpack plugin as well.

Better Typesafety Across Modules

Nx 17 improves typesafety across modules now so that proper typesafety is now supported across dynamic imports.

NEW GENERATOR: Federate ANYTHING.

Both the @nx/react and @nx/angular now include a federate-module generator. This will allow you to create a federated module out of any Nx project.

To run this generator, use the command:

> nx g federate-module <project name> --path=<path to module to be exposed> --remote=<name of remote exposing module>

This will create a new project that exposes the targeted project as a federated module.

Managing Module Versions

Nx now supports targeted versioning for federated modules.

To create versions for a given project, you can use the version property of that project's package.json file, and then build that project create the version locally.

Then when consuming this library, you can use the shared method of the ModuleFederationConfig:

import { ModuleFederationConfig } from '@nx/webpack';

const config: ModuleFederationConfig = {
  name: 'my-remote',
  exposes: {
    './Module':
      'apps/my-remote/src/app/remote-entry/entry.module.ts',
  },
  remotes: ['federated-is-odd'],
  shared: (libName, configuration) => {
    if (libName === 'is-odd') {
      return {
        singleton: true,
        strictVersion: true,
        requiredVersion: '0.0.1',
      };
    }
    return configuration;
  },
};

export default config;

This config will make sure that version 0.0.1 of the is-odd is used.

More Consistent Generator Paths

Similar to the adjustments we made in 16.8 for most of our project-creating generators, v17 brings updates to how component generators work. The goal of these updates is to give you more control over the name and file location of your components.

Towards this end, we've added a new --nameAndDirectoryFormat option, that you can set to either as-provided or derived.

When set to as-provided, the generator will use the name option for the name of your component, and the directory option to determine where on your file system to add the component. as-provided will be used by default if none is specified.

When set to derived, the generator will try to determine where to create your component based on the project option - which will mostly operate how component generators do now.

In addition, component generators now follow any given casing for component files. For example, let's say that we have an integrated monorepo with a react application called "my-app", and we want to add a "Home" component. With Nx 17, you can run the command:

> nx g component Home --directory=apps/my-app/src/app

And a Home.tsx file will be added in the apps/my-app/src/app directory.

You can now also build your directory path right into generator command. For example, the same "Home" component would be created via:

> nx g component apps/my-app/src/app/Home

Finally, generators will now factory in your current working directory, so you can also create this "Home" component via:

> cd apps/my-app/src/app
> nx g component Home

The NEW Nx AI ChatBot

We've added a new AI ChatBot to our docs site. You can access it now at https://nx.dev/ai-chat

This feature is still in beta, so please use the thumbs up/thumbs down buttons to provide feedback on whether the chat bot is accurate and helpful!

More Seamless Integration With Nx Cloud

After running the nx migrate command to upgrade to Nx 17 and using Nx Cloud, you may have observed the removal of nx-cloud from your dev dependencies. Don't worry - Nx Cloud is not only still around but thriving. Instead of having a standalone package, we've integrated the Nx Cloud communication layer directly into the nx package. This ensures a seamless connection whenever you opt-in and eliminates potential version misalignment concerns with our API endpoint.

`nx.json` Simplification

Our Nx Cloud updates come alongside some other configuration changes in your nx.json file and project configuration as well.

Specifically, we've added an optional nxCloudAccessToken to the nx.json file - as long as a token is provided here, we'll make sure that you take advantage of the currently deployed version of Nx Cloud when running commands with Nx.

We've also removed the need to specify cacheableOperations at the task-runner level. From now on, every target configured in your project.json can be specified as cacheable using the cache property.

// nx.json
{
    "targetDefaults": {
        "build": {
            "cache": true,
            ...
        }
    }
}

If you used the nx migrate command, all updates will be handled for you, using the targetDefaults in your nx.json file. More on the docs.

In general, we've been working hard at reducing and simplifying all the configuration that is required for your Nx workspaces. Checkout our latest guide on how to Reduce Repetitive Configuration for more, and stay tuned as we've got new efforts underway to make this simplification even more appealing!

Nx Repo Dog-Fooding Nx Workflows

At Nx Conf in New York City, we unvieled the next big step for Nx: Nx Workflows.

If you missed it, Simon Critchley walks you through in his Nx Conf talk:

Put simply, Nx Workflows represents Nx entering the CI provider arena, where Nx can now provide you with Cloud Computation to run your CI tasks. This creates the foundation for a whole new class of Nx Cloud features that we're very excited to be working on in the coming cycles.

The Nx repo itself is now "dog-fooding" this latest feature (dog-fooding refers to using our tool in our own projects, or "eating our own dog food"), and you can see how it's going now on our public Nx Cloud workspace.

Nx Workflows are still in the experimental phase, we're running pilots with our enterprise clients and we're excited to open this up for everyone soon!

Task Graphing Improvements

Task Caching in Nx is based on a set of "input" files that are calculated for a given task. You can specify certain files or patterns of files in your project.json for a specific task or in the targetDefaults of your nx.json to set the default file sets for your inputs.

In the past, there's been some difficulties in determining specifically which files were included and which weren't for a given task. This is where our latest update to the task graph comes in:

You can open this graph using the command:

> nx graph

And then selecting "Task" from the "Project"/"Task" graph dropdown in the top left. Clicking on a specific task now allows you to see a comprehensive list of all files that were factored in as inputs for this task:

`@nx/linter` Renamed to `@nx/eslint`

After running nx migrate, you may have noticed that the @nx/linter plugin was removed and replaced with @nx/eslint.

In Nx 17, we removed any remaining traces of tslint from our linter package, so this is mainly a simple rename to more accurately describe the package (and to remove any confusion that this package is intended to support linting for other languages/platforms).

New Experimental Feature: Nx Release

nx release is a new top level command on the Nx CLI which is designed to help you with versioning, changelog generation, and publishing of your projects:

nx release version - Determine and apply version updates to projects and their dependents
nx release changelog - Generate CHANGELOG.md files and optional Github releases based on git commits
nx release publish - Take the freshly versioned projects and publish them to a remote registry

nx release is still experiment and therefore subject to change, but the Nx repo itself is now using these commands to version itself, as well as generate changelogs, Github releases, and publish our packages to npm.

As we solidify this command, we intend to bring robust support for various versioning and publishing strategies, as well as built-in support for publishing packages or modules to a variety of languages, registries, and platforms.

For more checkout our API docs, and be sure to catch James Henry's announcement of this new command at Nx Conf:

Experimental: Nx Project Inference API v2

At Nx, we're OBSESSED with building a better, more robust experience for our developers. Towards this end, we're now in v2 of our Project Inference API.

This API is a way of extending the Nx project graph, which can be particularly helpful for extending Nx to support other languages, allowing Nx to determine where to find and draw boundaries around projects in your workspace. A great example is our very own Vue plugin.

Interestingly, v2 includes support for dynamic targets as well. This opens up exciting new doors to reducing configuration, and we hope to expand on this to better support our first-party plugins in the near future.

For most developers, the main thing you need to know is that plugins may now add additional targets that you won't see in your project.json file. To see your actual project configuration, you can now use the command:

nx show project <project_name>

For plugin authors, check out the v2 documentation to see how you can take advantage of the new API to deliver a better experience to your users.

20k Github Stars!!

Nx is SOOO CLOSE to 20,000 stars on github! If Nx has been helpful to you, please help us get there!

How to Update Nx

Nx is known to help you automatically migrate to the new version (including potentially breaking changes). To update simply run:

npx nx migrate latest

This will update your Nx workspace dependencies, configuration and code to the latest version. After updating your dependencies, run any necessary migrations.

npx nx migrate --run-migrations

Wrapping up

Learn more

More Nx Release Notes:

Nx 16.8 Release!!!

Zack DeRose — Wed, 06 Sep 2023 14:34:49 +0000

As always, the Nx Team has been hard at work, and we're here to launch our latest release: Nx 16.8! And it's absolutely bursting with new features. We'll go into all these in depth below, but be sure to check out our latest release video on YouTube!

If you have more questions - be sure to stop by our latest Nx Live to ask them there! You can sign up for a notification from the link below!

Nx Community News!

Before we jump into the features, be sure to get plugged in to get the most out of Nx in our NEW discord server!

Be sure to checkout our livestream with Jay Bell (Nx Champion, former Nx Community Slack admin, and current Nx Discord Admin) all about the news:

Nx is also coming up on 20k Github stars please help us get there!

NEW PROJECT GENERATOR BEHAVIOR: Project Creation Paths and Names in Nx Generators

Alright, getting into the newest updates from Nx, the biggest change is coming in the form of Nx project generators.

Originally, all Nx workspaces had a directory structure where applications were always held in an apps/ directory, while libraries were held in the libs/ directory.

Over the years, we found this to be much too rigid, so we made these locations more configurable. We added a workspaceLayout category to the nx.json file, where you could set appDir and libDir options to customize the names of these directories.

We also simplified the definition of Nx projects to be any directory that had a project.json file in it, allowing for the ability to nest projects in your filesytem and also forego app or lib directories altogether!

With Nx 16.8, we're introducing an all-new option in this workspaceLayout category: projectNameAndRootFormat where you can chose either the option to apply project names as-provided or derived.

If you don't set this option in your nx.json file, our generators will now prompt you as to how we should set:

the name of your project (as in the project's project.json file)
where to put the project in your filesystem

You can avoid the extra prompt above by setting the projectNameAndRootFormat in the workspaceLayout category of your nx.json file, or by providing it in in your generate command:

> nx g app my-app --projectNameAndRootFormat=as-provided

This will change some of the default behaviors of our generators and for new Nx workspaces. By default, new workspaces will be set to as-provided, so longtime Nx users might notice that if they create a new workspace and start generating apps or libs, that they will now get generated at the root of the workspace instead of inside the apps/ or libs/ directory like they used to.

To get the legacy behavior, be sure to change the projectNameAndRootFormat to derived and/or use the name option to set the name of the project, and the directory option to set the full path of the target directory for your new projects:

> nx g app --name=my-app --directory=apps/my-app

Packaging TypeScript Libraries - Secondary Entrypoints, ESM, CJS

Nx has always had first-class TypeScript support from the very beginning. You never really had to worry about Type Definition files being properly included or setting up TS support in the first place. But there are some aspects that can be tricky, like defining and properly exporting secondary entry points or packaging in multiple formats (ESM and CJS). That's why we did some research to help make it easier.

The package.json format supports an export field which is a modern alternative to the main property, allowing to have multiple such entry points.

{
  "exports": {
    "./package.json": "./package.json",
    ".": "./src/index.js",
    "./foo": "./src/foo.js",
    "./bar": "./src/bar.js"
  }
}

To make it easier to maintain these, we've added two new options to the @nx/js package: additionalEntryPoints and generateExportsField. Here's an example:

// packages/my-awesome-lib/project.json
{
  "name": "my-awesome-lib",
  "targets": {
    "build": {
      "executor": "@nx/js:tsc",
      ...
      "options": {
        "main": "packages/my-awesome-lib/src/index.ts",
        ...
        "additionalEntryPoints": ["packages/my-awesome-lib/src/foo.ts"],
        "generateExportsField": true
      },
    },
    ...
  }
}

When building the library, the @nx/js:tsc executor automatically adds the correct exports definition to the resulting package.json.

This makes it easy to maintain the exports field, something that becomes even more relevant if we want to add add multiple formats. By switching to the @nx/rollup:rollup executor, we can also add the format option and define esm and cjs as the target formats we want to have. Note we still keep the additionalEntryPoints and generateExportsField.

// packages/my-awesome-lib/project.json
{
  "name": "my-awesome-lib",
  "targets": {
    "build": {
      "executor": "@nx/rollup:rollup",
      ...
      "options": {
        "main": "packages/my-awesome-lib/src/index.ts",
        ...
        "format": ["esm", "cjs"],
        "additionalEntryPoints": ["packages/my-awesome-lib/src/foo.ts"],
        "generateExportsField": true
      },
    },
    ...
  }
}

After compiling our package using nx build my-awesome-lib we'll get the following output in our dist folder.

my-awesome-lib
└─ .
   ├─ README.md
   ├─ foo.cjs.d.ts
   ├─ foo.cjs.js
   ├─ foo.esm.js
   ├─ index.cjs.d.ts
   ├─ index.cjs.js
   ├─ index.esm.js
   ├─ package.json
   └─ src
      ├─ foo.d.ts
      ├─ index.d.ts
      └─ lib
         └─ my-awesome-lib.d.ts

And our package.json will look as follows:

{
  "name": "my-awesome-lib",
  "version": "0.0.1",
  ...
  "type": "commonjs",
  "main": "./index.cjs.js",
  "typings": "./src/index.d.ts",
  "exports": {
    "./package.json": "./package.json",
    ".": {
      "import": "./index.esm.js",
      "default": "./index.cjs.js"
    },
    "./foo": {
      "import": "./foo.esm.js",
      "default": "./foo.cjs.js"
    }
  },
  "module": "./index.esm.js"
}

High Performance TypeScript Compilation: Introducing Batch Mode & Rust-based Dependency Resolution

Speed is in our DNA! And TypeScript compilation can be slow which is mostly due to tsc being a costly operation. You feel this in particular in a monorepo where you have multiple projects that are being compiled independently, thus launching dozens of processes of the tsc compiler.

To help with this, the TypeScript team introduced Project References which performs incremental compilation by caching intermediate results. However this comes with some caveats you need to be aware of and it can be intense to maintain by hand on a large codebase.

We wanted to make it transparent though and not something the user needs to worry about. That's why we introduced "Batch Mode". Batch mode is still experimental, and you can enable it for any project using the @nx/js:tsc executor by adding the environment variable NX_BATCH_MODE=true:

> NX_BATCH_MODE=true nx run-many --target=build

When enabling batch mode, Nx leverages the underlying project graph to generate TypeScript project references behind the scenes for you, to fully leverage TS incremental building. The results are amazing. According to our benchmarks, batch mode has the potential to speed up Typescript compilation by up to 5x for large monorepos.

In addition to batch mode, the processing of Typescript dependencies is now using a faster and more accurate Rust implementation. This should be transparent to most users - aside from your monorepo becoming even faster!

NEW Nx PLUGIN: Playwright

A new Nx plugin has appeared!!

Nx now supports Playwright as an e2e option alongside our long-standing support for Cypress!

First off, this means we've added Playwright as an option when generating new frontend applications:

If you want to add playwright to an existing project in your workspace you can also do that now by installing the plugin (here using npm):

npm add -D @nx/playwright

Then running our new generator to add playwright to your project (here I'm adding it to my application called my-app):

nx g @nx/playwright:configuration --project=my-app

This will setup playwright for you, and add an e2e target to your project using playwright!

NEW INTEGRATION: Netlify's Improved Monorepo Experience

On Netlify's enterprise tier, approximately 46% of builds are monorepos, with the majority leveraging Nx and Lerna. Recognizing this trend, Netlify has focused on enhancing the setup and deployment experiences for monorepo projects. In particular they worked on an "automatic monorepo detection" feature. When you connect your project to GitHub, Netlify automatically detects if it's part of a monorepo, reads the relevant settings, and pre-configures your project. This eliminates the need for manual setup. This feature also extends to local development via the Netlify CLI.

Juri Strumpflohner from the Nx team sits down with Lukas Holzer from Netlify to discuss what monorepos are, when you might need them, their challenges and benefits, and the tooling support Nx provides. But it's not just talk; they also walk you through setting up a new Nx monorepo, adding Netlify Edge functions, and deploying it all to Netlify—both via the website and locally through the newly improved Netlify CLI.

If you prefer the blog post, check out "Elevating enterprise deployment: Introducing an enhanced monorepo experience on Netlify" on the Netlify blog.

NEW Nx CONSOLE FEATURE: Interactive Graph Functionality

If you're not familiar - Nx Console is our IDE enhancement for VsCode (1.4 million installations!!) and JetBrains Products (Intellij/WebStorm/etc - 52 thousand downloads!).

Nx Console provides a Graphical User Interface for running tasks and generating code for your Nx Monorepos, and it also provides the ability to view your project graph

and task graph

within your IDE!

As of our latest release, Nx Console has added the new feature of adding buttons inside the project graph to take you directly to the selected project in the project graph:

And gives you a "play button" to run any task within your task graph:

ENHANCEMENT: Storybook Support for Interaction Testing

Storybook 7 introduces new Interaction Testing to their platform!

The Nx Storybook plugin has now been enhanced with a new interactionTests option on the storybook-configuration generator, that will automate setting up these interaction tests for you when you use Nx to generate stories for your components!

You can checkout everything about Storybook Interaction tests and our Nx support for it in this video:

Nx has always provided similar functionality via our Storybook + Cypress integrations, where you can setup cypress tests to test your storybook showcases, and while you can use interaction testing to replace this integration, we will continue to support our Storybook + Cypress integrations going forward!

NEW GENERATOR: convert-to-monorepo

Towards the start of the year, we added support for Nx standalone applications. These were designed as a way of using Nx features in a way where you didn't need to opt into a monorepo setup.

Ever since we introduced these, we've had requests from the community to add a generator to convert your standalone workspace to a monorepo setup - to support repos that grew to emcompass more than just the 1 application.

This is where our new convert-to-monorepo generator comes into play!

> nx g convert-to-monorepo

This will identify all library projects in currently in your repo and place them in the libs/ directory that you might expect of a typical Nx monorepo. It will also hoist your application project from the root of your workspace into the apps/ directory.

When all is said and done, you should be able to now add additional applications to your repo now!

DOCS ENHANCEMENT: Third-Party Plugin Quality Indicators

One of the great things about Nx is the extensibility, and the wide range of plugins that are available for supporting languages, frameworks, and tools that the core Nx team does not directly support.

Our docs site has hosted a registry of these plugins for awhile now, but we've recently added npm downloads, github stars, release dates, and compatible Nx versions to this registry:

We expect that these will be valuable signals to users as to the quality of the plugin.

We've also added the ability to sort the registry by these metrics as a way of surfacing the higher quality plugins to the top!

Go check it out now live on our docs site!

DOCS ENHANCEMENT: Redesigned Intro & Examples

Our mission to improve Nx docs continues: this edition with some major updates to our Docs intro page.

We improved the messaging around Nx and more prominently emphasizing the core features that distinguish Nx from other tools out there. We also linked a new "What is Nx" video. You should check it out 🐐

The core part of the intro page now has a dedicated section for "Learning Nx", surfacing some of our Nx, Nx Cloud and Monorepo videos as well as our in-depth tutorial about monorepos and single-project Nx workspaces. And we already have more in the works, so stay tuned.

We're also proud of all the new examples we've added in the last months. We have a brand new Nx Recipe repo with a variety of example projects that showcase Nx in combination with different technologies, even outside the JS ecosystem (e.g. with Rust, Go and .Net).

Go pick the ones you're most interested in!

You can find all of the examples and more on our "Showcase" section: https://nx.dev/showcase.

NEW GENERATOR: ESLint Flat Config

ESLint has announced a new config system - nicknamed "flat config" - whose intent is to be be familiar and much simpler than the current config system. You can read more about this in their blog post.

As part of our continued support for ESLint, we've introduced a new generator to convert your Nx monorepo to this new system:

> nx g convert-to-flat-config

Flat config is still experimental, so you can use this as a way of easily previewing the new config system now. Just be sure not to mix the original configuration with this new configuration system!

New Nx Cloud Overview Video

We've been working hard on our premium product: Nx Cloud, and part of that has been this awesome video from our own Rares Matei on what exactly Nx Cloud is!

Be sure to checkout the Nx Cloud landing site for more details on all the additional features you unlock with the power of the cloud!

Nx Conf Coming Up

Last but definitely not least, Nx Conf 2023 is fast approaching! We'll be coming to you live from New York City on September 26!

Be sure to register to attend online FOR FREE and be sure to checkout our lineup of talks and speakers!

Wrap Up

That's all for now folks! We're just starting up a new iteration of development on Nx, so be sure to subscribe to our YouTube channel to get updates when new features land! Until next time, KEEP WORKING HARD!

Learn more

More Nx Release Notes:

Nx 16.5 Release!!

Zack DeRose — Thu, 06 Jul 2023 14:26:25 +0000

We have launched SO MANY features since our last release blog on Nx 16.0, so we're covering the major features in this blog!

Be sure to mark your calendars for our Nx 16.5 livestream as well! We'll highlight the features you see here AND field any questions live! Follow the link to schedule a notification for when we go live:

Targetting Tasks By Tags

Our first major feature actually comes to us from the community. Nx has supported a tags property in your project.json file for awhile now - and it's main purpose has been to be used in conjuncture with the Nx Module Boundary lint rule to define which projects in your Nx workspace can depend on what - for example, you don't want your frontend applications to depend on any backend-specific code.

With this new feature, you can add the --tag option to the nx affected and nx run-many commands to specify to Nx to only run commands for projects that match the given tags.

NextJS 13 Support

React Server Components, the and the new NextJS app router are here, and Nx is here to support them. We've added support for the latest versions of Next - complete with generators and executors. We've also made sure that our withNx NextJS plugin, which allows you to import from your other projects in your workspace while still working with the NextJS build scripts, works both for workspaces using our executors in an Integrated Monorepo approach, as well as for those using a Package-Based approach that are simply using the next dev command directly to start their dev server.

There's also built-in support for the new turbopack builder option via the --turbo command, for example: nx serve webapp --turbo

We've also launched a new preset for npx create-nx-workpace for a standalone NextJS app. Checkout it out using the command: npx create-nx-workspace@latest --preset=nextjs-standalone or use the interactive prompts to find it:

We've added a couple videos specifically on Next development in an Nx workspace in the past month, so if you're looking for more on Next, be sure to check them out!

New Nx Recipes!!!

Did you know that we maintain a set of Nx workspaces designed to serve as examples for different Nx Workspaces?

We've recently added examples repos for:

fastify + mongo
fastify + postgres
fastify + redis
nextjs + trpc
remix
serverless + fastify + planetscale

Go check it out at https://github.com/nrwl/nx-recipes and let us know in the comments if there are more recipes you'd like to see or if you want to see videos made from any of the existing recipes!

Angular 16 Support And Migrations

Angular is continuing their pattern of releasing new and exciting features - and in Nx 16.1, we added support for Angular 16, including updates to our NgRx generators and cypress support.

As usual, we provide migrations to the most recent Angular version to cover your codebase for any breaking changes going to Angular 16.

And in case you missed it, Nx is no longer tied to your Angular version - the most recent version of Nx will now always support all currently LTS versions of Angular, meaning you DON'T have to upgrade your Angular version in order to get all these latest Nx Features. Be sure to use the --interactive flag to take advantage of this feature: nx migrate latest --interactive. You can find more details in our docs for choosing optional packages to apply.

New `verdaccio` support!

The @nx/js package now includes a new setup-verdaccio generator as well as a verdaccio executor!

Running nx g setup-verdaccio will now add a new local-registry target to your workspace, that will use the new verdaccio executor.

To start your local registry, run the command nx local-registry in one terminal, and then you can publish via commands like npm publish as you normally would, but rather than publish packages to the npm registry, this will only publish those packages to your locally-running registry!

While the local-registry process is running, you will also be able to install packages published to your local registry as well.

These tools should help in particular with local testing of publishing packages to help support both manual and automated testing!

Create your own CLI with Nx

The use of command-line interfaces (CLIs) to create new workspaces is common in various technologies. React has one, so does Angular, Vue, Vite and many more. Maintaining a good CLI experience can be tedious though, especially because framework authors would rather want to focus on the library or framework itself.

For a while now, Nx plugin authors had the possibility to create a so-called "preset" to control the entire Nx workspace structure. Once published it can be invoked by using the --preset flag:npx create-nx-workspace myapp --preset=@my/plugin. Qwik-Nx is an example of that.

However, many authors would rather want to have a more "branded" experience. Like being able to invoke the previous example as follows:

npx create-qwik-nx myapp

To fulfill this need, in 16.5 we ship with a new create-package generator that allows you to add and ship such "CLI package" with your Nx plugin.

You can either create a new Nx plugin workspace immediately with a CLI package using:

npx create-nx-plugin my-own-cli --create-package-name=create-my-own-cli-app

Or alternatively add it to an existing Nx plugin workspace using:

nx g @nx/plugin:create-package <cli name> --project=<existing plugin name> --e2eProject e2e

New `externalDependencies` Input Type

Nx now supports a new input type: externalDependencies to add to the existing input types: filesets, runtime inputs, and env variables.

By default, Nx will take the defensive stance of assuming that all packages will affect your commands, meaning all external dependencies are taken into account when hashing your task's dependencies.

The new externalDependencies input type allows you to specify a specific set of external dependencies for a given command, so you can configure your tasks to more accurately reflect their inputs.

For example, if you have a publish-package target that is using a command of lerna publish for your publishing, you can specify that the only external dependency for that specific input is lerna:

{
  "name": "mylib",
  // ...
  "targets": {
    "publish-package": {
      "command": "lerna publish",
      "inputs": [{ "externalDependencies": ["lerna"] }]
    }
  }
}

This way you are free to change other dependencies that don't affect this task without invalidating your cached run of the task.

New `@nx/dependency-checks` EsLint Rule

We've added a new @nx/dependency-checks lint rule to help with detecting any issues when specifying dependencies for your packages.

This rule will analyze your source code to determine any dependencies you are using in this specific package, and will catch any missing dependencies, mismatched versions, and unused dependencies in your project's package.json file.

Even better, this rule supports the --fix option to automatically fix any issues that are found - making it a great tool for automating your dependencies.

After migrating your Nx workspace, you should have access to this lint rule. To turn it on, you'll need to adjust the lint targets in your project.json files to include your package.json files like so:

{
  "name": "webapp",
  // ...
  "targets": {
    // ...
    "lint": {
      "executor": "@nx/linter:eslint",
      "outputs": [
        "{options.outputFile}"
      ],
      "options": {
        "lintFilePatterns": [
          "apps/webapp/**/*.{ts,tsx,js,jsx}",
          "apps/webapp/package.json" // here!
        ]
      }
    }
  }
}

Then in your root .eslintrc.json file you'll want to turn the rule on for your json files:

{
  "root": true,
  "ignorePatterns": ["**/*"],
  "plugins": ["@nx"],
  "overrides": [
    // ...
    {
      "files": ["*.json"],
      "parser": "jsonc-eslint-parser",
      "rules": {
         "@nx/dependency-checks": "error"
      }
    }
  ]
}

Now you should be able to run the linter via nx run-many --target=lint to catch any errors across any of your packages, and you can nx run-many --target=lint --fix to automatically fix all errors as well.

Nx Goes Brrrrrr

Nx has continued to get faster!

Our biggest speed increase has come from moving our task hashing into the Nx Daemon. A daemon process refers to a process that runs continuously in the background.

Because the daemon persists between command runs, we are able to have more of the work that goes into hashing a task cached, which we added in Nx 16.3!

In Nx 16.4 we also moved to a rust-based watcher to further improve performance. We had already began the migration of some of the more performance-intensive computation of Nx to Rust in prior version, but we're excited to bring more of the core of Nx into Rust and see more of these performance gains!

Since our last benchmarking of Nx in October of last year where we clocked Nx at 276.2ms per command, these speed boosts have now gotten us down to 149.3ms, nearly doubling our speed!!

You can see our results and the details of the benchmark - and even run the benchmarks for yourself in this repo.

Nx Console Revamped

Nx Console got a new coat of paint in both the VsCode and JetBrains (IntelliJ/Webstorm) IDEs!

As part of the redesign, we also moved our webviews to the Lit framework - checkout all the latest updates in this video:

Nx Changelog Launched

Last but CERTAINLY not least, we've launched a new changelog to our docs site!

This changelog includes links to all the release notes for all major and minor versions, as well as links to patch versions. We made sure to also include any deprecations or breaking changes brought about by each version as well.

Wrap Up

Learn more

More Nx Release Notes:

What's New With Lerna 6.5?

Zack DeRose — Wed, 22 Feb 2023 17:01:23 +0000

In case you missed it, Lerna version 6.5 recently launched. We'll catch you up on the latest Lerna news and newest features.

Lerna: Brought to You by Nx
Still On Lerna 4?
Idempotency Added to the lerna publish from-git Command
lerna run Can Run Multiple Scripts In a Single Command
New --include-private Option Added To lerna publish
Massive Refactor
Getting Started With Lerna From The Lerna Team
The Future of Lerna

Lerna: Brought to You by Nx

In case you missed it, Lerna, the OG JavaScript monorepo tool, went largely unmaintained for a while, starting around 2020. Then, it officially declared itself to be unmaintained in April of 2022, only for Nx to step in to take over maintenance of the project in May of 2022!

You can find a more detailed account of Lerna's "Maintainance Odyssey" in this article.

Since Nx took over in Lerna 4, we've added a brand new site to refresh the Lerna Docs:

The top of our priorities for Lerna 5 was to resolve all vulnerabilities and outdated dependencies facing Lerna. We went on to make Lerna faster by allowing users to opt into Nx's task caching inside of Lerna with the new lerna add-caching command, and add support for distributed caching to share task results amongst your organization in Lerna with Nx Cloud.

We were proud to go on to launch Lerna 6 last October, where we began focusing on further improving Lerna's feature set - focusing specifically on its unique strengths: versioning and publishing.

Still on Lerna 4?

Here's how to upgrade to the latest and greatest.

We've also started an initiative to assist Open Source projects in getting the most out of Lerna. Projects that use Lerna can now request free consulting to learn how to take advantage of Lerna's newest features.

We've just started this initiative and have already been able to help Sentry get optimized with task caching and task pipeline optimizations for their workspace!

This initiative complements our free tier of unlimited Nx Cloud for any Open Source project.

If you're interested in optimizing your Open Source project to take advantage of the latest Lerna features, reach out to us on Twitter!

Now let's jump into the newest Lerna 6.5 features!

Idempotency Added to the `lerna publish from-git` Command

"Idempotent" is a word used to describe an operation you can perform any number of times, and the resulting state is the same as if you had only run the operation once.

The lerna publish command is a beneficial tool for quickly publishing multiple packages from your workspace:

Running lerna publish by itself will version and publish all packages in the workspace since your latest release
Running lerna publish from-git will publish all projects tagged in the latest commit
Running lerna publish from-package will publish all projects whose version does not yet exist in the target registry based on the version listed in their package.json file.

As we can see, lerna publish from-package is already idempotent (since it only publishes packages whose version doesn't exist, any run past the first will not adjust the state of the registry).

With 6.5, we've added the same idempotency to lerna publish from-git. This update is handy for recovering from a situation where some of your packages failed to publish initially (maybe due to a networking issue).

For more information, check out the PR

`lerna run` Can Run Multiple Scripts In a Single Command

For 6.5, we've added the ability to run multiple scripts in a single lerna run command! Checkout this quick video demonstrating this below:

Learn more here.

New `--include-private` Option Added To `lerna publish`

Npm supports a "private": true configuration as a way of preventing the publication of a library that is private.

> lerna publish from-git --include-private my-private-package

Running lerna publish with this new --include-private option (as above) will strip this "private": true configuration from the package.json of the packages listed in the command.

This new option is beneficial for the use case where you'd like to run e2e for a package that will eventually be public but is currently private to prevent getting published too soon.

You can find more information on this change [here]((https://github.com/lerna/lerna/pull/3503).

Massive Refactor

Unlike the other updates mentioned for 6.5, this update does not affect Lerna's public API, but as you can see from the numbers, this was quite an undertaking:

The result is a significant improvement to the Typescript support for Lerna's internals and a substantial simplification of the codebase. This investment will make Lerna significantly more approachable to other would-be contributors!

Find more on this change here.

Getting Started With Lerna From The Lerna Team

We recently ran a live stream with James Henry and Austin Fahsl from our Lerna team to show how to get started with Lerna, all the way through to versioning and publishing our packages to npm!

Check out the recap of this session above, and check out the repo from our session on GitHub.

The Future of Lerna

Looking to the future, we are targeting Q2 of 2023 for Lerna v7 (including a --dry-run option for both lerna version and lerna publish commands - you can catch a sneak-peak of this in James' talk from Nx Conf 2022 below!)

You can find a roadmap for all the features we plan to add in Lerna 7 on Github!

Lerna More!

If you liked this, click the 👏 and make sure to follow Lerna and Zack on Twitter for more!

Create Your Own tRPC Stack!

Zack DeRose — Thu, 26 Jan 2023 15:38:55 +0000

The Evolution of Awesome Tec Stacks
Building Our Concrete Example Stack
Creating a Code Generation Script
Using that Script
Defining a Task Executor
Using that Executor
Putting it All Together

The Evolution of Awesome Tech Stacks

LAMP - the OG Tech Stack

Arguably the first tech stack that was called as such was the LAMP stack, which was traced back to a 1998 issue of the German computing magazine: Computertechnik.

LAMP here was an acronym that stood for:

L - Linux (the operating system)
A - Apache (the HTTP server)
M - MySql, or sometimes MariaDB (the database)
P - PHP / Perl / Python (the programing language)

There was something magical about this idea of a tech stack. This bundle of free-to-use, open-sourced, and relatively interchangeable software was a viable (maybe even preferable!) alternative to the many paid, proprietary, and "locking-in" packages that were popular at the time, and gave rise to some killer applications - like WordPress!

An interesting essential part of this idea of "a stack" was the concept of interchangeable pieces - note how the "P" in particular could stand for 3 VERY different programming languages, and a close cousin to LAMP was WAMP which exchanged Linux for Windows.

First-Gen JS stacks: MEAN/MERN

As we move on from the early 2000s to the 2010s - the JavaScript ecosystem, in particular, started growing in popularity, spurred by the creation of Node.js in 2009, which was accompanied by a JS package manager: npm.

With this popularity came the rise of the first all-JS stack - the MEAN stack, which stood for:

M - Mongo - a JSON (JavaScript Object Notation) based Database
E - Express - a Web Framework for Node.js
A - AngularJS - a frontend JS web framework
N - NodeJS - a backend Javascript runtime environment

A later evolution of this stack was the MERN stack that exchanged React with AngularJS as the frontend web framework.

While this first generation of JavaScript stacks made for a recognizable and searchable term for describing a typical setup, there was little in the way of standardizing this stack.

Current-Gen JS stacks: T3, tRPC, Tanstack

Stepping into the current generation of JavaScript in the 2020s - and while we're still early in this generation of JS stacks, a clear trend can be seen in the form of a focus on tooling and the developer experience.

A stand-outs from this generation of the JS stack is the t3 stack, which is an opinionated and evolving collection of the following technologies:

A marked difference we can see from the MEAN/MERN stacks of the previous generation is that while MEAN/MERN operated mainly as a convenient search term to give needed context to looking up problems, the t3 stack is much more formalized, including a website, a community of support on discord and Twitter, and importantly: a CLI tool to create a working starter application.

This CLI is exciting as it is a way of standardizing and versioning the stack over time. If the community identifies a specific tool or enhancement that it can canonically bring into the stack, the "generative" nature of this tool gives developers a working starting point. Still, they can work from there to bring in their tools to further customize their stack.

The impact on the developer, however, is the ultimate goal here, as the t3 tenants of ruthless practicality:

Developers should be focused on solving their problems.

Using create-t3-app clearly demonstrates this: after answering a short series of questions, the developer has an operational full-stack application that they can see in action with one simple command to start up the project locally.

Other popular packages in this generation include the tanstack series of packages:

and tRPC:

While not fully-fledged stacks the way t3 is, these projects are likely successful mainly due to the attention given to tooling - particularly type safety. This positions them as obvious building blocks for other stacks to incorporate.

The Next Step: Nx

We think that Nx is uniquely positioned to be an essential tool in this current generation of JS stacks.

Nx is built on a series of core tooling features that benefit most repositories (especially monorepos), including:

code generation mechanisms that allow you to quickly scaffold an entire project structure or add features such as Tailwind to an existing project
a way of visualizing how sections of your code are connected via the project graph
mechanisms to ensure speed while just running commands via the nx affected command and task caching
a mechanism for defining how commands in your workspace depend on each other via task pipeline configuration
a way to easily extend tooling via a plugin mechanism

While all the above features help make things faster for any project, Nx's pluggability is particularly interesting for our discussion about stacks.

At Nx, we maintain many packages that are designed to be used as building blocks for developers to create their own stacks.

Framework-based packages like our React, Angular, Nest, and Node packages offer developers a way of assembling their own stack based on their preferences. For instance, adding a react application to your repository with react-router-dom installed and pre-configured to match their getting started guide is as simple as running the command:



npx nx g @nrwl/react:app my-app --routing

Then to complement this frontend application with a backend written with NestJS, you run the command:



npx nx g @nrwl/nest:app api --frontendProject=my-app

This will not only create a backend Nest application for you but also configure your React application to create a proxy for your API requests to this Nest application. This otherwise tedious task will often waste developer time.

Other tooling-based packages like our Vite, Webpack, and Rollup packages offer support for build, test, and Linting level tools allowing easy migration to the tool that best suits your preferences, with the added benefit of allowing for painless transitions from using webpack to vite or vice-versa.

In addition to the official Nx packages comes a registry of community-supported plugins that support other frameworks, tools, and languages that we don't have official support for:

These community-supplied plugins offer more building blocks to create your desired stack.

And our Nx plugin package provides an API for creating your own building blocks and composing other building blocks into a pre-defined stack - just like the t3 stack!

Building Our Concrete Example Stack

With this context in mind, let's dive into creating our concrete stack, specifically:

React as our frontend Application
Tailwind for styling on our frontend app
Express for our backend application
Vite and Vitest for frontend bundling and testing
Esbuild for backend building
tRPC for building our API and full-stack type safety across both apps

We can build upon Nx's official plugins for the first five items and write our generators for the tRPC pieces based on their "Getting Started" documentation.

The end goal is to have a codified and versioned stack that will allow us to create a full-stack application in one command and then be able to serve the entire working stack in a single command.

Here's a teaser of how this will all look when we're finished:

And you can see and clone the workspace we'll create here.

Creating our Plugin

Before starting this section, create an initial workspace using the command create-nx-workspace@latest nx-trpc-example --preset=empty, and then install our dependencies by running the commands:



> yarn add -D @nrwl/react @nrwl/vite @nrwl/node @nrwl/nx-plugin @nrwl/esbuild
> yarn add @trpc/client @trpc/server
> npx nx g @nrwl/react:init
> npx nx g @nrwl/vite:init
> npx nx g @nrwl/node:init
> npx nx g @nrwl/esbuild:init

We'll need the above to install manually, but in the sequel to this guide, we'll create our own init generator script so that any consumers of our package won't need to run this step manually!

Next, to create our plugin, we'll run the command:



npx nx g @nrwl/nx-plugin:plugin plugin --minimal

This will use the plugin generator of the @nrwl/plugin package to create a plugin for our workspace named: plugin. We're also using the --minimal flag here, so the plugin is empty initially.

Once this command is run, we'll see the new project in: libs/plugin

The scaffolding of this project is separated into executors and generators - where executors are an Nx mechanism to define a task (like building an app or starting a web server for local development) simplified to a simple Typescript function, and generators are an Nx mechanism for code generation simplified to a simple Typescript function. We'll see these more in the following sections, starting with generators:

Create a Full-Stack Application Generator

Nx's Generator API simplifies any code-gen script to a simple function. The @nrwl/devkit package goes on to provide utility functions to make the more burdensome things about code-generation scripts more manageable and tolerable!

When we consider at a high level what our code generation should look like, we can separate it into these four steps:

generate a front-end application
generate a corresponding backend application
generate a tRPC server library that is already imported into our backend application
generate a tRPC client library that is already imported by our frontend application

Because first-party Nx generators from the official Nx packages are functions as well, we can create a corresponding function for all four of the points above and then call those Nx generators in sequence to implement our generator.

Now that we have our roadmap for the generator, we also need to consider how we'll want to parameterize our generator. The Nx CLI uses a schema-based approach to defining these options so that when another developer uses our code generation script, they can pass any of these options to the CLI, which will be passed as parameters to our generator function we'll write next.

Given this, let's limit our options for now to the following:

the name of the full-stack application. This will be required, and we'll use this name to inform how we'll name the four projects to generate for this app: (${name}-web, ${name}-server, ${name}-trpc-server and ${name}-trpc-client).
the port for the backend and the frontend applications to run on. These won't be required - and we'll default them to 3000 and 3333, respectively.

With these in mind, we'll create our application generator using the command:



npx nx g @nrwl/nx-plugin:generator app --project=plugin

Which will use the generator generator of the @nrwl/nx-plugin package to create our new generator named "app" located at libs/plugin/src/generators/app.

Once the command is run, you should see new files located in libs/plugin/src/generators/app, and metadata for this new app generator in libs/plugin/generators.json.

The file: libs/plugin/generators.json will define all the generators contained in our plugin to Nx - but we won't need to touch this file as the generator already took care of any changes required.

As for the other files created, we'll start with libs/plugin/src/generators/app/schema.d.ts:



export interface AppGeneratorSchema {
  name: string;
  frontendPort?: number;
  backendPort?: number;
}

This interface matches the parameterization of the generator we want to support mentioned above. We'll also want to adjust the libs/plugin/src/generators/app/schema.json file to match this as well:

This schema file will inform all Nx tools (including the CLI validation, the CLI --help option, and the Nx Console tool) what options are available for this generator.

Notice that the name property is the only required parameter, and lines 11-14 above tell us that it is the first non-named option in our command's argument vector (or argv).



npx nx generate @nx-trpc-example/plugin:app test

So, for example, the above command would create our new application with the name: "test", and frontendPort and backendPort would use their default values. We can add specific values for these options by providing it to our command like so:



npx nx generate @acme-dev/plugin:app test --frontendPort=3001

Next, we can remove the libs/plugin/src/generators/app/files directory, as we won't use that mechanism for this generator.

The @nrwl/nx-plugin creates this files directory to support templating with Nx generators via the writeFiles() function created in the generator.ts file.
The generators we're creating in this article are relatively simple, so we'll use string literals when changing a file's contents.

The implementation of our generator will be written in the libs/plugin/src/generators/app/generator.ts file.

The mental model here is we will implement these steps in the following function:



import { Tree } from '@nrwl/devkit';
import { AppGeneratorSchema } from './schema';

export default async function (tree: Tree, options: AppGeneratorSchema) {
    // ... implementation to go here!
}

Our tree parameter represents a virtual file system of the current state of our repo. We'll use this Tree API and utility functions from the @nrwl/devkit package to mutate that tree object until it matches the desired state.

You can find the entire contents of that file here, and you can see our original high-level four-step approach to the generator:



export default async function (tree: Tree, options: AppGeneratorSchema) {
  // ...
  await createReactApplication(tree, optionsWithDefaults, webAppName);
  await createNodeApplication(
    tree,
    optionsWithDefaults,
    serverName,
    webAppName
  );
  await createTrpcServerLibrary(tree, optionsWithDefaults, trpcServerName);
  await createTrpcClientLibrary(tree, optionsWithDefaults, trpcClientName);
}

That's most of our high-level view of what a generator is and how to create it - you can skip ahead to using the generator, but otherwise - let's dive in deeper by walking through the implementation of each of these functions next:

0. Adding Default Options and Project Names

As a preliminary step, we'll define the default values for the optional parameters (lines 4-7 below). Then we'll create our optionsWithDefaults by spreading the defaultPorts with the options coming in from the command. This has the effect of overwriting the defaultPorts if the user provides their own, but otherwise, the defaults are used.

We'll also import the names function from the @nrwl/devkit package so that we can kebab-case the name provided by the user. For example, if the user-provided name is "helloWorld", the fileName of this will be "hello-world". We'll use this to get a name of our four projects in kebab-case to use later on in the generator.

Other cases supported by the names() function include:

pascal case

console.log(names('helloWorld').className); // HelloWorld

camel case:

console.log(names('helloWorld').propertyName); // helloWorld

screaming snake case:

console.log(names('helloWorld').constantName); // HELLO_WORLD

untouched:

console.log(names('uNtOuChEd').name); // uNtOuChEd

We'll use some of these later on.

1. Create Our React App

For this step, we'll create a function called createReactApplication():



async function createReactApplication(
  tree: Tree,
  options: AppGeneratorSchema,
  webAppName: string
) {
  // implementation will go here!!
}

Our first step in this function will be to use Nx's first-party React app generator. We can import it like so:



import { applicationGenerator as reactAppGenerator } from '@nrwl/react';

Notice we're renaming applicationGenerator to reactAppGenerator because we'll be importing other applicationGenerators in future steps!

When it comes time to call the function, we'll call it like so:

Note that Typescript Intellisense can help us with the required and optional options in lines 7-13 above!

The options we've provided will set up the application with vite and vitest, and we'll give it the appropriate port. Note that if we ever wanted to adjust our bundler to webpack in the future, making that change is as simple as changing the bundler option here!

Also note that since the reactAppGenerator we imported is an async function, we want to make sure we await it! Without awaiting, we could get a race condition that would give us interesting and undesired results.

It may be a good idea to test our generator out incrementally. For example, at this point, we can confirm that our React application is generated as expected.
To do this, I recommend using git to commit all changes you've made so far right before running the generator:
npx nx g @nx-trpc-example/plugin:app test
You can check that things look good and then reset to discard all the results so you can continue building the generator:
git add . && git reset --hard HEAD
Another tool you have for previewing changes from your generator is the --dry-run option. This will list all files that would have been created, updated, or deleted by the generator without actually running them:
npx nx g @nx-trpx-example/plugin:app test --dry-run

The Nx React plugin includes a generator for adding Tailwind to a React application, so we'll import it and call it next:



import { setupTailwindGenerator } from '@nrwl/react';

// ...

async function createReactApplication(
  tree: Tree,
  options: AppGeneratorSchema,
  webAppName: string
) {
  await reactAppGenerator(tree, {
    name: webAppName,
    linter: Linter.EsLint,
    style: 'css',
    e2eTestRunner: 'none',
    unitTestRunner: 'vitest',
    bundler: 'vite',
    devServerPort: optionsWithDefaults.frontendPort,
  });
  await setupTailwindGenerator(tree, { project: webAppName });
  // rest of implementation to come here!!
}

Our next step is to add the boilerplate to import the tRPC client (that we'll generate in step 4!) to our new app.tsx file of our React application:



import { getWorkspaceLayout, names, Tree } from '@nrwl/devkit';

// ...

function createAppTsxBoilerPlate(tree: Tree, name: string) {
  const { className, fileName } = names(name);
  const { npmScope } = getWorkspaceLayout(tree);

  const appTsxBoilerPlate = `import { create${className}TrpcClient } from '@${npmScope}/${fileName}-trpc-client';
import { useEffect, useState } from 'react';

export function App() {
  const [welcomeMessage, setWelcomeMessage] = useState('');
  useEffect(() => {
    create${className}TrpcClient()
      .welcomeMessage.query()
      .then(({ welcomeMessage }) => setWelcomeMessage(welcomeMessage));
  }, []);
  return (
    <h1 className="text-2xl">{welcomeMessage}</h1>
  );
}

export default App;
`;
  tree.write(`apps/${fileName}-web/src/app/app.tsx`, appTsxBoilerPlate);
}

Notice that we're anticipating our import statement to match the trpc-client library that we'll create in Step 4 and using the client to query for a welcomeMessage that we'll define in our trpc-server library in Step 3.

Also, note that we use the write method of the Tree api here to write a file to our virtual file system.

Other methods on the Tree api include:

read()

exists()

delete()

rename()

isFile()

children()

listChanges()

changePermissions()

The @nrwl/devkit also includes a list of utility functions to manipulate our tree more deftly. You can find the whole list here

We're also using the getWorkspaceLayout function of the devkit so that we can match the correct import scope that Nx uses by default for Typescript imports.

Our last step for now on the React application is to adjust the default port to match the port provided by the user:

We're also using the updateJson utility function from the @nrwl/devkit to update our React app's project.json file to change the options.port of our serve target to the provided port (line 15 above).

With these pieces now created, we can finish our createReactApplication function now:



async function createReactApplication(
  tree: Tree,
  options: AppGeneratorSchema,
  webAppName: string
) {
  await reactAppGenerator(tree, {
    name: webAppName,
    linter: Linter.EsLint,
    style: 'css',
    e2eTestRunner: 'none',
    unitTestRunner: 'vitest',
    bundler: 'vite',
    devServerPort: options.frontendPort,
  });
  await setupTailwindGenerator(tree, { project: webAppName });
  createAppTsxBoilerPlate(tree, options.name);
  adjustDefaultDevPort(tree, options);
}

2. Create Our Backend Node App

We'll take a similar approach to create our Node application, starting by importing the @nrwl/node application generator:

Notice that we are adding a frontendProject to the options (line 19 above). This will add a proxy configuration to our React app's development server - allowing us to side-step CORS complications in our local environment.

We'll also adjust the contents of the main.ts file that is already created after the Promise returned by this nodeAppGenerator() resolves:



function createServerBoilerPlate(
  tree: Tree,
  name: string,
  backendPort: number
) {
  const { fileName } = names(name);
  const { npmScope } = getWorkspaceLayout(tree);
  const serverBoilerPlate = `/**
 * This is not a production server yet!
 * This is only a minimal backend to get started.
 */

import express from 'express';
import * as trpcExpress from '@trpc/server/adapters/express';
import { trpcRouter } from '@${npmScope}/${fileName}-trpc-server';
import { environment } from './environments/environment';

const app = express();

app.use('/api', trpcExpress.createExpressMiddleware({ router: trpcRouter }));

const port = environment.port;
const server = app.listen(port, () => {
  console.log(\`Listening at http://localhost:\${port}/api\`);
});
server.on('error', console.error);

`;
  tree.write(`apps/${name}-server/src/main.ts`, serverBoilerPlate);
  tree.write(
    `apps/${name}-server/src/environments/environment.ts`,
    `export const environment = {
  production: false,
  port: ${backendPort},
};
`
  );
}

Note that we're anticipating an import of the trpcRouter that we'll generate in step 3, and we're also using the backendPort from our options to write this port to the environment.ts file, and thereby configure our backend port.

Putting these pieces together, our resulting function looks like so:



async function createNodeApplication(
  tree: Tree,
  options: AppGeneratorSchema,
  serverName: string,
  webAppName: string
) {
  await nodeAppGenerator(tree, {
    name: serverName,
    js: false,
    linter: Linter.EsLint,
    unitTestRunner: 'none',
    pascalCaseFiles: false,
    skipFormat: true,
    skipPackageJson: false,
    frontendProject: webAppName,
  });
  createServerBoilerPlate(tree, options.name, options.backendPort);
}

3. Create a Library for Our tRPC Server

We'll use a similar approach with the @nrwl/js library generator for this lib:



import { libraryGenerator as jsLibGenerator } from '@nrwl/js';

// ...

async function createTrpcServerLibrary(
  tree: Tree,
  options: AppGeneratorSchema,
  trpcServerName: string
) {
  await jsLibGenerator(tree, {
    name: trpcServerName,
    bundler: 'vite',
    unitTestRunner: 'vitest',
  });
  // ... rest of the implementation to go here!
}

After the library is generated, we'll add the boilerplate to export our trpc from the index.ts file created in this library:



function createTrpcServerBoilerPlate(tree: Tree, name: string) {
  const { className } = names(name);
  const trpcServerBoilerPlate = `import { initTRPC } from '@trpc/server';

const t = initTRPC.create();

export const trpcRouter = t.router({
  welcomeMessage: t.procedure.query((req) => ({
    welcomeMessage: \`Welcome to ${name}!\`,
  })),
});

export type ${className}TrpcRouter = typeof trpcRouter;
`;
  tree.write(`libs/${name}-trpc-server/src/index.ts`, trpcServerBoilerPlate);
}

Note that this creates the welcomeMessage query that we call from app.tsx back in step 1!

After calling these functions, we'll make a few more adjustments to clean up this library:

remove the ${libraryName}.ts file that was generated
remove the ${libraryName}.spec.ts file that was generated
add a sourceRoot property to our project.json file

These operations are simple enough that we can inline them in our createTrpcServerLibrary:



async function createTrpcServerLibrary(
  tree: Tree,
  options: AppGeneratorSchema,
  trpcServerName: string
) {
  await jsLibGenerator(tree, {
    name: trpcServerName,
    bundler: 'vite',
    unitTestRunner: 'vitest',
  });
  createTrpcServerBoilerPlate(tree, options.name);
  tree.delete(`libs/${trpcServerName}/src/lib/${trpcServerName}.ts`);
  tree.delete(`libs/${trpcServerName}/src/lib/${trpcServerName}.spec.ts`);
  updateJson(tree, `libs/${trpcServerName}/project.json`, (json) => ({
    ...json,
    sourceRoot: `libs/${trpcServerName}/src`,
  }));
}

4. Create a Library for Our tRPC Client

We'll use the same approach and the same @nrwl/js library generator for this lib as well:



import { libraryGenerator as jsLibGenerator } from '@nrwl/js';

// ...

async function createTrpcClientLibrary(
  tree: Tree,
  options: AppGeneratorSchema,
  trpcClientName: string
) {
  await jsLibGenerator(tree, {
    name: trpcClientName,
    bundler: 'vite',
    unitTestRunner: 'none',
  });
  createTrpcClientBoilerPlate(tree, options.name);
  tree.delete(`libs/${trpcClientName}/src/lib/${trpcClientName}.ts`);
  updateJson(tree, `libs/${trpcClientName}/project.json`, (json) => ({
    ...json,
    sourceRoot: `libs/${trpcClientName}/src`,
  }));
}

function createTrpcClientBoilerPlate(tree: Tree, name: string) {
  const { className, fileName } = names(name);
  const { npmScope } = getWorkspaceLayout(tree);
  const trpcClientBoilerPlate = `import { ${className}TrpcRouter } from '@${npmScope}/${fileName}-trpc-server';
import { createTRPCProxyClient, httpBatchLink } from '@trpc/client';

export const create${className}TrpcClient = () =>
  createTRPCProxyClient<${className}TrpcRouter>({
    links: [httpBatchLink({ url: '/api' })],
  } as any);
`;
  tree.write(
    `libs/${fileName}-trpc-client/src/index.ts`,
    trpcClientBoilerPlate
  );
}

The client here is pretty trivial and not expected to change, so we'll use 'none' for our unitTestRunner option to avoid adding unit tests for this lib.

Putting Our Whole Generator Together

With all this in place, we're good to go! To recap, here's the entirety of our function now:



import { getWorkspaceLayout, names, Tree, updateJson } from '@nrwl/devkit';
import { applicationGenerator as nodeAppGenerator } from '@nrwl/node';
import { libraryGenerator as jsLibGenerator } from '@nrwl/js';
import {
  applicationGenerator as reactAppGenerator,
  setupTailwindGenerator,
} from '@nrwl/react';
import { AppGeneratorSchema } from './schema';
import { Linter } from '@nrwl/linter';

const defaultPorts = {
  frontendPort: 3000,
  backendPort: 3333,
};

export default async function (tree: Tree, options: AppGeneratorSchema) {
  const optionsWithDefaults = {
    ...defaultPorts,
    ...options,
  };
  const kebobCaseName = names(optionsWithDefaults.name).fileName;
  const webAppName = `${kebobCaseName}-web`;
  const serverName = `${kebobCaseName}-server`;
  const trpcServerName = `${kebobCaseName}-trpc-server`;
  const trpcClientName = `${kebobCaseName}-trpc-client`;
  await createReactApplication(tree, optionsWithDefaults, webAppName);
  await createNodeApplication(
    tree,
    optionsWithDefaults,
    serverName,
    webAppName
  );
  await createTrpcServerLibrary(tree, optionsWithDefaults, trpcServerName);
  await createTrpcClientLibrary(tree, optionsWithDefaults, trpcClientName);
}

// omitting the function implementations, but they would go below here

Which reads like a list of exactly what we set out to do at the start!

The generators in your Local Plugin can serve as the expected scaffolding for our stack codified (as well as automated!).

This way, if you decide to alter your stack or change this scaffolding - you can adjust your generators via a Pull Request.

That pull request can serve as a discussion place to verify the change, and once merged, your stack will follow the new standard!

Use your Generator

To use the generator now, run the command:



npx nx generate @nx-trpc-example/plugin:app test

Where @nx-trpc-example is the name of our workspace, plugin is the name of the plugin we created, app is the name of the generator we created, and test is the name of the full-stack app we want to create.

After creating our test app via the generator, we can run the command to start our server:



npx nx serve test-server

And in a separate terminal, we can run the command:



npx nx serve test-web

To run our react application that communicates with our server. This should give us our full-stack development environment to respond to our saves as long as these serve commands are running. But wouldn't it be great to run this in the same terminal via a single command?

In the next section, we'll create an executor that will allow us to run both of these serves in a single command.

Create an Executor

Next, we'll add a way to run both the frontend and backend applications in a development mode in a single command. As it turns out, Nx gives us a way out of the box to do this via:



% npx nx run-many --target=serve

 >  NX   Running target serve for 2 projects:

    - test-server
    - test-web

 —————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————

> nx run test-server:serve


> nx run test-web:serve:development

Loading proxy configuration from: /Users/zackderose/nx-recipes/trpc-example-stack/apps/test-web/proxy.conf.json
  ➜  Local:   http://127.0.0.1:3000/
Debugger listening on ws://localhost:9229/7c8bd276-1df5-43e2-81cc-7de68cde56c4
Debugger listening on ws://localhost:9229/7c8bd276-1df5-43e2-81cc-7de68cde56c4
For help, see: https://nodejs.org/en/docs/inspector
Listening at http://localhost:3333/api
[ watch ] build succeeded, watching for changes...

With that in place, both our client and server are started with the one command, but it's difficult to tell in the terminal which line belongs to which process, so we'll address this by creating an executor so that our resulting terminal looks like this:

(That's everything for the high-level view of understanding of executors! Feel free to skip ahead to how we can use this executor once it's created, or other stick around for an in-depth explanation of the implementation details!)

Our goal in Nx's task-running API is to simplify any task to a single function: an executor. When we use Nx to run a task (like with the command: npx nx build my-app) Nx will determine the executor function attached to my-app's build target and call that executor function!

To create an executor that will serve both the front and backend applications, we'll start by running the command:



npx nx g @nrwl/nx-plugin:executor serve-fullstack --project=plugin

This will run the executor generator of the @nrwl/nx-plugin package to create an executor called serve-fullstack in our plugin library, with all the scaffolding managed for us.

Not unlike our generator, we can adjust the parameterization of the executor here, starting with the libs/plugin/src/executors/serve-full-stack/schema.d.ts:



export interface ServeFullstackExecutorSchema {
  frontendProject: string;
  backendProject: string;
}

This will require us to provide the name of the frontendProject and backendProject in the options of any targets we set up for this executor. We'll also add the corresponding libs/plugin/src/executors/serve-full-stack/schema.json file:



{
  "$schema": "http://json-schema.org/schema",
  "version": 2,
  "cli": "nx",
  "title": "ServeFullstack executor",
  "description": "",
  "type": "object",
  "properties": {
    "frontendProject": {
      "type": "string",
      "description": "The name of the frontend project to serve."
    },
    "backendProject": {
      "type": "string",
      "description": "The name of the backend project to serve."
    }
  },
  "required": ["frontendProject", "backendProject"]
}

With that setup, we'll start in the libs/plugin/src/executors/serve-fullstack/executor.ts file.

While we could take a similar approach as our generators and import the executors from our @nrwl/... packages, this is not as feasible for our use case.

Long-running executors (a task that is expected to keep running until canceled, for instance: a serve - as opposed to executors that complete at some point, like a build) return an AsyncInterator from the existing first-party Nx Executors currently, which are a bit more challenging to work with.

So instead, we'll use Node's child_process api to use Nx's CLI to call the serve's of our web app and server. Then we'll listen to emissions from these processes' stdio and stderr and log them with a good-looking prefix. In the end, it should look like this:

Starting our Server

We'll start by running the server first, as we'll need our server running for our web server's proxy to be created correctly when we start running it.

Here's the code to do so:

The startBackendServer() function will return a Promise that never resolves. This will ensure that the task will never complete (this is another way of achieving a long-running task, in addition to the AsyncIterators mentioned before).

Line 16 above creates the child process, and lines 19-20 will ensure that if our parent process ends (like if the user pressed CTRL-C while it's running), the child process will be kill()ed as well.

On lines 21-25, we'll also listen for the substring: 'build succeeded, watching for changes...' here to start up our frontend serve next!

Note the second input here: the ExecutorContext on line 9 above.

We won't use this in the generator in this example. Still, when Nx calls this function to run our executor, it will provide all of this potentially helpful context information in the second parameter here, which is useful for many other use cases!

Starting our React App

We'll use the following function to start up our frontend server:



async function startFrontendServer(frontendProject: string) {
  return new Promise(() => {
    const childProcess = exec(`npx nx serve ${frontendProject}`, {
      maxBuffer: LARGE_BUFFER,
    });
    process.on('exit', () => childProcess.kill());
    process.on('SIGTERM', () => childProcess.kill());
  });
}

This should look very similar to the function we wrote to start our backendProject!

With this function in place, we can adjust our startBackendServer() function now to call this only the first the backend server starts correctly:

Notice we added a variable to track whether we've started the frontend server before on line 2 above, and we added a check in line 10, just before calling our startFrontendServer() function on line 11.

Adding Good-Looking Prefixes to Our logs

At this point, our executor is functional, but if we run it right now, the logs will be empty! We'll fix this by creating a function that, when given a ChildProcess and a prefix, will relay anything logged by the process to the parent's stdout.

Since we want the prefixes to look nice, later, we'll use chalk (that Nx already has as a dependency, so it's already installed) and add some logic to center the name of the project and make all prefixes take the same amount of space:

Lines 2-12 above create a reusable function to prefix every line of any incoming string and send it to the parent process's stdout by calling console.log(), and lines 13-16 set up hooks to call this function whenever the given ChildProcess writes to stdout or stderr.

The function to padTargetName on lines 19-25 above will ensure that our prefix is centered and the same length as any other project name.

All that's left is to put it all together now:

Notice lines 12-13 above determines the targeted prefix width, and we adjusted our startBackendServer() and our startFrontendServer() functions to accept this as a parameter as well, and lines 28-31 and 54-57 add our prefixTerminalOutput() so both the ChildProcesses are prefixed correctly.

Use your Executor

To use our executor, we'll start by adding a new target to our apps/test-web/project.json file:

Lines 8-14 above add a new serve-fullstack target to our test-web app that we already created with our generator. Line 9 tells it to use the executor we just wrote, and lines 10-13 give that executor the required parameters we set up for it.

All that's left to do now is call this target from the Nx CLI:



npx nx serve-fullstack test-web

Putting it All Together

As a bonus step, now that we have our executor set up, we can automate this step of adding the serve-fullstack target to the right project.json file.

Going back to libs/plugin/src/generators/app/generator.ts, and specifically the createReactApplication() function, we can add another function called addFullStackServeTarget and call it after generating the rest of our react application:

Starting at line 26, we use @nrwl/devkit's updateJson() function to do just this to the project.json of the react app that we'll create in this generator.

As we can see in the result, the whole picture of what we've created allows us to "stamp out" any number of full stack applications to add to our monorepo's workspace, given simply a name (and optionally a frontend or backend port!). We are then fully set up to execute a full-stack serve where we can easily distinguish the logs from our frontend vs. backend serve processes, as we saw in our original teaser:

Recap

In this article, we looked at the history and evolution of tech stacks and saw how Nx is positioned to be an integral part of creating and maintaining tech stacks in the future!

While this plugin currently exists only within our current workspace that we built together, we'll follow up this blog post with another on how to publish and share your plugin with the broader community (including an init generator for installing required packages, and a preset generator for creating a new workspace from scratch!)

Learn more

If you liked this, click the ❤️ and make sure to follow Zack and Nx on Twitter for more!

Nx 15.4 - Vite 4 Support, a new Nx Watch Command, and more!

Zack DeRose — Thu, 22 Dec 2022 21:21:23 +0000

Nx just had a massive release 2 weeks ago with Nx 15.3 - if you missed it be sure to check out our article featuring some huge improvements including Vite support, Standalone Angular and React presets, and a Task Graph visualization!

But over the past couple of weeks, we’ve been able to land quite a few awesome features, so we’re going back at it again releasing Nx 15.4 today, including:

Vite 4 support
A new nx watch command
Webpack-less Cypress for React Standalone
Server-Side Rendering support for Module Federation for both Angular and React Applications
Running Multiple Targets in Parallel for Multiple Projects
Interactive Custom Preset Prompts

Vite 4.0 Support

Nx 15.4 brings in the latest Vite major version following the Vite 4 release earlier this month.

As the Vite launch article mentions, we are investing in the Vite ecosystem, and now officially support a first-party Vite plugin. Nx 15.4 continues this investment with timely support for Vite 4, and we’re excited to be a part of the Vite ecosystem and a part of bringing more value to our devs through Vite support!

Projects already using our @nrwl/vite plugin will be automatically upgraded to Vite 4 when they upgrade to the latest Nx version with the nx migrate command, and we've also simplified the configuration required to support Vite.

We've also spent some effort into making the conversion of existing projects to use Vite simpler, including:

the ability to choose which targets you want to convert
enhanced vite.config.ts file configuration
better DX with detailed messages during conversion
better documentation around converting using our generator
adding a guide to our docs for converting manually

You can check out more details about our Vite plugin including how to add Vite and Vitest to your existing Nx workspace by visiting our docs at nx.dev/packages/vite

Nx Watch

Nx 15.4 includes a new feature to support file-watching with Nx! Here’s how it works:

Syntax:

nx watch [projects modifier option] -- [command]

Example:

nx watch --all -- nx build \$NX_PROJECT_NAME

For the projects modifier option:

you can use --all for all projects in the workspace
or you can filter down to specific projects with the --projects=[comma separated list of project names] option that can be used in conjunction with a --includeDependentProjects option as well

The nx watch command will support the variables $NX_PROJECT_NAME and $NX_CHANGED_FILES. This feature opens the door for nice developer workflows where we can provide an out-of-the-box mechanism for Nx to run relevant tasks on save, and we’re excited to see our users get their hands on this feature.

Personally, I'm excited to use the following command:

npx -c 'nx watch --all -- nx affected --target=test --files=\$NX_FILE_CHANGES'

To link in nx watch with the nx affected command to have a single watch command to run all my affected tests on save as they are affected!

Check out our docs for more details.

Webpack-less Cypress Support for Our React Standalone preset

We added a React Standalone preset in 15.3 to support single react application workspaces with Nx, and in 15.4, we’ve added back in Cypress for this preset.

With Nx 15.4, a standalone React application will be created with an e2e directory preconfigured and optimized for running Cypress with the command npx nx e2e e2e as soon as your initial workspace is generated.

Server-Side Rendering support for Module Federation for both Angular and React Applications

Now you can get the benefits of both Server Side Rendering and Module Federation for your applications, which will improve page loads, Search Engine Optimization, and build times!

Our existing host and remote Module Federation generators have an added --ssr flag that will enable Server-Side Rendering by generating the correct server files.

We've also added a new executor to allow you to serve the host server locally, along with all remote servers from a single command.

Learn more about this new feature in our docs!

Running Multiple Targets in Parallel for Multiple Projects

Nx 15.4 includes updates to the nx run-many command, allowing you to add multiple whitespace separated targets, as well as globs in the projects option, for example:

npx nx run-many --target test build lint

^ this would run all test, build, and lint targets in your workspace, and you can now filter this down to select projects via globbing:

npx nx run-many --target test build lint --projects "domain-products-*"

^ this will now run all test, build, and lint targets for all projects in your workspace that start with "domain-products-".

Interactive Prompts for Custom Preset

Last but not least, we’ve added support for interactive prompts for Custom Presets!

In Nx, presets are special code generation scripts that can be used to create a brand new Nx Workspace, using our create-nx-workspace command.

For instance, I happen to know Shai Reznik at builder.io has been working on a qwik plugin for Nx, and since the qwik-nx plugin that he’s published includes an Nx generator called “preset”, I can run the command:

npx nx create-nx-workspace –preset=qwik-nx

As we can see, the preset option matches the name of the published npm package.

This custom preset feature has been around for a while, but as of 15.4 we’ve added support for these custom presets to interactively prompt the user following the initial installation step!

This should open up some powerful functionality for plugin and package authors to parameterize their code generation scripts with Nx, and we’re excited to see folks like Shai, builder.io, and qwik leverage this new feature!

That's it for this release.

You can find full changelogs for the release on github.

How to Update Nx

Updating Nx is done with the following command and will update your Nx workspace dependencies and code to the latest version:

npx nx migrate latest

After updating your dependencies, run any necessary migrations.

npx nx migrate --run-migrations

Learn more

Also, if you liked this, click the ❤️ and make sure to follow Zack and Nx on Twitter for more!

Nrwl Wins | April 8, 2022

Zack DeRose — Mon, 11 Apr 2022 14:37:29 +0000

Nx

@nxdevtools

Our first #NrwlWins!!

Check out 🧵⬇️ for links!

17:07 PM - 08 Apr 2022

The "DeRxJSViewModel Pattern": The E=mc^2 of State Management [Part 2]

Zack DeRose — Sun, 31 Oct 2021 07:58:17 +0000

👋 hi all - this article is a continuation of a previous article that explains the goals of the DeRxJS pattern:

entirely de-couple state management code from presentational code (to the point where your state management code could be re-used across frameworks)
maximize the benefits of RxJS, while minimizing the negatives
next-level testing [and potential to hand over all our state-management code to AI at some point]

In that article, we did most of the heavy lifting - developing our state-management code and fully testing out every edge case with "timeline testing" (allowing us to assert not only "what" state looks like, but "when" it should look that way as well).

In this article, we'll bring that state management code and show how we can use this across 3 front-end "frameworks": React, Angular, and Vanilla JS.

React

One of the goals of DeRxJS [as the name suggests] is to remove actual RxJS code from our code bases. We discussed in the previous example how @derxjs/reducer can help us write our state management, leveraging RxJS, but without actually writing any RxJS code ourselves.

In this article, I'm excited to introduce @derxjs/react - that will allow us to leverage that same approach to our react presentation code.

In all honesty, I've prioritized React as the first presentation-based package for derxjs in part because of React's popularity. But beyond that there are 2 huge reasons that I've targeted React first:

RxJS and React don't really play well together [yet!]
One of my favorite things about React is how it is not domain-specific, for nearly everything but state-management! (Interestingly, I think this is almost entirely inverted from Angular, which I'd argue is domain-specific for everything BUT state-management) Marrying React and RxJS I think can close that gap, so that the state-management code you write is as domain-agnostic as the rest of your react code.

In general, I'm quite long on React. My motivations are almost entirely selfish - I think if this package works the way I want it to, this will be my ideal environment for frontend development.

Without further ado, here's the general api for our @derxjs/react code:

export const TicTacToe = () => {
  return DeRxJSComponent<
    TicTacToeViewModelInputs,
    TicTacToeViewModel,
    TicTacToeProps
  >({
    viewModel$: ticTacToeViewModel$,
    component: TicTacToeView as any,
    initialValue: createInitialViewModel(),
    triggerMap: {
      spaceClick: 'userSpaceClickEvents$',
      resetClick: 'userResetClickEvents$',
    },
    inputs: {
      ai: randomAi,
    },
  });
};

viewModel$ is imported from our work from the previous article
component is a presentational component (we'll see that next!)
initialValue is the starting value for our state (the createInitialViewModel() function comes from the previous article as well)
triggerMap is a [type-safe!] object that maps the name of "trigger" functions for our presentational components to Observable inputs of our viewModel$. "Trigger" functions are how we'll communicate the message passing our presentation component will need to perform, and hand this off to to the @derxjs/react package to turn those into Observables (so we don't have to write any of that RxJS code ourselves).
inputs is our way to provide any non-reactive (or non-Observable) inputs to our viewModel$ function. Note we're passing our randomAi function here - essentially parameterizing functionality of our viewModel$ this way. (Would be fun in future work to create an "unbeatable" ai as well!)

This API is designed to allow you to write all presentational code as "presentational" components, delegating any smarts to your @derxjs/view-model, and using the provided trigger functions for message passing.

Here's how that code ends up looking:

interface TicTacToeProps {
  spaceClick: (spaceCoordinates: SpaceCoordinates) => void;
  resetClick: () => void;
}

interface SpaceProps {
  contents: SpaceContent;
  spaceCoordinates: SpaceCoordinates;
  clickHandler: (spaceCoordinates: SpaceCoordinates) => void;
}
const Space = ({ contents, clickHandler, spaceCoordinates }: SpaceProps) => (
  <div>
    <button onClick={() => clickHandler(spaceCoordinates)}>
      {contents.toUpperCase()}
    </button>
  </div>
);

function TicTacToeView({
  state,
  triggers,
}: {
  state: TicTacToeViewModel;
  triggers: TicTacToeProps;
}) {
  return (
    <>
      <h2>{state.turn}</h2>
      <div className={'border'}>
        <div className={'board'}>
          {([0, 1, 2] as const)
            .map((row) => ([0, 1, 2] as const).map((column) => [row, column]))
            .flat()
            .map(([row, column]) => (
              <Space
                contents={state.board[row][column]}
                spaceCoordinates={{ row, column }}
                clickHandler={triggers.spaceClick}
                key={`${row}:${column}`}
              />
            ))}
        </div>
      </div>
      <button className="reset" onClick={triggers.resetClick}>
        Reset
      </button>
    </>
  );
}

Note how onClicks are set to those "trigger functions" we defined.

Here's that code in action:

Angular

Next up: Angular! As mentioned, I'm of the opinion that Angular is generally very domain-agnostic when it comes to state management. In particular, it's very RxJS friendly.

As such, I don't know if a @derxjs/angular package is really necessary. Eventually we could end up creating a package of utilities for hiding more of the RxJS code that we'd write, but I have no plans for that at the moment.

Here's a look at the Typescript component code we'll write:

export class AppComponent {
  userResetClickObserver!: Observer<void>;
  userResetClickEvents$ = new Observable<void>(
    (observer) => (this.userResetClickObserver = observer)
  );
  userSpaceClickObserver!: Observer<SpaceCoordinates>;
  userSpaceClickEvents$ = new Observable<SpaceCoordinates>(
    (observer) => (this.userSpaceClickObserver = observer)
  );
  vm$ = ticTacToeViewModel$({
    ai: randomAi,
    userSpaceClickEvents$: this.userSpaceClickEvents$,
    userResetClickEvents$: this.userResetClickEvents$,
  });
  rows: BoardIndex[] = [0, 1, 2];

  handleSpaceClick(coordinates: SpaceCoordinates) {
    this.userSpaceClickObserver.next(coordinates);
  }

  handleResetClick() {
    this.userResetClickObserver.next();
  }
}

Note how we're creating our observables by creating an 'observer' property on the class at "construction time", and then in our click handler methods, we call next() on those observers. (This essentially the same "message passing" as our React code, but the @derxjs/react package hid most of the actual code here)

Similar to our react example, we'll see the same idea of a 'presentational' component in our template - with the one exception of passing our viewModel$ to the Angular async pipe at the top level of our template:

<h1>Tic Tac Toe</h1>
<ng-container *ngIf="vm$ | async as vm">
  <h2>{{ vm.turn }}</h2>
  <div class="border">
    <div class="board">
      <ng-container *ngFor="let row of rows">
        <div *ngFor="let column of rows">
          <button (click)="handleSpaceClick({ row, column })">
            {{ vm.board[row][column] | uppercase }}
          </button>
        </div>
      </ng-container>
    </div>
  </div>
  <button class="reset" (click)="handleResetClick()">Reset</button>
</ng-container>

Nice and simple :). Here's the stackblitz for our Angular code:

Vanilla JS

In this example, we'll use the dom-manipulation API to do the lifting that React and Angular were doing in their examples. Here's the simplified version of what we're doing:

Create a "template" for our component, attaching id's to the buttons we'll need to listen to for clicks/update their text. This example is a bit fortunate as all the elements on the DOM are static (they don't need to be added or removed, so we can just leave the Element objects on the DOM as-is, and change their text content. This would be significantly more difficult if this were not the case).
use fromEvent from RxJS to get observables of the 'click' events on the buttons.
Once we have our observables, pass them to that same viewModel$ function we used in React and Angular to create our View Model observable.
Subscribe to that observable, and update the 'board' by changing the text content of the buttons to match the board property on the view model object.

Here's how that looks in the stackblitz:

Conclusion

And that's a wrap!! Hope that this article helped spark some cool ideas. Be sure to reach out on twitter or check out the DeRxJS repo if you ever want to jam about state-management or good code architecture!!

About the author

Zack DeRose [or DeRxJS if you like] is:

a GDE in Angular
a recent nx conf/NgConf/RxJS Live/The Angular Show/ZDS speaker
Creator of the @derxjs OSS packages
Senior Engineer and Engineering Manager at Nrwl

Checkout out my personal website for more of my dev content! And go bug Jeff Cross/Joe Johnson if you want to hire me to come help out your codebase or come help level up your team on Nx/NgRx/DeRxJS/RxJS/State Management! (I especially love building awesome stuff - and building up teams with bright developers that are eager to learn!)

The "DeRxJSViewModel Pattern": The E=mc^2 of State Management [Part 1]

Zack DeRose — Fri, 08 Oct 2021 14:15:48 +0000

Part 1: Creating a Blue Print, setting up TDD and Test Specs to Be CERTAIN that Our Code is Built to Spec.

What we'll learn in this article

Hi everyone! 👋

Today, I'm going to share and analyze a pattern that I've become quite fond of recently for managing state management in a way that is truly domain agnostic.

We'll do this by first discussing a new pattern for implementing state management code using RxJS in this article. In a follow up article (that I've committed to releasing next friday), we'll demonstrate its "domain agnosticism" by using the same code to create a small app in vanilla JS [by which I simply mean "JS without a framework/library"], Angular, and React.

There's something of a prerequisite of some more basic JS knowledge, and familiarity with RxJS would helpful here, but my goal is for this to be accessible for junior and senior engineers alike!

Also before we proceed, [not-so-]coincidentally, I've recently published a new npm package to the registry that we'll be using in this series: 🎉🎉🎉 @derxjs/view-model 🎉🎉🎉.

Installing the package is not necessary for this article, but I'm very excited for our roadmap as I think that this had the potential to be a huge E = mc^2 moment (more on that later!), so I highly recommend that you check it out.

Here's how the work will break down:

First part we'll need to do is create TS types, which will serve as our blueprint for the lego blocks.

From there, it doesn't really matter which of the 5 second-tier tasks we take on next, but in some order, we're going to:

create our ViewModel tests
build out the ViewModel implementation
create a "vanilla" JS app
create an Angular app
create a React app

In another world, we could even potentially have 5 different developers each working on these tasks in parallel if we had the resources for that!

Unfortunately, my brain (and articles in general) is for the most part only single threaded, [insert huberman labs link on double focus] so instead, our path through these tasks is going to look like this:

In this article, we'll create our @derxjs/view-model TS types, then write out our tests, and then finally use TDD to implement our spec with absolute confidence that we built what we set out to build.

Next week, we'll put this all to good use, creating 3 webapps with 3 different frameworks.

So without further ado..... let's do this!!!

Establishing our tools

[This section is designed more for junior developers - please feel free to skip these if you're already familiar with Ts and Observables and RxJS]

Typescript

For this article, we'll be using Typescript interfaces to help us think about our problem, and to help us to architect a solution. In the context of our view model pattern, Typescript will allow us to create a "shape" of the view model data that our particular "domains" (think vanilla JS, Angular, and React) will leverage to create our html from that data (this is also known as "templating").

Think of TS as a blueprint that we'll use early on in our development process to lay out our problem, that we'll continue to leverage and keep us honest as we actually build our solution out.

RxJS

RxJS is a library we'll use to compose observable event streams (or Observables) in our code. I advise that it's best to think of Observables as "Timelines".

RxJS also introduces the idea of an "operator" as a function that takes an Observable and returns a new Observable. In the context of our "Observables as 'Timelines'" mental model then, an operator is a function that takes a "Timeline" as input, and returns a new "Timeline" as output.

(^ this is a talk I gave on Observables as "Timelines" at RxJS Live 2021.)

The “Pro’s” of RxJS are:

Extreme precision and control over code
ability to write tests with a higher order of magnitude of precision
Declarative, expressive, powerful code
Huge potential for composability
A perfect mental model and toolset for frontend web development (essentially a flurry of user-generated events with no guaranteed sequence)

The “Con’s”:

Takes a long time to fully understand
Even if YOU make the investment to learn it, hard to pass that buck off onto the next developer to use our code [makes it difficult to scale]
Many complicated/confusing dimensions
- "Observable joining strategies" (merge, switch, exhaust, concat)
- Hot vs. Cold vs. Luke-Warm (cold observable sourced with a hot observable)
- Behavior vs. Replay vs. plain vs. "Async" emmission strategy
“Dangerous”
- Risk of “leaky subscriptions”
- Risk of wrong implementation bugs
- Risk of poor implementation leading to even worse code (the only thing worse than complicated imperative code is a complicated mess of imperative code with a healthy chunk of “reactive” code mixed in)
They flood the call stack, making debugging untennable (this is especially unfortunate as bugs in your RxJS code are probably the kind of bugs that we need good debugging tools for the MOST)

In many ways, the pattern recommended in this article (and supported on @derxjs packages) is designed to squeeze all the awesome benefits out of RxJS, while avoiding all the nasty pitfalls:

Our view model function will take as input an Observable of our user's events
It will return as output a single Observable of our ViewModel interface
We'll build out extensive, precise test suite BEFORE starting our implementation to ensure that we're developing EXACTLY what we set out to build.
We'll use operators inside of our implementation to compose the transition of the input Observables to the output Observable

What is the "DeRxJS View Model" Pattern?

The basic idea for the "DeRxJS View Model" pattern is:

Pass Observables in (along with maybe a few functions or pieces of data)
Get a single Observable out
Use your framework of choice for templating (turning the output Observable from #2 into html).

The `E = mc^2` of State Management

import { Observable } from "rxjs";

export type DeRxJSViewModel<InputType, ViewModelType> = (
  inputs: InputType
) => Observable<ViewModelType>;

^ The core of my @derxjs approach are these 5 lines of Typescript code. It's deceptively simple, but my hypothesis is, this pattern is elegant enough to encompass any && all possible state management requirements. It's a powerful core that has lots of potential as a pattern and mental model - as well as potential tools and utility code we can build on top of it!

To use this type, simply install the package (npm i @derxjs/view-model) and import the type into your code (import { DeRxJSViewModel } from '@derxjs/view-model';) [don't worry, I'll show it in use in our actual code snippets as well!].

If you want to opt out though - you can always just copy these 5 lines of code, and be on your merry way :).

Introducing the problem: Tic Tac Toe

Our example problem for today: creating a Tic Tac Toe game.

Let's break this idea down to a rough spec in English:

Presentational concerns

The user will need to see a 3x3 grid that will operate as our game board. We'll make this a 3x3 grid of buttons, and we'll need in our view model some way of modeling/structuring this data.
We'll want to allow the user to reset the game at anypoint (even while the computer is "thinking"). This should empty the board and make it their turn.

Logical concerns

We'll want to introduce the idea of "turns" to the game. During the user's turn, they should be allowed to click a button, but after clicking a button, they shouldn't be allowed to move until the computer opponent makes a move. We'll also want to make this feedback prominent to the user.
We'll need some AI for our computer opponent. As cool as it would be to use some GPT-3 here, instead, let's opt for a Random Number Generator (RNG) to act in the place of our AI, and we'll simulate our AI thinking by adding in a delay of 2 seconds before the computer player makes their move.
If the game is over (if either our player or the computer wins, or if the board is full and neither player won) we'll want to inform the user, and they'll need hit restart to play again.

Creating a Typescript blue print

Let's start by identifying the parameters of our system. The way I tend to think about this problem, the inputs come down to:

the user's events selecting spaces on the board.
the user's events selecting the "restart game" option.
a function that will act as the ai that will define how our computer player will act.

We can visualize the first 2 of these as Timelines, so we'll represent them as Observables - for the selection of spaces by the user, we'll represent that event with an object that states the column and row the user selected, and for the reset button clicks, the contents of the event actually doesn't matter much (just the fact that it happened is really all we need!).

For our ai, we'll define it as some function that will take a given Board and the computer's letter (x or o) and return the SpaceCoordinates for the space the computer will choose. This way we can pass in a determinist ai function for reliable testing of our code [but we'll see more on this later!!].

Let's transpose these to actual Typescript now:

interface TicTacToeViewModelParams {
  userSpaceClickEvents$: Observable<SpaceCoordinates>;
  userResetClickEvents$: Observable<void>;
  ai: TicTacToeAi
}

interface SpaceCoordinates {
  row: BoardIndex;
  column: BoardIndex;
}

type BoardIndex = 0 | 1 | 2;

type TicTacToeAi = (params: AiParams) => SpaceCoordinates;

interface AiParams {
  board: Board;
  aiLetter: 'o' | 'x';
}

type Board = [
  [SpaceContent, SpaceContent, SpaceContent],
  [SpaceContent, SpaceContent, SpaceContent],
  [SpaceContent, SpaceContent, SpaceContent],
];

type SpaceContent = 'x' | 'o' | '';

Next up, we'll create an interface for our View Model itself. We'll represent this with a board property that should contain a 3x3 array of either x's, o's, or empty spaces. The other thing we'll need is a turn property that will tell us if it's our turn, the computer's turn, or if the game is over.

interface TicTacToeViewModel {
  board: Board;
  turn: Turn;
}

type Turn =
  | 'your turn'
  | `computer's turn`
  | 'game over - you win'
  | 'game over - you lose'
  | `game over - it's a tie`;

The last step is to combine these into a function that takes our inputs and returns an Observable of our view model. Let's set out that function's signature now!

import { DeRxJSViewModel } from '@derxjs/view-model';

export const ticTacToeViewModel$: DeRxJSViewModel<
  TicTacToeViewModelParams,
  TicTacToeViewModel
> = ({
  userSpaceClickEvents$,
  userResetClickEvents$,
  ai
}) => {
  // implementation to go here
}

That about does it for our blueprint! Here's a rough blue print that matches our DeRxJS diagram from before:

As we mentioned prior, one of the best things architecturally about having done this work is we have 3 independent paths we could follow from here:

implementing the function
templating our component (in any of the 3 frameworks)
writing tests for our function!

To reiterate: in another scenario, we could even potentially have 3 different developers each working on a different branch of these three things at once.

Since our brains are mostly single-threaded though, let's start with writing tests for our function, then implementing the function, then templating!

TDD and setting up our Timeline Tests for our View Model

For a sneak peak of this in real code, go check out the example .spec file in the @derxjs repo (maybe go give us a start there too if you feel like it! :))

So, let's break this concept down && use some cool visualizations in the process. Before we get into that, let's address one big hairy issue about our specific system: RNG.

Our spec requires that the ai choose a valid space at random. The AI being random immediately throws off a key component of a reliable test suite: being deterministic (or "the same thing happening EVERY time").

Luckily, we thought of this before designing our system :). Because the ai() function is passed in as a parameter to our function, we can pass in a "deterministic AI" to our view model for our test, and then a "random AI" to our actual implementation (we could also come up with some other cool "flavors" of AI if we wanted - feel free to take this code and go nuts with it if you like! Would be cool to see someone come up with an "I always lose" AI.)

To get this, let's quickly draft out this ai function:

const testAiFunction: TicTacToeAi = ({ board }) => {
    for (const i of [0, 1, 2] as const) {
      for (const j of [0, 1, 2] as const) {
        if (board[i][j] === '') {
          return { row: i, column: j };
        }
      }
    }
    throw new Error('Ai was passed a full board. This should never happen');
  };

We should see the following behavior from this AI:

Very cool. By leveraging functions (for the people who like terminology, this is technically a "higher order function" as the DeRxJSViewModel is a function that took this ai() function as a parameter), we can see that we are able to pretty effortlessly make our system very highly configurable! If we wanted to - we could actually have passed in an async function (or a function that returns a Promise) here as well, and built in the 2 second delay right into our AI for even more configurability, but I think this is enough complexity for now.

Btw - if you thought passing functions was cool - just wait until what we can do when passing in observables as input!!

The Test Suite

We want to build out a test to cover our system. In general, we want to make sure we hit most of our edge cases and then maybe run the whole way through a couple times.

It's usually nice to start with a nice basic base-case, so let's start with an empty board where the user never makes any actions:

(Since we'll always use the same ai() function for every test, I've skipped that in the diagrams) but as we can see, this very basic test shows that with no user events, we start out with an empty board, and that board never changes.

Here's the code for this exact scenario:

test('with no user events, the board stays empty', () => {
    const firstUserState = createInitialViewModel();
    testScheduler.run(({ cold, expectObservable }) => {
      const userBoardClicks = cold<SpaceCoordinates>('------');
      const userResetClicks = cold<void>('------');
      const expected = cold('a-----', { a: firstUserState });
      const result = ticTacToeViewModel$({
        userSpaceClickEvents$: userBoardClicks,
        userResetClickEvents$: userResetClicks,
        ai: testAiFunction,
      });
      expectObservable(result).toEqual(expected);
    });
  });

Notice the ASCII art syntax!! While it's not bad here, I think it gets a bit of a bad rap for being a bit cumbersome to work with, and not without good reason! I was helping out with trying to line up these ASCII art kind of tests on the rxjs codebase, so I can vouch that it's not fun! (I think I got through 3 operators before I gave up :()

(@derxjs is working on a nice gui tool to "draw" out these timelines and spit out working jest .spec.ts files - but that's an article for another time)

Also notice the testScheduler! We'll touch on this in the next example:

So in this example, we can see the player chooses the center square - note the dotted vertical line! This shows us how the timelines are aligned horizontally so that the moment we observe the user select the middle square, we should immediately observe a new state in our UI - reflecting an 'x' in that square and showing that it is now the 'computer's' turn to move. Then 2 seconds later (2 seconds of "virtual time" thanks to our TestScheduler!!) we should see our AI move to that first open slot in the top left corner, and it should now be our player's turn again.

So to recap: our timeline test is showing us that for the given inputs (the two observables/timelines) here's the expected timeline.

Remember when we discussed the expressive power of the ai() function as a parameter to our tic-tac-toe system? These observable inputs are actually bringing in with them AN INFINITE NUMBER OF POTENTIAL FUTURES, EVENTS, AND COMBINATIONS OF EVENTS

and our viewModel function is [attempting] to WRANGLE EVERY SINGLE LAST ONE of them and handle them appropriately, and RxJS is masterful at allowing us to do so.

Part of the reason I'm so long on these timeline tests are because of how good they are at setting a mental model - and especially with RxJS code being so difficult to debug, these marble tests become even MORE valuable! After all, you don't have to debug what ain't broke!

Here's the code for this test (notice things starting to get a bit more hairy!

test('computer player makes a move 1999ms after the player selects a square', () => {
    const initialState = createInitialViewModel();
    const userClick: SpaceCoordinates = {
      row: 1,
      column: 1,
    };
    const afterUserClick: TicTacToeViewModel = {
      board: [
        ['', '', ''],
        ['', 'x', ''],
        ['', '', ''],
      ],
      turn: `computer's turn`,
    };
    const afterComputerMoves: TicTacToeViewModel = {
      board: [
        ['o', '', ''],
        ['', 'x', ''],
        ['', '', ''],
      ],
      turn: `your turn`,
    };
    testScheduler.run(({ cold, expectObservable }) => {
      const userBoardClicks = cold<SpaceCoordinates>('---a----', {
        a: userClick,
      });
      const userResetClicks = cold<void>('------');
      const expected = cold('a--b 1999ms c', {
        a: initialState,
        b: afterUserClick,
        c: afterComputerMoves,
      });
      const result = ticTacToeViewModel$({
        userSpaceClickEvents$: userBoardClicks,
        userResetClickEvents$: userResetClicks,
        ai: testAiFunction,
      });
      expectObservable(result).toEqual(expected);
    });
  });

Let's move onto the next case: make sure that nothing happens when a player clicks on an already filled square (and also that nothing happens 2 seconds AFTER the user clicks that filled square.... for hopefully evident reasons!!)

code:

test('user click does nothing on an already filled square', () => {
    const initialState = createInitialViewModel();
    const userClicksCenterSquare: SpaceCoordinates = {
      row: 1,
      column: 1,
    };
    const afterUserClick: TicTacToeViewModel = {
      board: [
        ['', '', ''],
        ['', 'x', ''],
        ['', '', ''],
      ],
      turn: `computer's turn`,
    };
    const afterComputerMoves: TicTacToeViewModel = {
      board: [
        ['o', '', ''],
        ['', 'x', ''],
        ['', '', ''],
      ],
      turn: `your turn`,
    };
    const userClicksComputersSquare: SpaceCoordinates = {
      row: 0,
      column: 0,
    };
    testScheduler.run(({ cold, expectObservable }) => {
      const userBoardClicks = cold<SpaceCoordinates>('---a 3s a-b-aaaa-bbbb-', {
        a: userClicksCenterSquare,
        b: userClicksComputersSquare,
      });
      const userResetClicks = cold<void>('------');
      const expected = cold('a--b 1999ms c', {
        a: initialState,
        b: afterUserClick,
        c: afterComputerMoves,
      });
      const result = ticTacToeViewModel$({
        userSpaceClickEvents$: userBoardClicks,
        userResetClickEvents$: userResetClicks,
        ai: testAiFunction,
      });
      expectObservable(result).toEqual(expected);
    });
  });

Notice our output looks the same, even though our user is spamming those selected squares!

Next up: The reset button works

test('reset button works', () => {
    const initialState = createInitialViewModel();
    const userClicksCenterSquare: SpaceCoordinates = {
      row: 1,
      column: 1,
    };
    const afterUserClick: TicTacToeViewModel = {
      board: [
        ['', '', ''],
        ['', 'x', ''],
        ['', '', ''],
      ],
      turn: `computer's turn`,
    };
    const afterComputerMoves: TicTacToeViewModel = {
      board: [
        ['o', '', ''],
        ['', 'x', ''],
        ['', '', ''],
      ],
      turn: `your turn`,
    };
    testScheduler.run(({ cold, expectObservable }) => {
      const userBoardClicks = cold<SpaceCoordinates>('---a------', {
        a: userClicksCenterSquare,
      });
      const userResetClicks = cold<void>('---- 1999ms ---a', { a: undefined });
      const expected = cold('a--b 1999ms c--a', {
        a: initialState,
        b: afterUserClick,
        c: afterComputerMoves,
      });
      const result = ticTacToeViewModel$({
        userSpaceClickEvents$: userBoardClicks,
        userResetClickEvents$: userResetClicks,
        ai: testAiFunction,
      });
      expectObservable(result).toEqual(expected);
    });
  });

Fairly straight-forward - but it will be a good marker to let us know if the most basic functionality of resetting our game is working properly

Next one is around the same reset case, with a twist: the user can reset the game while the computer is "thinking" (making sure that the move the computer would have made is appropriately "cancelled"!)

I think that covers it for most of the potential edge cases of our system! For good measure, I'd also throw a couple fully-played out games as well just to be sure that we can make it all the way through a game without issues (I'm not gonna diagram those out here, but you can see it in action for yourself in the @derxjs codebase :))

Run the test suite now if you like:

git clone https://github.com/ZackDeRose/derxjs.git
cd derxjs
npm i
npx nx test examples-tic-tac-toe-view-model-implementation

Implementing our "DeRxJS View Model" Pattern

Alright, so we've got a fully fleshed out spec at this point - time to implement!

(Btw - if you want to give yourself a fun challenge now - go clone my derxjs repo and erase the contents of tic-tac-tow-view-model-implementation/src/lib/view-model.spec, and see if you can get the tests to pass before reading this section!)

We could honestly go a couple ways with this specific problem (in particular a 'state machine' approach would be a great fit for this - and I hope to do a proper XState implementation [maybe even a @derxjs/xstate package somewhere down the line!!] at some point in the future).

But because it's a pretty common pattern, we'll look at a "reducer" solution here!

If you're familiar with the JavaScript Array.reduce() method, that's a great place to start:

const foo = [1,2,3,4]

function sum(arr: number[]): number {
  return arr.reduce(
    (accumulator, arrayItem) => accumulator + arrayItem,
    0
  );
}

console.log(sum(foo)); // 10

In this code, we used reduce to "reduce the contents of the array down to a single value: their sum." Notice that this too is a higher-order function (since it takes a function as a parameter), making it very versatile. You can do ALOT of things with reduce.

We're actually interested more in the reducer function though, specifically:

(accumulator, arrayItem) => accumulator + arrayItem

The idea for this function is that it will loop through the list and call this function for each item; the item itself going into the arrayItem param, and the return value of the prior function call going into the accumulator param.

In this way, we "reduce the array down to a sum"! Pretty cool.

We're going to take this same concept a bit further for our tic-tac-toe example now, expanding the anaology in 2 separate dimensions:

Instead of numbers, we're going to reduce some set of "observed events" (think user clicks and ai moves) down into the TicTacToeViewModel interface from the prior section; here it is again if you missed it:

export interface TicTacToeViewModel {
  board: Board;
  turn: Turn;
}

export type Turn =
  | 'your turn'
  | `computer's turn`
  | 'game over - you win'
  | 'game over - you lose'
  | `game over - it's a tie`;

export type SpaceContent = 'x' | 'o' | '';

export type Board = [
  [SpaceContent, SpaceContent, SpaceContent],
  [SpaceContent, SpaceContent, SpaceContent],
  [SpaceContent, SpaceContent, SpaceContent]
];

Instead of synchronously iterating through a defined list and returning a value at the end of it all, we're going to asynchronously handle events immediately as they are observed, emitting a corresponding state. (this one sounds intimidating, but this one is actually quite trivial thanks to RxJS!)

Before getting overwhelmed in all this, let's take a deep breath and break this down into it's pieces. The first step is to identify the events that could potentially change our TicTacToeViewModel.

Two of them are pretty clear (because they're input observables to our function!): user clicking a square, and user clicking reset.

Let's go ahead and wrap those up now, by creating interfaces for them that wrap their value in an object and add a 'type' property to them (we'll switch on these 'type values later on!):

interface UserSpaceClickAction {
  type: 'user space click';
  space: SpaceCoordinates;
}

// export interface SpaceCoordinates {
//   row: BoardIndex;
//   column: BoardIndex;
// }

interface UserResetAction {
  type: 'user reset click';
}

[You might see this elsewhere referred to as "tokenizing" (or "actionizing") the data.]

There's one more event that would change our view model though: the ai's moves:

interface AiAction {
  type: 'ai action';
  space: SpaceCoordinates;
}

We'll create a union type of these actions via TS as well:

type Action = UserSpaceClickAction | UserResetAction | AiAction;

Think of this as "grouping" the actions into a single type, where you know an Action is one of the 3 possible.

Now we'll write the signature for our reducer function:

export function reducer(
  state: TicTacToeViewModel,
  action: Action
): TicTacToeViewModel {
  // ... impl here
}

Best to think of this function as "handling" an action - so if a user clicks on a button, the next state should be the same as before, but with an 'X' on the square the user selected (and also the computer's turn - or maybe the user even won with that move and we should say "You Win!!"):

Or if the user clicks "reset" we should get a new board:

Or if the user clicks on an occupied square, or tries to act while it's the computer's turn, we should just stay the same.

Hopefully these sound familiar, because these are pretty much exactly the test cases we had tested prior! ONLY! Rather than thinking about the whole flow of data (the whole timeline) instead we're focused in on the micro: handling a single action.

Before we actually write these functions though, let's create some utility functions for the things we'll need:
TicTacTo Utility Fns

function isSpaceOccupied(board: Board, space: SpaceCoordinates): boolean {
  return board[space.row][space.column] !== '';
}

/**
 * assumes the given `space` is unoccupied!
 */
function nextBoard(
  board: Board,
  space: SpaceCoordinates,
  player: 'x' | 'o'
): Board {
  const newBoard: Board = [[...board[0]], [...board[1]], [...board[2]]];
  newBoard[space.row][space.column] = player;
  return newBoard;
}

function isGameOver(
  board: Board
): 'user wins' | 'computer wins' | 'tie game' | false {
  const winningCombinations: [
    SpaceCoordinates,
    SpaceCoordinates,
    SpaceCoordinates
  ][] = [
    [
      { row: 0, column: 0 },
      { row: 0, column: 1 },
      { row: 0, column: 2 },
    ],
    [
      { row: 1, column: 0 },
      { row: 1, column: 1 },
      { row: 1, column: 2 },
    ],
    [
      { row: 2, column: 0 },
      { row: 2, column: 1 },
      { row: 2, column: 2 },
    ],
    [
      { row: 0, column: 0 },
      { row: 1, column: 0 },
      { row: 2, column: 0 },
    ],
    [
      { row: 0, column: 1 },
      { row: 1, column: 1 },
      { row: 2, column: 1 },
    ],
    [
      { row: 0, column: 2 },
      { row: 1, column: 2 },
      { row: 2, column: 2 },
    ],
    [
      { row: 0, column: 0 },
      { row: 1, column: 1 },
      { row: 2, column: 2 },
    ],
    [
      { row: 0, column: 2 },
      { row: 1, column: 1 },
      { row: 2, column: 0 },
    ],
  ];
  for (const [x, y, z] of winningCombinations) {
    if (
      board[x.row][x.column] === 'x' &&
      board[y.row][y.column] === 'x' &&
      board[z.row][z.column] === 'x'
    ) {
      return 'user wins';
    }
    if (
      board[x.row][x.column] === 'o' &&
      board[y.row][y.column] === 'o' &&
      board[z.row][z.column] === 'o'
    ) {
      return 'computer wins';
    }
  }
  return (board.flat() as SpaceContent[]).some((contents) => contents === '')
    ? false
    : 'tie game';
}

export function createInitialViewModel(): TicTacToeViewModel {
  return {
    board: [
      ['', '', ''],
      ['', '', ''],
      ['', '', ''],
    ],
    turn: 'your turn',
  };
}

Functions make for really great "Lego blocks" and now that we have all these, let's write out function (throwing the real implementation in here because too many cases to cover them all in text, but good for you to look over it and make sure it makes sense):

export function reducer(
  state: TicTacToeViewModel,
  action: Action
): TicTacToeViewModel {
  switch (action.type) {
    case 'user reset click': {
      return createInitialViewModel();
    }
    case 'user space click': {
      if (state.turn !== 'your turn') {
        return state;
      }
      if (isSpaceOccupied(state.board, action.space)) {
        return state;
      }
      const newBoard = nextBoard(state.board, action.space, 'x');
      const result = isGameOver(newBoard);
      switch (result) {
        case false: {
          return {
            board: newBoard,
            turn: `computer's turn`,
          };
        }
        case 'user wins': {
          return {
            board: newBoard,
            turn: 'game over - you win',
          };
        }
        case 'tie game': {
          return {
            board: newBoard,
            turn: `game over - it's a tie`,
          };
        }
        default: {
          throw 'should not be reached';
        }
      }
    }
    case 'ai action': {
      const newBoard = nextBoard(state.board, action.space, 'o');
      const result = isGameOver(newBoard);
      switch (result) {
        case false: {
          return {
            board: newBoard,
            turn: 'your turn',
          };
        }
        case 'computer wins': {
          return {
            board: newBoard,
            turn: 'game over - you lose',
          };
        }
        default: {
          throw 'should not be reached';
        }
      }
    }
  }
}

Awesome!! It wouldn't be a terrible idea now to write some test for this reducer function (or even writing them before we implemented this) but since we already have our test suite set up, this is not really necessary. (Even the fact that we're using a reducer strategy right now is implementation detail that we don't necessarily want to preserve moving forward!)

The majority of our work is done now! For the sake of time, I'm going to reveal the rest of the black box of our "reducer" implementation of the ticTacToeViewModel$():

The shape "engine" is actually quite generic to the reducer pattern (although passing in the ai() function is a little bit of a twist... but not that much). If you've worked with NgRx, Redux, or some similar library, it actually probably looks very familiar already!

This "genericism" actually makes it quite nice to "package" this flow and... maybe publish it on npm??? (you can check out an example implementation for this same problem [that uses this exact same reducer function we just wrote!!] in the derxjs repo!)

But in any case, let's follow the diagram and see how to translate this into code:

First off, we'll take our incoming user actions and use the map operator to "tokenize" or wrap them into the right Action type, and then merge them down to create a single actions$ Observable. We'll go ahead here and create out actionsSubject and start sharing our actions to that subject.

const actionsSubject = new Subject<Action>();
const userClickActions$ = userSpaceClickEvents$.pipe(
    map(
      (space): UserSpaceClickAction => ({
        type: 'user space click',
        space: space,
      })
    )
  );
  const userResetActions$ = userResetClickEvents$.pipe(
    map(
      (): UserResetAction => ({
        type: 'user reset click',
      })
    )
  );
  const actions$ = merge(userClickActions$, userResetActions$).pipe(
    share({ connector: () => actionsSubject })
  );

(Green shows what we've done!)

Next up, we're gonna hook that actions stream up with our reducer function to create our state observable. This is the Observable<TicTacToeViewModel> that we set our to make!!! But we're not done yet...

const state$ = actions$.pipe(
    scan(reducer, createInitialViewModel()),
    startWith<TicTacToeViewModel>(createInitialViewModel()),
    distinctUntilChanged()
  );

^ Note how we used scan with our reducer function here. What we're doing is feeding in all the user's actions one-by-one, and each action is running through that reducer to get to a next "TicTacToeViewModel" object, which is a super clean && easy way to get to our Observable of that TicTacToeViewModel!!! This is where RxJS really shines in my opinion!

Note we're also starting with an initialState (think just an empty board) and we're going to use distinctUntilChanged to filter out any times our state observable would emit the same state over again (since we're creating this view model for a ui - it really doesn't make sense to make the UI re-render if [for example] the user tried to click on a space that was already occupied!

If we ran this now as is though, after the user made their first move, it would become the computer's turn, and so far, we haven't hooked up the ai piece of our code yet, so the user would just be stuck in that state....

This is where "effects" come into play! The idea of an effect (thinking generically in the context of DeRxJS/reducer) is that it is a function that takes our actions$ Observable, and our state$ Observable (or just one of them.... or NEITHER!) and returns a new Observable of actions that we're going to connect BACK into our actions Subject to share those actions back into the actions$ observable!

That's generically though - for our specific example, we only have the one effect that we need to worry about, and that's our AI!

We'll start this with the observed states, filtered down to only states where the turn has just changed to "computer's turn" - we'll then delay for 2 seconds before mapping the Board that came with the state through our ai() function to get our computer's move!

Last step is to wrap alll that into a (switchMap)[https://rxjs.dev/api/operators/switchMap] from the user reset actions! We do this so that if the user ever resets the game while the computer is "thinking", we'd "discard" that subscription, so that the computer doesn't randomly barge in 2 seconds after the last "user space click" action when it should be the user's turn!

const aiActions$ = userResetActions$.pipe(
    startWith(undefined),
    switchMap(() =>
      state$.pipe(
        filter((x) => x.turn === `computer's turn`),
        delay(2000),
        map((state) => ({
          type: 'ai action' as const,
          space: ai({ board: state.board, aiLetter: 'o' }),
        })),
        share({ connector: () => actionsSubject })
      )
    )
  );

  aiActions$.subscribe();

  return state$;

Last thing to do, subscribe to our aiActions$ and return the state$!

And yes - I'm aware there's a potentially leaky subscription there on the aiActions$!

I'm gonna say that's okay for now (in my mind, this "game" is all our app is, so no need to teardown...) - but be sure to checkout the DeRxJS/reducer source code to see how we could handle that!

Closing Thoughts

I'm very excited for the work we're doing here (and not just because of the upcoming DeRxJS roadmap 👀):

The reason I'm excited is that (in case you didn't notice) NONE OF THE CODE WE WROTE IN THIS ARTICLE is domain-specific. Beyond just Angular/React/Vue/etc., we could take this same 'tic-tac-toe' state management code now and drop it in a mobile app/a native app/Artificial Reality/Augmented Reality/really ANY presentation layer and our state management code would be valid, and proven to be to spec!

I'm very excited to see where this takes us next - and I can't wait to see y'all in the next article!!

About the author

Zack DeRose [or DeRxJS if you like] is:

a GDE in Angular
a recent nx conf/NgConf/RxJS Live/The Angular Show/ZDS speaker
Creator of the @derxjs OSS packages
Senior Engineer and Engineering Manager at Nrwl

Creating a Habit Tracker App using Typescript, React, and Tailwind

Zack DeRose — Sun, 21 Feb 2021 07:46:53 +0000

What We're Building!

In a previous article, I had mentioned creating a 'morning habit stack' as part of my on-going effort this year to establish good habits and become a more productive person.

As a part of wanting to establish this habit, I figured I'd use the "Seinfeld Calendar" approach - but being a web developer, I'd kinda prefer to make some sort of online tool for tracking my habit... so let's do it!!

[Most of my efforts are fueled by the book "Atomic Habits" by James Clear - if you're interested in learning more!!]

Breaking Down the Problem

A critical skill [maybe THE critical skill] in our line of work is breaking down a problem into logical pieces. Let's follow this exercise for this small example:

Determine the 'shape' of our data, both in how we'd like to "store" the data, and how we'd like to use the data within a Calendar component.
Create functions to convert the "stored" shape of our data to the shape we'd like to use in our components.
Create a React Component for our Calendar, with appropriately accessible HTML elements (good bones are important!!)
Add tailwind utility classes to improve our presentation!

First Step: Determine the "Shape" of our Data!

Looking at our desired output, let's focus first on determining the way we'd like to store data for our calendar. I think there are likely many valid ways we could take this - but going with a basic and simple approach, I think the following Typescript interface covers most of our bases:

export interface HabitTrackerProps {
  startDate: {
    dayOfTheWeek: string,
    month: string,
    date: number
  },
  endDate: {
    dayOfTheWeek: string,
    month: string,
    date: number
  },
  results: string[]
}

Given this information, we should be able to determine everything we'd need to display the calendar view shown at the start of this section.

Better Types, plus Iterables!

To enhance this typing, we can add the following:

export DAYS_OF_THE_WEEK = [
  'Sunday',
  'Monday',
  'Tuesday',
  'Wednesday',
  'Thursday',
  'Friday',
  'Saturday',
] as const;
export type DayOfTheWeek = typeof daysOfTheWeek[number];

export const months = [
  'January',
  'February',
  'March',
  'April',
  'May',
  'June',
  'July',
  'August',
  'September',
  'October',
  'November',
  'December',
] as const;
export type Month = typeof months[number];

The as const syntax here signals to our typing system that these arrays are readonly, which allows us to create a union type from the arrays!

This is helpful as it gives us a proper type, as well as an Iterable, that we'll see come in handy in future sections!

Let's also define a union type for our results to make that a bit more clear-cut:

export type HabitResult = 'success' | 'failure';

With these changes, we can now enhance our typing:

interface CalendarDate {
  dayOfTheWeek: DayOfTheWeek,
  date: number,
  month: Month
}

export interface CalendarProps {
  startDate: CalendarDate,
  endDate: CalendarDate,
  results: HabitResult[]
}

Data Format for our "Template"

The data model we've set up is simple enough for storage I'd wager! It's pretty minimal in what it holds (we probably could remove the day of the week and add a year, and then extrapolate the day of the week from the other info... but this works for our use-case I think). The data is fairly human-readable as well, while still passing the 5-second rule of comprehension:

{
  "startDate": {
    "month": "February",
    "date": 4,
    "dayOfTheWeek": "Thursday",
  },
  "endDate": {
    "month": "March",
    "date": 21,
    "dayOfTheWeek": "Sunday",
  },
  "results": [
    "success",
    "success",
    "success"
  ]
}

When it comes to the data we'd like to work with in 'templating' out our calendar component in tsx, we'd like to refine this data a bit to make it easier to work with! Here's what I'd like to see personally:

const data = {
  'week-1': {
    Sunday: {
      month: 'January',
      date: 31,
      result: 'out of bounds',
    },
    // ...
  },
  'week-2': {
    // ...
  }
}

If this were fully expanded, it would definitely start surpassing the capacities of a human brain (well, mine at least!) but its perfect data format for our computers to iterate through as we create our DOM nodes!

To type this properly, let's reach for the Record utility type from Typescript. I definitely advise reading the official docs here! But the short version is a Record<keyType, valueType> will specify an object where all the keys conform to the keyValue and all values conform to the valueType, AND FURTHERMORE - if the keyType is a union type, then it will assert that a key exists for EVERY type in the union type!

This is perfect for our 'days of the week' use-case:

export interface HabitTrackerDay {
  month: Month,
  date: number,
  result: ResultToDisplay
}

export type HabitTrackerWeek =
  Record<DayOfTheWeek, HabitTrackerDay>

Also looking at the ResultToDisplay type, we'd like for this to support all possibilities of the HabitTrackerResult, but we also probably need a out of bounds and a no result yet option here to support everything our UI requires! To do this, lets create that type:

export type ResultToDisplay = 
  | HabitTrackerResult
  | 'out of bounds'
  | 'no result yet';

Now that we have a week, let's create the following type for all our data:

export type HabitTrackerData =
  Record<string, HabitTrackerWeek>;

This will allow us to create an object with our week names mapped to a week's chunk of data. To supplement this data, we'll also probably want a list of all week names to iterate though. We could create this from this object (Object.keys(habitTrackerData)), but might as well supply it to our template, so as to keep it as simple as possible. We'll also want the streak information! This can be determined only by the HabitResult array, but we'll throw it all together to give us the following:

export interface HabitTrackerTemplateData {
  weekNames: string[],
  data: HabitTrackerData,
  maxSuccessStreak: number,
  maxFailureStreak: number
}

We've hardly written anything in the way of implementation at this point, but we now have a solid data model that we're expressing in our TypeScript code! The rest will start to fall into place at this point!

Part 2: Converting From `CalendarProps` to `HabitTrackerTemplateData`

Let's start with the following:

export function createHabitTrackerTemplateData(props: CalendarProps): HabitTrackerTemplateData {
  //...
}

So, here's the cool thing about our solution - at this point, we definitely could skip ahead to steps 3 && 4 and leave this unimplemented! (Maybe have it return an example of the desired data)

This is all benefit of the 'work' we did in step 1 to set up our data models. Since we're here though, we might as well set up the problem.

Since we'd like to have general confidence in our solution, we might as well start with a unit test to assert that our implementation on this function is correct:

import {
  CalendarProps,
  createHabitTrackerTemplateData,
  HabitTrackerTemplateData,
} from './calendar.utils';

interface TestParams {
  input: CalendarProps;
  output: HabitTrackerTemplateData;
}

function testCreatingTemplateData(
  { input, output }: TestParams
) {
  expect(
    createHabitTrackerTemplateData(input)
  ).toEqual(output);
}

describe('createHabitTrackerTemplateData()', () => {
  test('known example', () => {
    testCreatingTemplateData({
      input: {
        startDay: {
          month: 'February',
          date: 4,
          dayOfTheWeek: 'Thursday'
      },
      endDay: {
        month: 'March',
        date: 21,
        dayOfTheWeek: 'Sunday'
      },
      results: ['success', 'failure', 'success', 'success'],
    },
    output: {
      weekNames: [
        'week-1',
        'week-2',
        'week-3',
        'week-4',
        'week-5',
        'week-6',
        'week-7',
        'week-8',
      ],
      data: { /* much too big to show here */ },
      maxSuccessStreak: 2,
      maxFailureStreak: 1
    }
  });
});

This will give us a red/green check to run while we fill out our implementation!

When it comes to our actual implementation, let's start with the streak information. Streak info is a function of the results array, so we can create a smaller piece of functionality that focuses only on this:

function determineStreakInfo(
  results: HabitResult[]
): { maxSuccessStreak: number; maxFailureStreak: number } {
  let maxSuccessStreak = 0;
  let maxFailureStreak = 0;
  const currentStreak: {
    kind: HabitResult;
    count: number
  } = { kind: 'success', count: 0 };
  for (const result of results) {
    if (result === currentStreak.kind) {
      currentStreak.count++;
    } else {
      currentStreak = { kind: result, count: 1 };
    }
    if (result === 'success' && currentStreak.count > maxSuccessStreak) {
      maxSuccessStreak = currentStreak.count;
    }
    if (result === 'failure' && currentStreak.count > maxFailureStreak) {
      maxFailureStreak = currentStreak.count;
    }
  }
  return { maxFailureStreak, maxSuccessStreak };
}

Next, we'll need to build our HabitTrackerData object. Thinking through this problem, the general algorithm here would be:

start with a pointer at the provided first day
create a 'reverse' pointer and loop backwards one day at a time until you hit a 'Sunday' (the first day of the week), adding 'out of bounds' days to our object as we go.
Go back to our original pointer, and advance this pointer forward one day at a time until we hit the provided end day, adding either the data from the provided results array, or 'no result yet' if the array isn't large enough to include the given day.
Continue to advance the pointer one day at a time, until we hit a 'Saturday' (last day of the week), adding 'out of bounds' days to our object as we go.

All the while, keeping a record of the # week we're on, and advancing that when the pointer goes from a 'Saturday' to a 'Sunday'.

This is a fairly messy implementation (most implementations involving dates are!) but we can make it happen! Let's start with some utilities we know we'll need based on this implementation:

a function that takes a CalendarDate and returns the previous CalendarDate
a function that takes a CalendarDate and returns the next CalendarDate

To create these properly, we'll also need a map of the number of days per month, as it will affect the date when going backwards, and when to switch to the next month when going forwards:

const daysPerMonth: Record<Month, number> = {
  January: 31,
  February: 28,
  March: 31,
  April: 30,
  May: 31,
  June: 30,
  July: 31,
  August: 31,
  September: 30,
  October: 31,
  November: 30,
  December: 31,
};
function nextMonth(month: Month): Month {
  if (month === 'December') {
    return 'January';
  }
  return months[months.indexOf(month) + 1];
}
function nextDayOfWeek(day: DayOfTheWeek): DayOfTheWeek {
  if (day === 'Saturday') {
    return 'Sunday';
  }
  return daysOfTheWeek[daysOfTheWeek.indexOf(day) + 1];
}
function nextCalendarDay(calendarDay: CalendarDate): CalendarDate {
  if (calendarDay.date === daysPerMonth[calendarDay.month]) {
    return {
      month: nextMonth(calendarDay.month),
      date: 1,
      dayOfTheWeek: nextDayOfWeek(calendarDay.dayOfTheWeek),
    };
  }
  return {
    month: calendarDay.month,
    date: calendarDay.date + 1,
    dayOfTheWeek: nextDayOfWeek(calendarDay.dayOfTheWeek),
  };
}
function previousMonth(month: Month): Month {
  if (month === 'January') {
    return 'December';
  }
  return months[months.indexOf(month) - 1];
}
function previousDate(calendarDay: CalendarDate): number {
  if (calendarDay.date === 1) {
    return daysPerMonth[previousMonth(calendarDay.month)];
  }
  return calendarDay.date - 1;
}
function previousDay(day: DayOfTheWeek): DayOfTheWeek {
  if (day === 'Sunday') {
    return 'Saturday';
  }
  return daysOfTheWeek[daysOfTheWeek.indexOf(day) - 1];
}
function previousCalendarDay(calendarDay: CalendarDate): CalendarDate {
  return {
    dayOfTheWeek: previousDay(calendarDay.dayOfTheWeek),
    date: previousDate(calendarDay),
    month:
      calendarDay.date === 1
        ? previousMonth(calendarDay.month)
        : calendarDay.month,
  };
}

As complex as this is already - we're still not accommodating for leap years... I'm not going to sweat it for now, but! We could in the future (maybe for 2024!) adjust our map of months to days in the month to instead point to a function that returns a number - the idea being that the function would take the year as a parameter, and we could then use the Gregorian calendar logic to determine the proper number of days for February based on that (the function for all other months would ignore any parameters and return the value they current point to).

And now my implementation:

export function createHabitTrackerTemplateData({
  startDay,
  endDay,
  results,
}: CalendarProps): HabitTrackerTemplateData {
  const weekNames = ['week-1'];

  // go backwards until you hit a 'Sunday'
  const firstWeekOutOfBoundsDates = {} as any;
  let firstWeekPointer = { ...startDay };
  while (firstWeekPointer.dayOfTheWeek !== 'Sunday') {
    firstWeekPointer = previousCalendarDay(firstWeekPointer);
    firstWeekOutOfBoundsDates[firstWeekPointer.dayOfTheWeek] = {
      month: firstWeekPointer.month,
      date: firstWeekPointer.date,
      result: 'out of bounds',
    } as const;
  }

  // go forwards day by day, populating from the provided
  // `results` array, until you hit the provided `endDay`
  const data: Record<
    string,
    Record<DayOfTheWeek, { month: Month; date: number; result: DisplayResult }>
  > = {
    'week-1': { ...firstWeekOutOfBoundsDates } as any,
  };
  let dayIndex = 0;
  let dayPointer = { ...startDay };
  let weekCounter = 0;
  while (dayPointer.date !== endDay.date || dayPointer.month !== endDay.month) {
    data[`week-${weekCounter + 1}`][dayPointer.dayOfTheWeek] = {
      month: dayPointer.month,
      date: dayPointer.date,
      result: results[dayIndex] || 'no result yet',
    };
    dayPointer = nextCalendarDay(dayPointer);
    dayIndex++;
    if (dayPointer.dayOfTheWeek === 'Sunday') {
      weekCounter++;
      const newWeekName = `week-${weekCounter + 1}`;
      weekNames.push(newWeekName);
      data[newWeekName] = {} as any;
    }
  }
  data[`week-${weekCounter + 1}`][dayPointer.dayOfTheWeek] = {
    month: dayPointer.month,
    date: dayPointer.date,
    result: results[dayIndex] || 'no result yet',
  };

  // keep going forwards until you hit a `Saturday`
  while (dayPointer.dayOfTheWeek !== 'Saturday') {
    dayPointer = nextCalendarDay(dayPointer);
    data[`week-${weekCounter + 1}`][dayPointer.dayOfTheWeek] = {
      month: dayPointer.month,
      date: dayPointer.date,
      result: 'out of bounds',
    };
  }
  return {
    data,
    weekNames,
    ...determineStreakInfo(results)
  };
}

I'm not crazy with this implementation - it certainly doesn't pass a 5 second rule (maybe not even a 5 minute rule...) but our test is going green with this in place, which gives me the general confidence to proceed.

The cool thing here is we have some great general utility functions available now - that actually could just as easily be used in Angular or any other JS framework!

Part 3: Creating a React Component

Breaking down our React Component, we'll want to:

define our props as the HabitTrackerProps type we created in the first part
call our createHabitTrackerTemplateData(), passing in those props, and destructuring out the properties
create our component template in tsx, by map()ing over all weeknames, and then inside of that map()ing over all days of the week, creating a <div> for each day
if the day was a 'success', set the background image to that div to the url of a green check - or a red x if it was a 'failure'.
Add streak information at the bottom of all these divs!

Here's how that looks in practice:

const GREEN_CHECK_URL = 'some_image_url';
const RED_X_URL = 'some_image_url';

export function Calendar(props: CalendarProps) {
  const {
    weekNames,
    data,
    maxSuccessStreak,
    maxFailureStreak,
  } = createHabitTrackerTemplateData(props);
  return (
    <>
      <div>
        {weekNames.map((weekName) =>
          daysOfTheWeek.map((dayOfTheWeek) => {
            const { date, result } = data[weekName][dayOfTheWeek];
            return (
              <div
                key={`${weekName}|${dayOfTheWeek}`}
                style={{
                  backgroundImage: `url(${
                    result === 'success'
                      ? GREEN_CHECK_URL
                      : result === 'failure'
                      ? RED_X_URL
                      : undefined
                  })`,
                  backgroundSize: '100%',
                }}
              >
                <div>
                  {date}
                </div>
              </div>
            );
          })
        )}
      </div>
      <h2>
        Max Success Streak: {maxSuccessStreak}
      </h2>
      <h2>
        Max Failure Streak: {maxFailureStreak}
      </h2>
    </>
  );
}

Step 4: Add Tailwind Styles

At this point, we've got solid bones to our html, but actually a relatively un-usable presentation so far. We'll use Tailwind as a style system to get this up to at least passable quickly!

Here's the highlights of the tailwind goals for this component:

create a 7-column grid - to present our calendar
make the size of our <div>'s reactive to the screen size, by setting a small default size, but increasing this (with the md: modifier) once the screen size passes the "medium" threshold
Add borders to our day <div>'s - making them twice as thick on the edges to make the display consistant.
Add rounded corners to the borders on the corners of our calendar
Put the inner <div> with our # date in the top-left of the day <div> and give it a circle-appearance.
Center the streak information headers

Check out the source code of this stackblitz for the details on the implementation!

Conclusion && Potential Next Steps

And there we go! From nothing to something semi-cool :). As a developer with limited React experience, I'm pretty enthused in general regarding the simplicity of React.

An obvious next step would be to read our HabitTrackerProps data from some network call - or even better to push change events from the server to our client! I've got some ideas for this in the pipes...

Another interesting way to take this further would be to introduce Nx to the project. Currently, I'm intentionally using create-react-app to try and understand the general "React way" of doing things. But being able to introduce this code (especially the calendar.utils.ts file) would be great in terms of pretty easily getting up an Angular version of this component!

Also cool would be to share the entire React component as well - making it available for me to run it in a stand-alone app, but also bring it into my other sites as needed!

DEV Community: Zack DeRose

Launch Nx Week Recap!!

Nx 18.0 && Project Crystal

Conference Talk: Project Crystal

Conference Talk: Project Crystal + .NET in Action

New Plugin: @nx/nuxt

Nx Agents Launched

Conference Talk: Nx Agents Walkthrough: Effortlessly Fast CI Built for Monorepos

Conference Talk: Solving E2E Tests

Tusky

Nx Release Is Stable

Conference Talk: Releasing Nx Release

Wrapping up

Learn more

Nx 17.2 Update!!

Nx Closes In On 4 Million Weekly NPM Downloads!!

New Simplified Project Configuration On the Way

Rust for Speed, Typescript for extensibility

Module Federation Updates

Nx Release Updates

Angular 17 (AND NgRx 17) Support

Smart Monorepos - Fast CI

New Canary Releases

Upcoming Release Livestream

Automatically Update Nx

Wrapping up

Learn more

More Nx Release Notes:

Nx 17.0 Has Landed!!!

It's a Vue-tiful Day for Nx!

Enhancements to Module Federation Support

NEW: Typesafe Config

Better Typesafety Across Modules

NEW GENERATOR: Federate ANYTHING.

Managing Module Versions

More Consistent Generator Paths

The NEW Nx AI ChatBot

More Seamless Integration With Nx Cloud

nx.json Simplification

Nx Repo Dog-Fooding Nx Workflows

Task Graphing Improvements

@nx/linter Renamed to @nx/eslint

New Experimental Feature: Nx Release

Experimental: Nx Project Inference API v2

20k Github Stars!!

How to Update Nx

Wrapping up

Learn more

More Nx Release Notes:

Nx 16.8 Release!!!

Nx Community News!

NEW PROJECT GENERATOR BEHAVIOR: Project Creation Paths and Names in Nx Generators

Packaging TypeScript Libraries - Secondary Entrypoints, ESM, CJS

High Performance TypeScript Compilation: Introducing Batch Mode & Rust-based Dependency Resolution

NEW Nx PLUGIN: Playwright

NEW INTEGRATION: Netlify's Improved Monorepo Experience

NEW Nx CONSOLE FEATURE: Interactive Graph Functionality

ENHANCEMENT: Storybook Support for Interaction Testing

NEW GENERATOR: convert-to-monorepo

DOCS ENHANCEMENT: Third-Party Plugin Quality Indicators

DOCS ENHANCEMENT: Redesigned Intro & Examples

NEW GENERATOR: ESLint Flat Config

New Nx Cloud Overview Video

Nx Conf Coming Up

Wrap Up

Learn more

More Nx Release Notes:

Nx 16.5 Release!!

Targetting Tasks By Tags

NextJS 13 Support

New Nx Recipes!!!

Angular 16 Support And Migrations

New verdaccio support!

Create your own CLI with Nx

New externalDependencies Input Type

New @nx/dependency-checks EsLint Rule

Nx Goes Brrrrrr

Nx Console Revamped

Nx Changelog Launched

Wrap Up

`nx.json` Simplification

`@nx/linter` Renamed to `@nx/eslint`

New `verdaccio` support!

New `externalDependencies` Input Type

New `@nx/dependency-checks` EsLint Rule

Idempotency Added to the `lerna publish from-git` Command

`lerna run` Can Run Multiple Scripts In a Single Command

New `--include-private` Option Added To `lerna publish`

The `E = mc^2` of State Management