tessl/npm-nx--js

The JS plugin for Nx contains executors and generators that provide the best experience for developing JavaScript and TypeScript projects.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Executors

Name: tessl/npm-nx--js
Author: tessl

@nx/js provides high-performance executors for building, running, and managing JavaScript/TypeScript projects with full Nx integration including caching, dependency graph awareness, and incremental builds.

Capabilities

TypeScript Compiler (tsc)

Builds TypeScript projects using the TypeScript compiler with support for incremental compilation and batch processing.

/**
 * Builds a TypeScript project using the TypeScript compiler
 * @param options - TypeScript compilation options
 * @param context - Nx executor context
 * @returns AsyncGenerator yielding build results with success status
 */
function tscExecutor(
  options: ExecutorOptions,
  context: ExecutorContext
): AsyncGenerator<{ success: boolean; options?: Record<string, any> }>;

/**
 * Batch executor for building multiple TypeScript projects efficiently
 * @param taskGraph - Graph of tasks to execute
 * @param inputs - Input options for each task
 * @param overrides - Override options for all tasks
 * @param context - Nx executor context
 * @returns AsyncGenerator yielding batch execution results
 */
function tscBatchExecutor(
  taskGraph: TaskGraph,
  inputs: Record<string, ExecutorOptions>,
  overrides: ExecutorOptions,
  context: ExecutorContext
): AsyncGenerator<BatchExecutorTaskResult>;

interface BatchExecutorTaskResult {
  success: boolean;                        // Operation success status
  error?: string;                          // Error message if failed
  terminalOutput?: string;                 // Terminal output from the task
  startTime?: number;                      // Task start timestamp
  endTime?: number;                        // Task end timestamp
}

interface TaskGraph {
  tasks: Record<string, Task>;             // Task definitions by ID
  dependencies: Record<string, string[]>;  // Task dependencies
  roots: string[];                         // Root task IDs
}

interface Task {
  id: string;                              // Unique task identifier
  target: { project: string; target: string; configuration?: string };
  projectRoot: string;                     // Project root directory
  overrides: Record<string, any>;          // Task option overrides
}

interface ExecutorOptions {
  assets: Array<AssetGlob | string>;    // Static assets to copy
  main: string;                         // Main entry-point file (required)
  rootDir?: string;                     // Root directory for compilation
  outputPath: string;                   // Output directory (required)
  tsConfig: string;                     // TypeScript configuration file (required)
  generateExportsField?: boolean;       // Update package.json exports field
  additionalEntryPoints?: string[];     // Additional entry-points for exports
  watch: boolean;                       // Enable watch mode
  clean?: boolean;                      // Clean output before build
  transformers: TransformerEntry[];     // TypeScript transformer plugins
  external?: 'all' | 'none' | string[]; // External dependencies (deprecated)
  externalBuildTargets?: string[];      // External build target names
  generateLockfile?: boolean;           // Generate matching lockfile
  generatePackageJson?: boolean;        // Generate package.json in output
  includeIgnoredAssetFiles?: boolean;   // Include ignored files in assets
}

Usage Example:

// In project.json
{
  "targets": {
    "build": {
      "executor": "@nx/js:tsc",
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputPath": "dist/libs/my-lib",
        "main": "libs/my-lib/src/index.ts",
        "tsConfig": "libs/my-lib/tsconfig.lib.json",
        "generatePackageJson": true,
        "assets": ["libs/my-lib/*.md"]
      }
    }
  }
}

SWC Compiler

Builds TypeScript/JavaScript projects using SWC for faster compilation with optional type checking.

/**
 * Builds a project using SWC for fast compilation
 * @param options - SWC compilation options
 * @param context - Nx executor context
 * @returns AsyncGenerator yielding build results with success status
 */
function swcExecutor(
  options: SwcExecutorOptions,
  context: ExecutorContext
): AsyncGenerator<{ success: boolean; options?: Record<string, any> }>;

