Quick Start - Mutates Docs

This guide will help you get up and running with Mutates in minutes. You'll learn how to install the package and perform basic code transformations.

Installation

Install the core package:

npm install @mutates/core

Optional: Install framework-specific packages if needed:

# For Angular projects
npm install @mutates/angular

# For Nx workspaces
npm install @mutates/nx

Basic Example

Here's a simple example that demonstrates the core functionality of Mutates:

import { addClasses, createProject, createSourceFile, saveProject } from '@mutates/core';

// Initialize project
createProject();

// Create a new TypeScript file
createSourceFile(
  'src/user.ts',
  `
  // Initial empty file
  `,
);

// Add a class
addClasses('src/user.ts', {
  name: 'User',
  isExported: true,
  properties: [
    {
      name: 'id',
      type: 'number',
    },
    {
      name: 'name',
      type: 'string',
    },
  ],
  methods: [
    {
      name: 'greet',
      returnType: 'string',
      statements: 'return `Hello, ${this.name}!`;',
    },
  ],
});

// Save changes
saveProject();

This will generate a file with the following content:

export class User {
  id: number;
  name: string;

  greet(): string {
    return `Hello, ${this.name}!`;
  }
}

Common Operations

Finding and Modifying Classes

import { editClasses, getClasses } from '@mutates/core';

// Find classes
const classes = getClasses({ pattern: 'src/**/*.ts' });

// Modify them
editClasses(classes, () => ({
  isExported: true,
  extends: 'BaseClass',
}));

Adding Methods

import { addMethods } from '@mutates/core';

addMethods(targetClass, {
  name: 'sayHello',
  parameters: [
    {
      name: 'name',
      type: 'string',
    },
  ],
  statements: 'console.log(`Hello, ${name}!`);',
});

Managing Imports

import { addImports } from '@mutates/core';

addImports('src/example.ts', {
  namedImports: ['Injectable'],
  moduleSpecifier: '@angular/core',
});

Framework Integration

Angular Example

import { createAngularProject } from '@mutates/angular';
import { saveProject } from '@mutates/core';

// Initialize Angular project
createAngularProject();

// Add component
addComponent('src/app/features', {
  name: 'UserList',
  template: '<ul><li *ngFor="let user of users">{{user.name}}</li></ul>',
  styles: [
    `
    :host {
      display: block;
      margin: 1rem;
    }
  `,
  ],
});

// Save changes
saveProject();

Nx Example

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

// Initialize Nx project
createNxProject();

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

// Save changes
saveProject();

Best Practices

Always Initialize Project

import { createProject } from '@mutates/core';

createProject();

Use Try-Finally

import { createProject, resetActiveProject } from '@mutates/core';

try {
  createProject();
  // Your transformations...
} finally {
  resetActiveProject();
}

Save Changes

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

// After all transformations
saveProject();

Error Handling

try {
  createProject();

  // Your transformations...

  saveProject();
} catch (error) {
  console.error('Failed to transform code:', error);
  // Handle error appropriately
} finally {
  resetActiveProject();
}

Next Steps

Learn about Basic Operations
Explore Framework Integrations
Read the Advanced Usage guide
Check out the API Documentation

Getting Help

If you run into any issues:

Check the Troubleshooting guide
Read the FAQ
Open an issue on GitHub