> ## 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 Installation

> Install and configure Codeflash for your JavaScript/TypeScript project

Codeflash supports JavaScript and TypeScript projects. It uses V8 native serialization for test data capture and works with Jest and Vitest test frameworks.

### Prerequisites

Before installing Codeflash, ensure you have:

1. **Node.js 18 or above** installed
2. **A JavaScript/TypeScript project** with a package manager (npm, yarn, pnpm, or bun)
3. **Project dependencies installed**

Good to have (optional):

1. **Unit tests** (Jest or Vitest) — Codeflash uses them to verify correctness of optimizations

<Warning>
  **Node.js 18+ Required**

  Codeflash requires Node.js 18 or above. Check your version:

  ```bash theme={null}
  node --version  # Should show v18.0.0 or higher
  ```
</Warning>

<Steps>
  <Step title="Install the Codeflash npm package">
    Install Codeflash as a development dependency in your project:

    <CodeGroup>
      ```bash npm theme={null}
      npm install --save-dev codeflash
      ```

      ```bash yarn theme={null}
      yarn add --dev codeflash
      ```

      ```bash pnpm theme={null}
      pnpm add --save-dev codeflash
      ```

      ```bash bun theme={null}
      bun add --dev codeflash
      ```
    </CodeGroup>

    <Tip>
      **Dev dependency recommended** — Codeflash is for development and CI workflows. Installing as a dev dependency keeps your production bundle clean.
    </Tip>

    <Info>
      **One-time setup required.** The Codeflash optimizer runs on Python behind the scenes. After installing the npm package, run:

      ```bash theme={null}
      npx codeflash setup
      ```

      This automatically creates an isolated Python environment — no global installs or manual Python management needed. After setup, all Codeflash commands run through `npx codeflash` which uses the installed binary automatically.
    </Info>
  </Step>

  <Step title="Generate a Codeflash API Key">
    Codeflash uses cloud-hosted AI models. You need an API key:

    1. Visit the [Codeflash Web App](https://app.codeflash.ai/)
    2. Sign up with your GitHub account (free tier available)
    3. Navigate to the [API Key](https://app.codeflash.ai/app/apikeys) page to generate your key

    Set it as an environment variable:

    ```bash theme={null}
    export CODEFLASH_API_KEY="your-api-key-here"
    ```

    Or add it to your shell profile (`~/.bashrc`, `~/.zshrc`) for persistence.
  </Step>

  <Step title="Run Automatic Configuration">
    Navigate to your project root (where `package.json` is) and run:

    <CodeGroup>
      ```bash npm / yarn / pnpm theme={null}
      npx codeflash init
      ```

      ```bash bun theme={null}
      bunx codeflash init
      ```

      ```bash Global install theme={null}
      codeflash init
      ```
    </CodeGroup>

    ### What `codeflash init` does

    Codeflash **auto-detects** most settings from your project:

    | Setting            | How it's detected                                                                      |
    | ------------------ | -------------------------------------------------------------------------------------- |
    | **Module root**    | Looks for `src/`, `lib/`, or the directory containing your source files                |
    | **Tests root**     | Looks for `tests/`, `test/`, `__tests__/`, or files matching `*.test.js` / `*.spec.js` |
    | **Test framework** | Checks `devDependencies` for `jest` or `vitest`                                        |
    | **Formatter**      | 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` presence                                                       |

    You'll be prompted to confirm or override the detected values. The configuration is saved in your `package.json` under the `"codeflash"` key:

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

    <Info>
      **No separate config file needed.** Codeflash stores all configuration inside your existing `package.json`, not in a separate config file.
    </Info>
  </Step>

  <Step title="Install the Codeflash GitHub App (optional)">
    To receive optimization PRs automatically, install the Codeflash GitHub App:

    [Install Codeflash GitHub App](https://github.com/apps/codeflash-ai/installations/select_target)

    This enables the codeflash-ai bot to open PRs with optimization suggestions. If you skip this step, you can still optimize locally using `--no-pr`.
  </Step>
</Steps>

## Monorepo Setup

For monorepos (Yarn workspaces, pnpm workspaces, Lerna, Nx, Turborepo), run `codeflash init` from within each package you want to optimize:

```bash theme={null}
# Navigate to the specific package
cd packages/my-library

# Run init from the package directory
npx codeflash init
```

Each package gets its own `"codeflash"` section in its `package.json`. The `moduleRoot` and `testsRoot` paths are relative to that package's `package.json`.

### Example: Yarn workspaces monorepo

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

```json theme={null}
// packages/core/package.json
{
  "name": "@my-org/core",
  "codeflash": {
    "moduleRoot": "src",
    "testsRoot": "tests"
  }
}
```

<Warning>
  **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>

<Info>
  **Hoisted dependencies work fine.** If your monorepo hoists `node_modules` to the root (common in Yarn Berry, pnpm with `shamefully-hoist`), Codeflash resolves modules using Node.js standard resolution and will find them correctly.
</Info>

## Test Framework Support

| Framework  | Status    | Auto-detected from       |
| ---------- | --------- | ------------------------ |
| **Jest**   | Supported | `jest` in dependencies   |
| **Vitest** | Supported | `vitest` in dependencies |
| **Mocha**  | Supported | `mocha` in dependencies  |

<Info>
  **Mocha projects** use `node:assert/strict` for generated tests (zero extra dependencies). Mocha's `describe`/`it` globals are used automatically — no imports needed.
</Info>

<Info>
  **Functions must be exported** to be optimizable. Codeflash can only discover and optimize functions that are exported from their module (via `export`, `export default`, or `module.exports`).
</Info>

## Try It Out

Once configured, optimize your code:

<CodeGroup>
  ```bash Optimize a function theme={null}
  codeflash --file src/utils.js --function processData
  ```

  ```bash Optimize locally (no PR) theme={null}
  codeflash --file src/utils.ts --function processData --no-pr
  ```

  ```bash Optimize entire codebase theme={null}
  codeflash --all
  ```

  ```bash Dry run (see what would be optimized) theme={null}
  codeflash --all --dry-run
  ```
</CodeGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Function not found or not exported">
    Codeflash only optimizes **exported** functions. Make sure your function is exported:

    ```javascript theme={null}
    // ES Modules
    export function processData(data) { ... }
    // or
    const processData = (data) => { ... };
    export { processData };

    // CommonJS
    function processData(data) { ... }
    module.exports = { processData };
    ```

    If codeflash reports the function exists but is not exported, add an export statement.
  </Accordion>

  <Accordion title="codeflash npm package not found / module errors">
    Ensure the codeflash npm package is installed in your project:

    <CodeGroup>
      ```bash npm theme={null}
      npm install --save-dev codeflash
      ```

      ```bash yarn theme={null}
      yarn add --dev codeflash
      ```

      ```bash pnpm theme={null}
      pnpm add --save-dev codeflash
      ```
    </CodeGroup>

    For **monorepos**, make sure it's installed in the package you're optimizing, or at the workspace root if dependencies are hoisted.
  </Accordion>

  <Accordion title="Test framework not detected">
    Codeflash auto-detects the test framework from your `devDependencies`. If detection fails:

    1. Verify your test framework is in `devDependencies`:
       ```bash theme={null}
       npm ls jest    # or: npm ls vitest
       ```
    2. Or set it manually in `package.json`:
       ```json theme={null}
       {
         "codeflash": {
           "testRunner": "jest"
         }
       }
       ```
  </Accordion>

  <Accordion title="Jest tests timing out">
    If Jest tests take too long, Codeflash has a default timeout. For large test suites:

    * Use `--file` and `--function` to target specific functions instead of `--all`
    * Ensure your tests don't have expensive setup/teardown that runs for every test file
    * Check if `jest.config.js` has a `setupFiles` that takes a long time
  </Accordion>

  <Accordion title="TypeScript compilation errors">
    Codeflash uses your project's TypeScript configuration. If you see TS errors:

    1. Verify `npx tsc --noEmit` passes on its own
    2. Check that `tsconfig.json` is in the project root or the module root
    3. For projects using `moduleResolution: "bundler"`, Codeflash creates a temporary tsconfig overlay — this is expected behavior
  </Accordion>

  <Accordion title="Monorepo: wrong package.json detected">
    Run codeflash from the correct package directory:

    ```bash theme={null}
    cd packages/my-library
    codeflash --file src/utils.ts --function myFunc
    ```

    If your monorepo tool hoists dependencies, you may need to ensure the `codeflash` npm package is accessible from the package directory. For pnpm, add `.npmrc` with `shamefully-hoist=true` or use `pnpm add --filter my-library --save-dev codeflash`.
  </Accordion>

  <Accordion title="No optimizations found">
    Not all functions can be optimized — some code is already efficient. This is normal.

    For better results:

    * Target functions with loops, string manipulation, or data transformations
    * Ensure the function has existing tests for correctness verification
    * Use `codeflash optimize --jest` to trace real execution and capture realistic inputs
  </Accordion>
</AccordionGroup>

## Configuration Reference

See [JavaScript / TypeScript Configuration](/configuration/javascript) for the full list of options.

### Next Steps

* Learn [how Codeflash works](/codeflash-concepts/how-codeflash-works)
* [Optimize a single function](/optimizing-with-codeflash/one-function)
* Set up [Pull Request Optimization](/optimizing-with-codeflash/codeflash-github-actions)
* Explore [Trace and Optimize](/optimizing-with-codeflash/trace-and-optimize) for workflow optimization