interface SwcExecutorOptions extends ExecutorOptions {
  skipTypeCheck?: boolean;              // Skip TypeScript type checking
  swcExclude?: string[];               // SWC glob/regex patterns to exclude (deprecated)
}

Usage Example:

// In project.json
{
  "targets": {
    "build": {
      "executor": "@nx/js:swc",
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputPath": "dist/libs/my-lib",
        "main": "libs/my-lib/src/index.ts",
        "tsConfig": "libs/my-lib/tsconfig.lib.json",
        "skipTypeCheck": false,
        "generatePackageJson": true
      }
    }
  }
}

Node Application Runner

Executes Node.js applications with debugging support, automatic rebuilding, and process management.

/**
 * Executes a Node.js application with debugging and watch capabilities
 * @param options - Node execution options
 * @param context - Nx executor context
 * @returns AsyncGenerator yielding execution results
 */
function nodeExecutor(
  options: NodeExecutorOptions,
  context: ExecutorContext
): AsyncGenerator<{ success: boolean; options?: Record<string, any> }>;

enum InspectType {
  Inspect = 'inspect',
  InspectBrk = 'inspect-brk',
}

interface NodeExecutorOptions {
  inspect: boolean | InspectType;       // Debug inspection settings (default: 'inspect')
  runtimeArgs: string[];                // Extra arguments for node process
  args: string[];                       // Extra arguments for the application
  waitUntilTargets: string[];           // Targets to complete before starting
  buildTarget: string;                  // Build target for the app (required)
  buildTargetOptions: Record<string, any>; // Additional build target options
  host: string;                         // Debug host (default: 'localhost')
  port: number;                         // Debug port (default: 9229)
  watch?: boolean;                      // Enable file watching (default: true)
  debounce?: number;                    // Restart delay in ms (default: 500)
  runBuildTargetDependencies?: boolean; // Run build dependencies first
}

Usage Example:

// In project.json
{
  "targets": {
    "serve": {
      "executor": "@nx/js:node",
      "options": {
        "buildTarget": "my-app:build",
        "inspect": "inspect",
        "port": 9229,
        "watch": true,
        "debounce": 1000
      }
    }
  }
}

Verdaccio Local Registry

Starts a local npm registry using Verdaccio for local package development and testing.

/**
 * Starts a Verdaccio local package registry
 * @param options - Verdaccio configuration options
 * @param context - Nx executor context
 * @returns Promise resolving to success status and port number
 */
function verdaccioExecutor(
  options: VerdaccioExecutorSchema,
  context: ExecutorContext
): Promise<{ success: boolean; port: number }>;

interface VerdaccioExecutorSchema {
  location: 'global' | 'user' | 'project' | 'none'; // npm config location (default: 'user')
  storage?: string;                     // Custom storage directory path
  port?: number;                        // Registry port (required)
  listenAddress: string;                // Listen address (default: 'localhost')
  config?: string;                      // Custom Verdaccio config file
  clear?: boolean;                      // Clear storage before start (default: true)
  scopes?: string[];                    // Package scopes to configure
}

Usage Example:

// In project.json
{
  "targets": {
    "local-registry": {
      "executor": "@nx/js:verdaccio",
      "options": {
        "port": 4873,
        "location": "user",
        "clear": true,
        "scopes": ["@myorg"]
      }
    }
  }
}

Package Publisher

Publishes packages to npm registry with support for different package managers and authentication (internal use only).

/**
 * Publishes a package to npm registry
 * @param options - Publishing configuration
 * @param context - Nx executor context
 * @returns Promise resolving to success status
 */
function runExecutor(
  options: PublishExecutorSchema,
  context: ExecutorContext
): Promise<{ success: boolean }>;

interface PublishExecutorSchema {
  packageRoot?: string;                 // Root directory with package manifest
  registry?: string;                    // Target npm registry URL
  tag?: string;                         // Distribution tag for published package
  otp?: number;                         // One-time password for 2FA
  dryRun?: boolean;                     // Run without actually publishing
  access?: 'public' | 'restricted';     // Package access level
  firstRelease?: boolean;               // Indicates first release
}

