codeflash/docs/getting-started/javascript-installation.mdx

---
title: "JavaScript / TypeScript Installation"
description: "Install and configure Codeflash for your JavaScript/TypeScript project"
icon: "node-js"
keywords:
  [
    "installation",
    "javascript",
    "typescript",
    "npm",
    "yarn",
    "pnpm",
    "bun",
    "jest",
    "vitest",
    "monorepo",
  ]
---

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
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
npm install --save-dev codeflash
```

```bash yarn
yarn add --dev codeflash
```

```bash pnpm
pnpm add --save-dev codeflash
```

```bash bun
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>
**Codeflash also requires a Python installation** (3.9+) to run the CLI optimizer. Install the Python CLI globally:

```bash
pip install codeflash
# or
uv tool install codeflash
```

The Python CLI orchestrates the optimization pipeline, while the npm package provides the JavaScript runtime (test runners, serialization, reporters).
</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
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
npx codeflash init
```

```bash bun
bunx codeflash init
```

```bash Global install
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
{
  "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
# 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
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
// 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** | Coming soon | — |

<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
codeflash --file src/utils.js --function processData
```

```bash Optimize locally (no PR)
codeflash --file src/utils.ts --function processData --no-pr
```

```bash Optimize entire codebase
codeflash --all
```

```bash Trace and optimize
codeflash optimize --jest
```
</CodeGroup>

## Troubleshooting

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

    ```javascript
    // 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
    npm install --save-dev codeflash
    ```
    ```bash yarn
    yarn add --dev codeflash
    ```
    ```bash pnpm
    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
       npm ls jest    # or: npm ls vitest
       ```
    2. Or set it manually in `package.json`:
       ```json
       {
         "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
    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