> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codeflash.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript / TypeScript Configuration

> Configure Codeflash for JavaScript and TypeScript projects using package.json

# JavaScript / TypeScript Configuration

Codeflash stores its configuration in `package.json` under the `"codeflash"` key.

## Full Reference

```json theme={null}
{
  "name": "my-project",
  "codeflash": {
    "moduleRoot": "src",
    "testsRoot": "tests",
    "testRunner": "jest",
    "formatterCmds": ["prettier --write $file"],
    "ignorePaths": ["src/generated/"],
    "disableTelemetry": false,
    "gitRemote": "origin"
  }
}
```

All file paths are relative to the directory containing `package.json`.

<Info>
  Codeflash auto-detects most settings from your project structure. Running `codeflash init` will set up the correct config — manual configuration is usually not needed.
</Info>

## Auto-Detection

When you run `codeflash init`, Codeflash inspects your project and auto-detects:

| Setting         | Detection logic                                                                        |
| --------------- | -------------------------------------------------------------------------------------- |
| `moduleRoot`    | Looks for `src/`, `lib/`, or the main source directory                                 |
| `testsRoot`     | Looks for `tests/`, `test/`, `__tests__/`, or files matching `*.test.js` / `*.spec.js` |
| `testRunner`    | Checks `devDependencies` for `jest` or `vitest`                                        |
| `formatterCmds` | Checks for `prettier`, `eslint`, or `biome` in dependencies and config files           |
| Module system   | Reads `"type"` field in `package.json` (ESM vs CommonJS)                               |
| TypeScript      | Detects `tsconfig.json`                                                                |

You can always override any auto-detected value in the `"codeflash"` section.

## Required Options

* `moduleRoot`: The source directory to optimize. Only code under this directory will be optimized.
* `testsRoot`: The directory where your tests are located. Codeflash discovers existing tests and generates new ones here.

## Optional Options

* `testRunner`: Test framework to use. Auto-detected from your dependencies. Supported values: `"jest"`, `"vitest"`, `"mocha"`.
* `formatterCmds`: Formatter commands. `$file` refers to the file being optimized. Disable with `["disabled"]`.
  * **Prettier**: `["prettier --write $file"]`
  * **ESLint + Prettier**: `["eslint --fix $file", "prettier --write $file"]`
  * **Biome**: `["biome check --write $file"]`
* `ignorePaths`: Paths within `moduleRoot` to skip during optimization.
* `disableTelemetry`: Disable anonymized telemetry. Defaults to `false`.
* `gitRemote`: Git remote for pull requests. Defaults to `"origin"`.

## Module Systems

Codeflash handles both ES Modules and CommonJS automatically. It detects the module system from your `package.json`:

```json theme={null}
{
  "type": "module"
}
```

* `"type": "module"` — Files are treated as ESM (`import`/`export`)
* `"type": "commonjs"` or omitted — Files are treated as CommonJS (`require`/`module.exports`)

No additional configuration is needed. Codeflash respects `.mjs`/`.cjs` extensions as well.

## TypeScript

TypeScript projects work out of the box. Codeflash detects TypeScript from the presence of `tsconfig.json` and handles `.ts`/`.tsx` files automatically.

No separate configuration is needed for TypeScript vs JavaScript.

## Test Framework Support

| Framework  | Auto-detected from       | Notes                                      |
| ---------- | ------------------------ | ------------------------------------------ |
| **Jest**   | `jest` in dependencies   | Default for most projects                  |
| **Vitest** | `vitest` in dependencies | ESM-native support                         |
| **Mocha**  | `mocha` in dependencies  | Uses `node:assert/strict`, zero extra deps |

<Info>
  **Functions must be exported** to be optimizable. Codeflash uses tree-sitter AST analysis to discover functions and check export status. Supported export patterns:

  * `export function foo() {}`
  * `export const foo = () => {}`
  * `export default function foo() {}`
  * `const foo = () => {}; export { foo };`
  * `module.exports = { foo }`
  * `const utils = { foo() {} }; module.exports = utils;`
</Info>

## Monorepo Configuration

For monorepo projects (Yarn workspaces, pnpm workspaces, Lerna, Nx, Turborepo), configure each package individually:

```text theme={null}
my-monorepo/
|- packages/
|  |- core/
|  |  |- src/
|  |  |- tests/
|  |  |- package.json    <-- "codeflash" config here
|  |- utils/
|  |  |- src/
|  |  |- __tests__/
|  |  |- package.json    <-- "codeflash" config here
|- package.json           <-- workspace root (no codeflash config)
```

Run `codeflash init` from within each package:

```bash theme={null}
cd packages/core
npx codeflash init
```

<Warning>
  **Always run codeflash from the package directory**, not the monorepo root. Codeflash needs to find the `package.json` with the `"codeflash"` config in the current working directory.
</Warning>

### Hoisted dependencies

If your monorepo hoists `node_modules` to the root (Yarn Berry with `nodeLinker: node-modules`, pnpm with `shamefully-hoist`), Codeflash resolves modules using Node.js standard resolution. This works automatically.

For **pnpm strict mode** (non-hoisted), ensure `codeflash` is a direct dependency of the package:

```bash theme={null}
pnpm add --filter @my-org/core --save-dev codeflash
```

## Example

### Standard project

```text theme={null}
my-app/
|- src/
|  |- utils.js
|  |- index.js
|- tests/
|  |- utils.test.js
|- package.json
```

```json theme={null}
{
  "name": "my-app",
  "codeflash": {
    "moduleRoot": "src",
    "testsRoot": "tests"
  }
}
```

### Project with co-located tests

```text theme={null}
my-app/
|- src/
|  |- utils.js
|  |- utils.test.js
|  |- index.js
|- package.json
```

