---
title: Manual Migration of Existing Code Bases
description: Learn how to manually integrate Nx into your existing codebase by installing dependencies, configuring nx.json, setting up caching, and updating your gitignore file.
filter: 'type:Guides'
sidebar:
  label: Manual migration
---

The easiest way to start using Nx is to run the `nx init` command.

```shell
npx nx@latest init
```

If you don't want to run the script, walk you through doing everything the script does manually.

## Install `nx` as a `devDependency`

We'll start by installing the `nx` package:

{% tabs syncKey="install-type" %}
{% tabitem label="npm" %}

```shell
npm add -D nx@latest
```

{% /tabitem %}
{% tabitem label="yarn" %}

```shell
yarn add -D nx@latest
```

{% /tabitem %}
{% tabitem label="pnpm" %}

```shell
pnpm add -D nx@latest
```

{% /tabitem %}
{% tabitem label="bun" %}

```shell
bun add -D nx@latest
```

{% /tabitem %}
{% /tabs %}

## Create a basic `nx.json` file

Next, we'll create a blank `nx.json` configuration file for Nx:

```json
// nx.json
{}
```

## Add `.nx` directories to `.gitignore`

Next, we'll add the Nx default task cache directory and the project graph cache directory to the list of files to be ignored by Git. Update the `.gitignore` file adding the `.nx/cache` and `.nx/workspace-data` entry:

```text
// .gitignore
...
.nx/cache
.nx/workspace-data
```

## Set up caching for a task

Now, let's set up caching for a script in your `package.json` file. Let's say you have a `build` script that looks like this:

```json
// package.json
{
  "scripts": {
    "build": "tsc -p tsconfig.json"
  }
}
```

In order for Nx to cache this task, you need to:

- run the script through Nx using `nx exec -- `
- configure caching settings in the `nx` property of `package.json`

The new `package.json` will look like this:

```json
// package.json
{
  "scripts": {
    "build": "nx exec -- tsc -p tsconfig.json"
  },
  "nx": {
    "targets": {
      "build": {
        "cache": true,
        "inputs": [
          "{projectRoot}/**/*.ts",
          "{projectRoot}/tsconfig.json",
          { "externalDependencies": ["typescript"] }
        ],
        "outputs": ["{projectRoot}/dist"]
      }
    }
  }
}
```

Now, if you run `npm build` or `nx build` twice, the second run will be retrieved from the cache instead of being executed.

## Enable more features of Nx as needed

You could stop here if you want, but there are many more features of Nx that might be useful to you. Many [plugins](/docs/plugin-registry) can automate the process of configuring the way Nx runs your tools. Plugins also provide [code generators](/docs/features/generate-code) and [automatic dependency updates](/docs/features/automate-updating-dependencies). You can speed up your CI with [remote caching](/docs/features/ci-features/remote-cache) and [distributed task execution](/docs/features/ci-features/distribute-task-execution).