Deprecating Custom Tasks Runner
The Custom Task Runners API was created many years ago and has not been supported for several years. It was developed before we introduced a formal method for extending Nx through plugins. The API potentially allows modifications to the lifecycle of the Nx command execution, which breaks important invariants that Nx depends on. The new API leverages the plugins API for better performance and functionality.
This page guides you on how to migrate off the now deprecated Custom Task Runner API for both:
- achieving self-hosted remote caching
- implementing pre/post processing logic when running tasks
Self-Hosted Remote Cache
Nx offers different ways to enable self-hosted remote caching for your workspace that can be used starting with Nx version 19.8 and higher. You can either use our official Nx packages that come with ready-to-use adapters for AWS S3, GCP, Azure and more, or build your own cache server by following the Nx Remote Caching OpenAPI spec.
Read more in our documentation.
Migrating from @nx-aws-plugin
If you've been using the @nx-aws-plugin/nx-aws-cache community plugin, you should be easily able to migrate to the free Nx S3 cache plugin. The specific modification depends on your repository's configuration.
The following is one example, where a custom tasks runner configuration in nx.json will be removed:
1{
2 "tasksRunnerOptions": {
3 "default": {
4 "runner": "@nx-aws-plugin/nx-aws-cache",
5 "options": {
6 "awsAccessKeyId": "key",
7 "awsSecretAccessKey": "secret",
8 "awsForcePathStyle": true,
9 "awsEndpoint": "http://custom",
10 "awsBucket": "my-bucket",
11 "awsRegion": "eu-central-1",
12 "encryptionFileKey": "key"
13 }
14 }
15 }
16}
17And replaced with:
1{
2 "s3": {
3 "accessKeyId": "key",
4 "secretAccessKey": "secret",
5 "forcePathStyle": true,
6 "endpoint": "http://custom",
7 "bucket": "my-bucket",
8 "region": "eu-central-1",
9 "encryptionFileKey": "key",
10 "localMode": "read-write"
11 }
12}
13The API documentation for each plugin describes the available options.
The preTasksExecution and postTasksExecution hooks
Starting with Nx 20.4, a dedicated plugin-based API has been introduced that allows you to safely hook into the task running lifecycle. This new approach provides pre and post execution hooks without compromising Nx's internal operations. For comprehensive documentation on this feature, see Hook into the Task Running Lifecycle.
Let's look into some concrete examples of how you can migrate from the previous custom task runners to this new API.
Before: Custom Tasks Runner Version
Let's imagine that you have implemented a custom task runner as follows:
1function serializeTasksResults(taskResults: { [taskId: string]: TaskResult }) {
2 // ...
3}
4
5function validateEnv() {
6 // ...
7}
8
9export default async function customTasksRunner(tasks, options, context) {
10 if (process.env.QA_ENV) {
11 process.env.NX_SKIP_NX_CACHE = 'true';
12 }
13 if (!validateEnv()) {
14 throw new Error('Env is not set up correctly');
15 }
16 const allTaskResults = {};
17 const lifeCycle = {
18 endTasks(taskResults) {
19 taskResults.forEach((tr) => {
20 allTaskResults[tr.task.id] = tr;
21 });
22 },
23 };
24 const ret = await defaultTasksRunner(
25 tasks,
26 { ...options, lifeCycle },
27 context
28 );
29 if (options.reportAnalytics) {
30 await fetch(process.env.DATACAT_API, {
31 method: 'POST',
32 headers: {
33 'Content-Type': 'application/json',
34 },
35 body: serializeTasksResults(allTaskResults),
36 });
37 }
38 return ret;
39}
40And let's imagine you configured it in nx.json as follows:
1{
2 "tasksRunnerOptions": {
3 "default": {
4 "runner": "npm-package-with-custom-tasks-runner",
5 "options": {
6 "reportAnalytics": true
7 }
8 }
9 }
10}
11After: Using the New API
The new API includes preTasksExecution and postTasksExecution hooks that plugins can register. These hooks do not affect task execution and cannot violate any invariants.
The custom task runner above can be implemented as follows:
1function serializeTasksResults(taskResults: { [taskId: string]: TaskResult }) {
2 // task results contain timings and status information useful for gathering analytics
3}
4
5function validateEnv() {
6 // ...
7}
8
9// context contains workspaceRoot and nx.json configuration
10export async function preTasksExecution(options: any, context) {
11 if (process.env.QA_ENV) {
12 process.env.NX_SKIP_NX_CACHE = 'true';
13 }
14 if (!validateEnv()) {
15 throw new Error('Env is not set up correctly');
16 }
17}
18
19// context contains workspaceRoot, nx.json configuration, and task results
20export async function postTasksExecution(options: any, context) {
21 if (options.reportAnalytics) {
22 await fetch(process.env.DATACAT_API, {
23 method: 'POST',
24 headers: {
25 'Content-Type': 'application/json',
26 },
27 body: serializeTasksResults(context.taskResults),
28 });
29 }
30}
31Because it's a regular plugin, it can be configured as follows in nx.json:
1{
2 "plugins": [
3 {
4 "plugin": "npm-package-with-the-plugin",
5 "options": {
6 "reportAnalytics": true
7 }
8 }
9 ]
10}
11As with all plugin hooks, the preTasksExecution and postTasksExecution hooks must be exported so that they load properly when the "npm-package-with-the-plugin" is initialized.
Multiple Tasks Runners
You can implement multiple tasks runners using the new hooks.
Imagine you have the following nx.json:
1{
2 "tasksRunnerOptions": {
3 "a": {
4 "runner": "package-a"
5 },
6 "b": {
7 "runner": "package-b"
8 }
9 }
10}
11You can replace it with two plugins:
1{
2 "plugins": [
3 {
4 "plugin": "package-a"
5 },
6 {
7 "plugin": "package-b"
8 }
9 ]
10}
11Simply add a condition to your hooks as follows:
1export async function preTasksExecution() {
2 if (process.env.RUNNER != 'a') return;
3}
4
5export async function postTasksExecution(options, tasksResults) {
6 if (process.env.RUNNER != 'a') return;
7}
8You can then choose which hooks to use by setting the RUNNER env variable.
Passing Options
You can no longer augment options passed to the default tasks runner, so instead you need to set env variables in the preTasksExecution hook.
Composing Plugins
Implementing hooks in plugins offers several advantages. It allows multiple plugins to be loaded simultaneously, enabling a clean separation of concerns.
Keeping State Across Command Invocations
By default, every plugin initiates a long-running process, allowing you to maintain state across command invocations, which can be very useful for advanced analytics.
Unhandled Custom Tasks Runner Use Cases?
If you have a use case that the new API doesn't handle, please open an issue.