```json theme={null}
{
  "name": "my-app",
  "codeflash": {
    "moduleRoot": "src",
    "testsRoot": "src"
  }
}
```

### Project with scattered test folders

If your tests are spread across multiple directories (e.g., `test/` at root and `__tests__/` inside `src/`), set `testsRoot` to the common ancestor:

```text theme={null}
my-app/
|- src/
|  |- utils/
|  |  |- __tests__/
|  |  |  |- utils.test.js
|  |  |- helpers.js
|  |- components/
|  |  |- __tests__/
|  |  |  |- Button.test.jsx
|  |  |- Button.jsx
|- test/
|  |- integration.test.js
|- package.json
```

```json theme={null}
{
  "name": "my-app",
  "codeflash": {
    "moduleRoot": "src",
    "testsRoot": "."
  }
}
```

<Info>
  **`testsRoot` is a single path.** Codeflash recursively searches for `*.test.js`, `*.spec.js`, and `__tests__/**/*.js` files under this directory. Setting it to `"."` (project root) discovers tests everywhere, including co-located `__tests__/` folders inside `src/`.
</Info>

<Warning>
  **Monorepos with per-package tests:** Don't set `testsRoot` to the monorepo root. Instead, run codeflash from each package directory with its own config. Each package's `testsRoot` is relative to that package.
</Warning>

### CommonJS library with no separate test directory

```text theme={null}
my-lib/
|- lib/
|  |- helpers.js
|- test/
|  |- helpers.spec.js
|- package.json
```

```json theme={null}
{
  "name": "my-lib",
  "codeflash": {
    "moduleRoot": "lib",
    "testsRoot": "test"
  }
}
```

## Manual Configuration (without `codeflash init`)

If you prefer to configure manually or `codeflash init` doesn't detect your project correctly, add the `"codeflash"` key directly to your `package.json`:

```json theme={null}
{
  "name": "my-project",
  "codeflash": {
    "moduleRoot": "src",
    "testsRoot": "tests",
    "testRunner": "vitest",
    "formatterCmds": ["prettier --write $file"],
    "ignorePaths": ["src/generated/", "src/vendor/"]
  }
}
```

### Step-by-step

1. **Set `moduleRoot`** — the directory containing your source code. Only files under this path are discovered for optimization.
2. **Set `testsRoot`** — the directory containing your tests. Codeflash searches recursively for `*.test.js`, `*.spec.js`, and `__tests__/**/*.js` files.
3. **Set `testRunner`** (optional) — `"jest"`, `"vitest"`, or `"mocha"`. Auto-detected from `devDependencies` if omitted.
4. **Set `formatterCmds`** (optional) — commands to format optimized code. `$file` is replaced with the file path. Use `["disabled"]` to skip formatting.
5. **Set `ignorePaths`** (optional) — directories to exclude from optimization (relative to `moduleRoot`).

### CLI flag overrides

All config values can be overridden via CLI flags:

```bash theme={null}
# Override moduleRoot and testsRoot for a single run
codeflash --file src/utils.ts --function myFunc \
  --module-root src \
  --tests-root test \
  --no-pr

# Specify a directory to optimize (within moduleRoot)
codeflash --all src/utils/
```

## FAQ

<AccordionGroup>
  <Accordion title="Will codeflash handle test files scattered throughout a package?">
    Yes, as long as `testsRoot` is set to a common ancestor directory. Codeflash recursively searches for `*.test.js`, `*.spec.js`, and `__tests__/**/*.js` under `testsRoot`.

    For co-located tests (test files next to source files), set `testsRoot` to the same value as `moduleRoot`:

    ```json theme={null}
    {
      "codeflash": {
        "moduleRoot": "src",
        "testsRoot": "src"
      }
    }
    ```

    For tests in multiple directories, set `testsRoot` to `"."` (project root) to discover them all.

    **Note:** `testsRoot` accepts a single path. For monorepos, run codeflash from each package directory with its own config rather than trying to cover all packages from the root.
  </Accordion>

  <Accordion title="Do I need to add one test folder at a time?">
    No. Codeflash recursively searches `testsRoot`, so a single path covers all nested test directories. For example, `"testsRoot": "."` discovers tests anywhere in the project:

    * `test/unit/*.test.js`
    * `src/components/__tests__/Button.test.tsx`
    * `lib/utils.spec.js`

    All of these are found with a single `testsRoot` setting.
  </Accordion>

  <Accordion title="How does codeflash find existing tests for a function?">
    Codeflash matches tests to functions by:

    1. Scanning all test files under `testsRoot` (matching `*.test.*`, `*.spec.*`, `__tests__/**/*`)
    2. Parsing imports in each test file using tree-sitter
    3. Matching imported function names to the target function

    If a test file imports `myFunction` from `./utils`, it's considered a test for `myFunction`.
  </Accordion>

  <Accordion title="What if codeflash init detects the wrong values?">
    Override any value in `package.json` under the `"codeflash"` key. The most common overrides:

    ```json theme={null}
    {
      "codeflash": {
        "moduleRoot": "src/lib",
        "testsRoot": ".",
        "testRunner": "mocha"
      }
    }
    ```

    Or use CLI flags for one-off overrides: `--module-root`, `--tests-root`.
  </Accordion>

  <Accordion title="Can I use codeflash with a standalone codeflash.yaml?">
    For internal testing and development, codeflash also reads `codeflash.yaml` files. This is useful when you don't want to modify `package.json`:

    ```yaml theme={null}
    module_root: "src"
    tests_root: "test"
    test_framework: "vitest"
    formatter_cmds: []
    ```

    Place this in the project root. The `package.json` config takes precedence if both exist.
  </Accordion>
</AccordionGroup>