Skip to content

quickstart.mdx

Latest commit

 

History

History
298 lines (244 loc) · 8.68 KB

quickstart.mdx

File metadata and controls

298 lines (244 loc) · 8.68 KB
title Quick start
description Get started with fallow in under a minute. Unused code, duplication, and complexity analysis with no configuration needed for the first run.
keywords
quickstart
getting started
first analysis
npx fallow
dead code
duplication
agents
CLI
MCP
CI
icon rocket

Fallow works across three tracks: agents, humans, and CI. Pick your starting point.

Any agent that can execute shell commands can run fallow. Use `--format json` for structured output: 
    ```bash
    npx fallow --format json
    ```

    This runs all analyses (dead code + duplication + complexity) in one pass and returns structured JSON. Fallow auto-detects your frameworks via `package.json`. For a specific analysis only:

    ```bash
    npx fallow dead-code --format json
    ```

    <Tip>
      90 built-in plugins cover Next.js, Vite, Jest, Tailwind, and 76+ more. No configuration needed. Agents can run fallow on any project immediately.
    </Tip>
  </Step>

  <Step title="Find duplicated code">
    ```bash
    npx fallow dupes --format json
    ```

    Finds copy-pasted code blocks across your codebase.
  </Step>

  <Step title="Check codebase health">
    ```bash
    npx fallow health --format json
    ```

    Reports health score, complexity findings, file-level maintainability, hotspots, and refactoring targets.
  </Step>

  <Step title="Auto-fix">
    Preview what would be removed:

    ```bash
    npx fallow fix --dry-run --format json
    ```

    Apply fixes (use `--yes` to skip confirmation in agent workflows):

    ```bash
    npx fallow fix --yes --format json
    ```
  </Step>

  <Step title="Add MCP (optional)">
    For agents that support MCP, add structured tool calling:

    ```json
    {
      "mcpServers": {
        "fallow": {
          "command": "fallow-mcp"
        }
      }
    }
    ```

    Your agent can then call `analyze`, `check_changed`, `find_dupes`, `fix_preview`, `fix_apply`, `feature_flags`, and `project_info` as typed tools. [Full MCP setup](/integrations/mcp)
  </Step>
</Steps>
From your project root, no config needed: 
    ```bash
    npx fallow
    ```

    This runs all analyses (dead code, duplication, and complexity hotspots) in one pass. For individual analyses, use `npx fallow dead-code`, `npx fallow dupes`, `npx fallow health`, or `npx fallow flags`.

    Fallow auto-detects your frameworks via `package.json` and reports unused files, exports, dependencies, types, and more.

    <Tip>
      90 built-in plugins cover Next.js, Vite, Jest, Tailwind, and 76+ more frameworks. Zero configuration required.
    </Tip>
  </Step>

  <Step title="Find duplicated code">
    ```bash
    npx fallow dupes
    ```

    Finds copy-pasted code blocks across your codebase using the default `mild` detection mode. Use `--mode semantic` to also catch clones with renamed variables.
  </Step>

  <Step title="Check codebase health">
    ```bash
    npx fallow health
    ```

    Reports health score, complexity findings, file-level maintainability, hotspots, and refactoring targets. Use `--max-cyclomatic 15` to customize the complexity threshold.
  </Step>

  <Step title="Preview auto-fixes">
    See what fallow would remove before making changes:

    ```bash
    npx fallow fix --dry-run
    ```

    When you're ready:

    ```bash
    npx fallow fix
    ```
  </Step>

  <Step title="Install VS Code extension">
    For real-time feedback as you code:

    ```bash
    code --install-extension fallow-rs.fallow-vscode
    ```

    You'll get inline diagnostics, Code Lens above exports, and one-click fixes. [Full VS Code guide](/integrations/vscode)
  </Step>

  <Step title="Optional: add runtime production coverage">
    If you want runtime evidence about which functions actually execute, start a trial and run the guided setup:

    ```bash
    npx fallow license activate --trial --email you@company.com
    npx fallow coverage setup
    ```

    Follow the generated `docs/collect-coverage.md`, then run:

    ```bash
    npx fallow health --production-coverage ./coverage
    ```

    [Production coverage guide](/analysis/production-coverage)
  </Step>
</Steps>
```yaml name: Fallow analysis on: [push, pull_request] 
        jobs:
          fallow:
            runs-on: ubuntu-latest
            steps:
              - uses: actions/checkout@v4
              - uses: fallow-rs/fallow@v2
                with:
                  format: sarif
        ```
      </Tab>
      <Tab title="GitLab CI">
        ```yaml
        include:
          - remote: 'https://raw.githubusercontent.com/fallow-rs/fallow/main/ci/gitlab-ci.yml'

        fallow:
          extends: .fallow
        ```
      </Tab>
      <Tab title="Other CI">
        ```yaml
        - run: npx fallow --ci
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Inline annotations (optional)">
    <Tabs>
      <Tab title="GitHub Action">
        Upload SARIF to GitHub Code Scanning for inline annotations on PR diffs:

        ```yaml
        - uses: fallow-rs/fallow@v2
          with:
            format: sarif

        - uses: github/codeql-action/upload-sarif@v4
          with:
            sarif_file: fallow-results.sarif
        ```
      </Tab>
      <Tab title="GitLab CI">
        The template automatically generates a GitLab Code Quality report (CodeClimate format) for inline MR annotations. No extra config needed.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Scope to PR/MR changes">
    Only check files modified in the PR or MR:

    <Tabs>
      <Tab title="GitHub Action">
        ```yaml
        - uses: fallow-rs/fallow@v2
          with:
            changed-since: ${{ github.event.pull_request.base.sha }}
        ```
      </Tab>
      <Tab title="GitLab CI">
        ```yaml
        fallow:
          extends: .fallow
          variables:
            FALLOW_CHANGED_SINCE: "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
        ```
      </Tab>
      <Tab title="Other CI">
        ```yaml
        - run: npx fallow --changed-since origin/main
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

[Full CI integration guide](/integrations/ci)

Create a config (optional)

For customization, generate a config file. This also adds .fallow/ to your .gitignore:

fallow init
```jsonc .fallowrc.json { "$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json", "entry": ["src/workers/*.ts", "scripts/*.ts"], "ignorePatterns": ["**/*.generated.ts"], "rules": { "unused-files": "error", "unused-exports": "warn", "unused-types": "off" } } ``` ```toml fallow.toml entry = ["src/workers/*.ts", "scripts/*.ts"] ignorePatterns = ["**/*.generated.ts"]

[rules] unused-files = "error" unused-exports = "warn" unused-types = "off"

</CodeGroup>

<Info>
  Configuration is shared across all three tracks. The same `.fallowrc.json` applies to agents, developers, and CI alike.
</Info>

<Info>
  **Migrating from knip or jscpd?** Fallow can auto-migrate your existing config. See the [knip migration guide](/migration/from-knip) or [jscpd migration guide](/migration/from-jscpd).
</Info>

## Next steps

<CardGroup cols={2}>
  <Card title="Agent integration" icon="robot" href="/integrations/mcp">
    Full guide for CLI and MCP agent workflows.
  </Card>
  <Card title="Dead code analysis" icon="skull-crossbones" href="/analysis/dead-code">
    Unused files, exports, dependencies, circular deps, and boundaries.
  </Card>
  <Card title="Code duplication" icon="clone" href="/analysis/duplication">
    Explore detection modes and clone families.
  </Card>
  <Card title="Configuration" icon="gear" href="/configuration/overview">
    Customize entry points, rules, and ignore patterns.
  </Card>
</CardGroup>