Note: This executor is hidden and should not be invoked directly. Use nx release publish instead.

Copy Workspace Modules

Copies workspace modules into the output directory for containerization and deployment.

/**
 * Copies workspace modules into output directory after build
 * @param schema - Copy configuration options
 * @param context - Nx executor context
 * @returns Promise resolving to success status
 */
function copyWorkspaceModules(
  schema: CopyWorkspaceModulesOptions,
  context: ExecutorContext
): Promise<{ success: boolean }>;

interface CopyWorkspaceModulesOptions {
  buildTarget: string;                  // Build target that produces output (required)
  outputPath?: string;                  // Output path (usually inferred from build target)
}

Usage Example:

// In project.json
{
  "targets": {
    "docker-prep": {
      "executor": "@nx/js:copy-workspace-modules",
      "options": {
        "buildTarget": "my-app:build"
      }
    }
  }
}

Prune Lockfile

Creates pruned lockfiles for deployments by including only dependencies needed by the built application.

/**
 * Creates a pruned lockfile based on project dependencies
 * @param schema - Prune lockfile configuration
 * @param context - Nx executor context
 * @returns Promise resolving to success status
 */
function pruneLockfileExecutor(
  schema: PruneLockfileOptions,
  context: ExecutorContext
): Promise<{ success: boolean }>;

interface PruneLockfileOptions {
  buildTarget: string;                  // Build target that produces output (required)
  outputPath?: string;                  // Output path (usually inferred from build target)
}

Usage Example:

// In project.json
{
  "targets": {
    "docker-lockfile": {
      "executor": "@nx/js:prune-lockfile",
      "options": {
        "buildTarget": "my-app:build"
      }
    }
  }
}

Common Types

interface FileInputOutput {
  input: string;                        // Source file path
  output: string;                       // Destination file path
}

interface AssetGlob extends FileInputOutput {
  glob: string;                         // Glob pattern for matching files
  ignore?: string[];                    // Patterns to ignore
  dot?: boolean;                        // Include dotfiles
  includeIgnoredFiles?: boolean;        // Include ignored files
}

interface TransformerPlugin {
  name: string;                         // Transformer plugin name
  options: Record<string, unknown>;     // Plugin configuration options
}

type TransformerEntry = string | TransformerPlugin;

interface NormalizedExecutorOptions extends ExecutorOptions {
  rootDir: string;                      // Resolved root directory
  projectRoot: string;                  // Project root directory
  mainOutputPath: string;               // Resolved main output path
  generatePackageJson: boolean;         // Whether to generate package.json
  files: Array<FileInputOutput>;        // Resolved file mappings
  root?: string;                        // Workspace root
  sourceRoot?: string;                  // Source root directory
}

Executor Patterns

Watch Mode Support

Many executors support watch mode for development:

// Watch mode automatically rebuilds when files change
{
  "executor": "@nx/js:tsc",
  "options": {
    "watch": true,
    // ... other options
  }
}

Asset Handling

Executors can copy static assets alongside compiled code:

{
  "executor": "@nx/js:tsc",
  "options": {
    "assets": [
      "libs/my-lib/*.md",                    // Simple glob
      {
        "input": "libs/my-lib/assets",       // Source directory
        "output": "./assets",                // Destination directory
        "glob": "**/*"                       // File pattern
      }
    ]
  }
}

Batch Execution

The TypeScript executor supports batch processing for improved performance:

{
  "executor": "@nx/js:tsc",
  "options": {
    // Regular options
  },
  "batchImplementation": "@nx/js:tsc"      // Enable batch processing
}

External Dependencies

Control which dependencies are bundled vs. treated as external:

{
  "executor": "@nx/js:tsc",
  "options": {
    "externalBuildTargets": ["build-deps"], // External build targets
    "generatePackageJson": true              // Include dependencies in package.json
  }
}

Install with Tessl CLI