@mutates/nx - Mutates Docs

The @mutates/nx package extends Mutates functionality to work seamlessly with Nx workspaces, providing tools for manipulating Nx project configurations and workspace files.

Installation

Install both the Nx package and the core package:

npm install @mutates/nx @mutates/core

Basic Usage

Project Setup

Initialize an Nx project with Mutates:

import { saveProject } from '@mutates/core';
import { createNxProject } from '@mutates/nx';

// Create project with Nx support
createNxProject();

// Make modifications...

// Save changes
saveProject();

Project Configuration

Modifying Project Configuration

import { editProjectConfiguration } from '@mutates/nx';

// Update project configuration
editProjectConfiguration('my-app', {
  targets: {
    build: {
      executor: '@nx/webpack:webpack',
      options: {
        outputPath: 'dist/apps/my-app',
        main: 'apps/my-app/src/main.ts',
      },
    },
  },
});

Adding Dependencies

import { addProjectDependencies } from '@mutates/nx';

// Add project dependencies
addProjectDependencies('my-app', {
  dependencies: ['shared-lib'],
  type: 'implicit', // or 'explicit'
});

Workspace Management

Updating Workspace Configuration

import { updateWorkspaceConfig } from '@mutates/nx';

// Update workspace configuration
updateWorkspaceConfig({
  npmScope: 'my-org',
  defaultProject: 'main-app',
  generators: {
    '@nx/angular:application': {
      style: 'scss',
      strict: true,
    },
  },
});

Managing Tags

import { addProjectTags } from '@mutates/nx';

// Add tags to project
addProjectTags('my-app', ['frontend', 'public-api']);

Library Management

Creating Libraries

import { addLibrary } from '@mutates/nx';

// Add new library
addLibrary({
  name: 'shared-utils',
  directory: 'libs/shared',
  tags: ['utils', 'shared'],
});

Modifying Libraries

import { editLibrary } from '@mutates/nx';

// Modify library configuration
editLibrary('shared-utils', {
  buildable: true,
  publishable: true,
});

Application Management

Creating Applications

import { addApplication } from '@mutates/nx';

// Add new application
addApplication({
  name: 'admin-portal',
  directory: 'apps/admin',
  tags: ['admin', 'frontend'],
});

Configuring Applications

import { editApplication } from '@mutates/nx';

// Update application configuration
editApplication('admin-portal', {
  strict: true,
  standalone: true,
});

Generator Configuration

Customizing Generators

import { updateGeneratorDefaults } from '@mutates/nx';

// Set default generator options
updateGeneratorDefaults('@nx/angular:component', {
  style: 'scss',
  changeDetection: 'OnPush',
  standalone: true,
});

Common Use Cases

Setting Up Module Boundaries

import { setupModuleBoundaries } from '@mutates/nx';

// Configure module boundaries
setupModuleBoundaries({
  enforce: [
    {
      sourceTag: 'type:feature',
      onlyDependOnLibsWithTags: ['type:shared', 'type:util'],
    },
    {
      sourceTag: 'scope:admin',
      notDependOnLibsWithTags: ['scope:public'],
    },
  ],
});

Configuring Build Targets

import { updateBuildTarget } from '@mutates/nx';

// Update build configuration
updateBuildTarget('my-app', {
  optimization: true,
  sourceMap: false,
  extractLicenses: true,
});

Best Practices

Pattern Matching

Use specific patterns for different project types:

// Libraries
getLibraries({ pattern: 'libs/**/*.ts' });

// Applications
getApplications({ pattern: 'apps/**/*.ts' });

Error Handling

Wrap Nx operations in try-catch:

import { resetActiveProject } from '@mutates/core';
import { createNxProject } from '@mutates/nx';

try {
  createNxProject();
  // Your transformations...
} catch (error) {
  console.error('Nx transformation failed:', error);
} finally {
  resetActiveProject();
}

Integration with Other Tools

Angular Integration

import { addAngularLibrary } from '@mutates/angular';
import { createNxProject } from '@mutates/nx';

// Combine Nx and Angular operations
createNxProject();
addAngularLibrary({
  name: 'feature-auth',
  directory: 'libs/features',
});

Testing Setup

import { updateTestTarget } from '@mutates/nx';

// Configure test setup
updateTestTarget('my-app', {
  executor: '@nx/jest:jest',
  options: {
    jestConfig: 'apps/my-app/jest.config.ts',
    passWithNoTests: true,
  },
});

Next Steps

Learn about Advanced Usage
Explore Framework Integrations
Check out the Core Package Documentation

API Reference

For a comprehensive guide on the available APIs and their usage, please refer to the official documentation

Contributing

🤝 Contributions are welcome! If you have any improvements or suggestions, feel free to open an issue or submit a pull request.

License

📄 @mutates/nx is licensed under the Apache-2.0 License. See the LICENSE file for more information.

For further assistance or to report issues, please visit our GitHub repository.