JavaScript / TypeScript Configuration

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

Full Reference

{
  "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.

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

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:

{
  "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

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;

Monorepo Configuration

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

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:

cd packages/core
npx codeflash init

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.

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:

pnpm add --filter @my-org/core --save-dev codeflash

Example

Standard project

my-app/
|- src/
|  |- utils.js
|  |- index.js
|- tests/
|  |- utils.test.js
|- package.json

{
  "name": "my-app",
  "codeflash": {
    "moduleRoot": "src",
    "testsRoot": "tests"
  }
}

Project with co-located tests

my-app/
|- src/
|  |- utils.js
|  |- utils.test.js
|  |- index.js
|- package.json

{
  "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:

my-app/
|- src/
|  |- utils/
|  |  |- __tests__/
|  |  |  |- utils.test.js
|  |  |- helpers.js
|  |- components/
|  |  |- __tests__/
|  |  |  |- Button.test.jsx
|  |  |- Button.jsx
|- test/
|  |- integration.test.js
|- package.json

{
  "name": "my-app",
  "codeflash": {
    "moduleRoot": "src",
    "testsRoot": "."
  }
}

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/.

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.

CommonJS library with no separate test directory

my-lib/
|- lib/
|  |- helpers.js
|- test/
|  |- helpers.spec.js
|- package.json

{
  "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:

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

Step-by-step

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

CLI flag overrides

All config values can be overridden via CLI flags:

# 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

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:

{
  "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.

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.

How does codeflash find existing tests for a function?

Codeflash matches tests to functions by:

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

If a test file imports myFunction from ./utils, it’s considered a test for myFunction.

What if codeflash init detects the wrong values?

Override any value in package.json under the "codeflash" key. The most common overrides:

{
  "codeflash": {
    "moduleRoot": "src/lib",
    "testsRoot": ".",
    "testRunner": "mocha"
  }
}

Or use CLI flags for one-off overrides: --module-root, --tests-root.

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:

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.

Overview

Getting Started

Using Codeflash

Configuration

Core Concepts

IDE Extension

JavaScript / TypeScript Configuration

JavaScript / TypeScript Configuration

Full Reference

Auto-Detection

Required Options

Optional Options

Module Systems

TypeScript

Test Framework Support

Monorepo Configuration

Hoisted dependencies

Example

Standard project

Project with co-located tests

Project with scattered test folders

CommonJS library with no separate test directory

Manual Configuration (without `codeflash init`)

Step-by-step

CLI flag overrides

FAQ

Overview

Getting Started

Using Codeflash

Configuration

Core Concepts

IDE Extension

​JavaScript / TypeScript Configuration

​Full Reference

​Auto-Detection

​Required Options

​Optional Options

​Module Systems

​TypeScript

​Test Framework Support

​Monorepo Configuration

​Hoisted dependencies

​Example

​Standard project

​Project with co-located tests

​Project with scattered test folders

​CommonJS library with no separate test directory

​Manual Configuration (without codeflash init)

​Step-by-step

​CLI flag overrides

​FAQ

JavaScript / TypeScript Configuration

Full Reference

Auto-Detection

Required Options

Optional Options

Module Systems

TypeScript

Test Framework Support

Monorepo Configuration

Hoisted dependencies

Example

Standard project

Project with co-located tests

Project with scattered test folders

CommonJS library with no separate test directory

Manual Configuration (without `codeflash init`)

Step-by-step

CLI flag overrides

FAQ