tessl/npm-nx--workspace

The Workspace plugin contains executors and generators that are useful for any Nx workspace and serves as a foundation for other plugins.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

TypeScript Configuration

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

Tools for reading, parsing, and managing TypeScript configuration files across the workspace. These utilities handle tsconfig.json files and provide workspace-aware TypeScript configuration management.

Capabilities

TypeScript Config Reading

Read and parse TypeScript configuration files with full compiler options.

/**
 * Read and parse a TypeScript configuration file
 * @param tsConfigPath - Path to the tsconfig.json file
 * @returns Parsed TypeScript configuration with resolved options
 */
function readTsConfig(tsConfigPath: string): ParsedCommandLine;

Usage Example:

import { readTsConfig } from "@nx/workspace";

// Read project-specific tsconfig
const config = readTsConfig("./apps/my-app/tsconfig.json");
console.log("Compiler options:", config.options);
console.log("Source files:", config.fileNames);
console.log("Project references:", config.projectReferences);

// Read root workspace tsconfig
const rootConfig = readTsConfig("./tsconfig.base.json");
console.log("Base paths:", rootConfig.options.baseUrl);
console.log("Path mapping:", rootConfig.options.paths);

Root Config Discovery

Find and manage root TypeScript configuration files in the workspace.

/**
 * Get root tsconfig path in file tree, preferring tsconfig.base.json
 * @param tree - The file system tree
 * @returns Path to root tsconfig or default path
 */
function getRootTsConfigPathInTree(tree: Tree): string | null;

/**
 * Get root tsconfig filename from filesystem
 * @returns Filename of root tsconfig or null if not found
 */
function getRootTsConfigFileName(): string | null;

Usage Examples:

import { Tree } from "@nx/devkit";
import { getRootTsConfigPathInTree, getRootTsConfigFileName } from "@nx/workspace";

// In a generator using file tree
function myGenerator(tree: Tree) {
  const rootTsConfig = getRootTsConfigPathInTree(tree);
  if (rootTsConfig) {
    console.log("Root tsconfig found at:", rootTsConfig);
  }
}

// From filesystem
const rootConfigFile = getRootTsConfigFileName();
if (rootConfigFile) {
  console.log("Root config file:", rootConfigFile); // "tsconfig.base.json" or "tsconfig.json"
}

Relative Path Resolution

Calculate relative paths to root TypeScript configuration for project references.

/**
 * Get relative path from target path to root tsconfig
 * @param tree - The file system tree
 * @param targetPath - Target path to calculate from
 * @returns Relative path to root tsconfig
 */
function getRelativePathToRootTsConfig(tree: Tree, targetPath: string): string;

Usage Example:

import { Tree } from "@nx/devkit";
import { getRelativePathToRootTsConfig } from "@nx/workspace";

function setupProjectTsConfig(tree: Tree, projectPath: string) {
  const relativePath = getRelativePathToRootTsConfig(tree, projectPath);
  
  // Create project tsconfig that extends root config
  const projectTsConfig = {
    extends: relativePath,
    compilerOptions: {
      outDir: "../../dist/out-tsc"
    },
    include: ["src/**/*"],
    exclude: ["src/**/*.spec.ts"]
  };
  
  tree.write(`${projectPath}/tsconfig.json`, JSON.stringify(projectTsConfig, null, 2));
}

AST Node Discovery

Find TypeScript AST nodes by syntax kind for advanced code analysis.

/**
 * Find AST nodes by TypeScript SyntaxKind
 * @param node - Root AST node to search
 * @param kind - SyntaxKind or array of SyntaxKinds to find
 * @param max - Maximum number of nodes to find (default: Infinity)
 * @returns Array of matching AST nodes
 */
function findNodes(
  node: Node, 
  kind: SyntaxKind | SyntaxKind[], 
  max?: number
): Node[];

Usage Example:

import { findNodes, readTsConfig } from "@nx/workspace";
import { SyntaxKind, createSourceFile, ScriptTarget } from "typescript";

// Parse TypeScript file and find function declarations
const sourceCode = `
  export function myFunction() {}
  export class MyClass {}
  export const myConst = 42;
`;

const sourceFile = createSourceFile(
  "example.ts", 
  sourceCode, 
  ScriptTarget.Latest
);

// Find all function declarations
const functions = findNodes(sourceFile, SyntaxKind.FunctionDeclaration);
console.log(`Found ${functions.length} functions`);

// Find multiple node types
const exports = findNodes(sourceFile, [
  SyntaxKind.FunctionDeclaration,
  SyntaxKind.ClassDeclaration, 
  SyntaxKind.VariableStatement
]);
console.log(`Found ${exports.length} export statements`);

Configuration File Management

Typical Workspace Structure

workspace-root/
├── tsconfig.base.json          # Root configuration with path mappings
├── apps/
│   └── my-app/
│       ├── tsconfig.json       # Extends root, app-specific options
│       └── tsconfig.app.json   # Build configuration
└── libs/
    └── shared/
        ├── tsconfig.json       # Extends root, lib-specific options
        └── tsconfig.lib.json   # Build configuration

Path Mapping Management

The utilities help manage TypeScript path mappings for monorepo imports:

// Root tsconfig.base.json typically contains:
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@my-org/shared": ["libs/shared/src/index.ts"],
      "@my-org/ui": ["libs/ui/src/index.ts"]
    }
  }
}

Advanced Usage

Custom Config Processing

import { readTsConfig } from "@nx/workspace";

function analyzeProjectConfig(projectPath: string) {
  const config = readTsConfig(`${projectPath}/tsconfig.json`);
  
  // Analyze compiler options
  const hasStrictMode = config.options.strict === true;
  const targetVersion = config.options.target;
  
  // Check for custom paths
  const customPaths = config.options.paths || {};
  const hasPathMapping = Object.keys(customPaths).length > 0;
  
  return {
    strict: hasStrictMode,
    target: targetVersion,
    hasPathMappings: hasPathMapping,
    sourceFiles: config.fileNames.length
  };
}

Types

interface ParsedCommandLine {
  options: CompilerOptions;
  fileNames: string[];
  projectReferences?: ProjectReference[];
  typeAcquisition?: TypeAcquisition;
  raw?: any;
  errors: Diagnostic[];
  wildcardDirectories?: MapLike<WatchDirectoryFlags>;
  compileOnSave?: boolean;
}

interface Node {
  kind: SyntaxKind;
  getChildren(): Node[];
  // ... other TypeScript Node properties
}

enum SyntaxKind {
  FunctionDeclaration,
  ClassDeclaration,
  VariableStatement,
  // ... other TypeScript syntax kinds
}

Install with Tessl CLI