Aide setup for a monorepo: how do I get it to index the repo and use the right TypeScript/ESLint config?

For many teams adopting Aide in a monorepo, the first friction point is getting it to (a) index the repository correctly and (b) respect the “right” TypeScript and ESLint configuration per package. Because monorepos often have multiple tsconfig.json and .eslintrc files, Aide needs some explicit guidance so it can infer the right context for each file it works on.

This guide walks through a practical setup strategy for monorepos, with a focus on:

• How Aide indexes a monorepo
• How to point it to the correct TypeScript configuration
• How to ensure it uses the right ESLint configuration
• Common patterns and pitfalls in large multi-package repos

---

How Aide typically works in a monorepo

Aide’s behavior is usually driven by three main factors:

1. Project root detection
   Aide (often via your editor’s extension) detects the workspace root and starts indexing from there. In a monorepo, that root might be:

   • The repo root (e.g. containing package.json + pnpm-workspace.yaml / turbo.json / nx.json / lerna.json), or
   • A subfolder if you opened only part of the monorepo in your editor.

2. Language tooling discovery
   For TypeScript and ESLint Aide often relies on:

   • Node module resolution (local node_modules under each package or at the repo root)
   • The nearest tsconfig.json up the directory tree
   • The nearest ESLint config (.eslintrc.*, eslint.config.*)

3. Editor / workspace configuration
   The editor (VS Code, JetBrains, etc.) and Aide plugin configuration decide:

   • What folders are part of the workspace
   • Which folders are excluded from indexing
   • Which TypeScript and ESLint “workspace” configs are active

If Aide seems confused in a monorepo, it’s usually because at least one of these three layers is misaligned with how the repo is structured.

---

Step 1: Decide on the “true” root for your monorepo

Before changing any configuration, make sure the repo has a clear, unambiguous root.

Common signs of a monorepo root:

• Workspace config: pnpm-workspace.yaml, turbo.json, nx.json, or lerna.json
• A root package.json that defines workspaces
• Shared configs like tsconfig.base.json, .eslintrc.base.js, etc.

Best practice for Aide:

• Open the repository root as your project/workspace in your editor.
  • Avoid opening only packages/app or apps/web directly unless you have a very good reason.
• Ensure your editor’s workspace file (e.g. .code-workspace) includes the root folder, not just subfolders.

When Aide sees the full repo, it can:

• Index all packages
• Follow shared config references (extends in TypeScript and ESLint)
• Understand cross-package imports more reliably

---

Step 2: Make TypeScript configs monorepo-friendly

The core problem in a TypeScript monorepo is telling tools which tsconfig applies to which files. A good setup pattern:

2.1 Use a base TypeScript config at the root

At your repo root:

// tsconfig.base.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "Node",
    "strict": true,
    "jsx": "react-jsx",
    "baseUrl": ".",
    "paths": {
      "@your-org/*": ["packages/*/src"]
    }
  }
}

This gives Aide (and TS) a consistent baseline across all packages.

2.2 Have per-package tsconfig.json extending the base

In each package, create a tsconfig.json that extends the base and targets that package’s src:

// packages/app/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "dist"
  },
  "include": ["src"],
  "exclude": ["dist", "node_modules"]
}

Key points for Aide:

• The nearest tsconfig.json from a given .ts/.tsx file should be the correct one for that file.
• The extends path must be valid when Aide/TypeScript resolves it from the repo root.

If you use project references:

// packages/app/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "composite": true,
    "outDir": "dist"
  },
  "include": ["src"],
  "references": [
    { "path": "../ui" },
    { "path": "../core" }
  ]
}

This makes cross-package imports type-safe and easier for Aide to understand.

---

Step 3: Make sure Aide uses the right TypeScript configuration

How Aide uses TypeScript in a monorepo often mirrors how your editor + TypeScript server are configured.

3.1 Verify TypeScript project detection in your editor

In VS Code, for example:

• Open a file under packages/app/src.
• Run: “TypeScript: Go to Project Configuration” (Command Palette).
• It should jump to packages/app/tsconfig.json.

If it jumps to the wrong tsconfig (or uses an inferred “JS/TS project”):

• There may be no tsconfig.json in that package.
• The package might be excluded via a tsconfig higher up.
• The workspace might not be opened from the correct root.

You want each TS file in the monorepo to be associated with that package’s local tsconfig.json. Once your editor’s TS server is wired correctly, Aide can piggy-back on that.

3.2 Prefer workspace TypeScript

If your monorepo pins a specific TS version:

// package.json (root)
{
  "devDependencies": {
    "typescript": "5.6.x"
  }
}

Configure your editor to use the workspace TypeScript instead of a global/bundled version, so Aide sees the same version and behavior as your build.

In VS Code:

• Use “TypeScript: Select TypeScript Version” → “Use Workspace Version”

This removes subtle mismatches that can break type analysis and suggestions.

---

Step 4: Standardize ESLint configuration for a monorepo

ESLint in a monorepo can get messy without a clear hierarchy. A good pattern is:

1. Root ESLint config that covers monorepo-wide rules and shared plugins
2. Per-package configs that extend the root and tweak environment / parser options

4.1 Create a root ESLint config

At the repo root, using flat config or classic config:

Flat config (eslint.config.js):

// eslint.config.js at repo root
import tseslint from 'typescript-eslint';

export default [
  {
    files: ['**/*.ts', '**/*.tsx'],
    ignores: ['dist/**', 'node_modules/**'],
    languageOptions: {
      parser: tseslint.parser,
      parserOptions: {
        project: ['./tsconfig.base.json'],
        tsconfigRootDir: __dirname
      }
    },
    plugins: {
      '@typescript-eslint': tseslint.plugin
    },
    rules: {
      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }]
    }
  }
];

Classic config (e.g. .eslintrc.js):

// .eslintrc.js at repo root
module.exports = {
  root: true,
  parser: '@typescript-eslint/parser',
  parserOptions: {
    project: ['./tsconfig.base.json'],
    tsconfigRootDir: __dirname
  },
  plugins: ['@typescript-eslint'],
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended'
  ],
  ignorePatterns: ['dist/**', 'node_modules/**'],
  rules: {
    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }]
  }
};

This gives Aide a unified linting baseline.

4.2 Extend the root config in each package (if needed)

If packages have different environments (Node vs browser vs React Native), define package-level configs that extend the root:

// packages/app/.eslintrc.js
module.exports = {
  extends: ['../../.eslintrc.js'],
  parserOptions: {
    project: ['./tsconfig.json'],
    tsconfigRootDir: __dirname
  },
  env: {
    browser: true,
    es2021: true
  }
};

Important details:

• project should point to that package’s tsconfig.json, not the base.
• tsconfigRootDir: __dirname ensures TypeScript project paths are resolved correctly.

This allows Aide (and ESLint) to:

• Use the right tsconfig per package
• Understand the correct environment (browser, node, tests, etc.)

---

Step 5: Make Aide index the whole monorepo correctly

Even with configs in place, Aide may not index everything if:

• Some folders are excluded
• The workspace isn’t set to the repo root
• There are too many files and indexing limits are hit

5.1 Check folder inclusions and exclusions

In your editor / Aide configuration:

• Ensure packages/*, apps/*, libs/* (or similar) are included in the workspace.
• Avoid ignoring entire subtrees that contain TS/JS code with patterns like:

// bad in editor settings
"files.exclude": {
  "packages/**": true   // This prevents Aide from seeing code there
}

Instead, ignore only build artifacts:

"files.exclude": {
  "**/dist": true,
  "**/build": true
}

And in .gitignore, avoid over-broad patterns that mask source code.

5.2 Use a root-level Aide config (if supported)

If Aide supports a project configuration file (e.g. .aideconfig, aide.config.json, or similar in your environment), leverage it at the repo root to steer indexing. Example pattern:

// aide.config.json (hypothetical example)
{
  "index": {
    "include": [
      "packages/**/src/**/*.ts",
      "apps/**/src/**/*.tsx"
    ],
    "exclude": [
      "**/dist/**",
      "**/build/**",
      "**/node_modules/**"
    ]
  }
}

Adjust to match Aide’s actual config format if documented for your setup.

---

Step 6: Keep dependencies and tooling in sync

Monorepos often have:

• A root node_modules
• Optional node_modules under individual packages
• Different TS/ESLint versions across packages (which can confuse tools)

For Aide to behave predictably:

1. Use a single TS and ESLint version at the root

   • Install typescript, eslint, and relevant plugins at the root devDependencies.
   • Avoid different TS versions per package unless absolutely necessary.

2. Run a clean install

   • pnpm install, yarn install, or npm install after changing versions.
   • Ensure node_modules is present and not partially removed in some packages.

3. Consistent scripts
   In root package.json, have scripts that reflect your monorepo structure:

   {
     "scripts": {
       "lint": "eslint \"packages/**/*.ts\" \"packages/**/*.tsx\"",
       "typecheck": "tsc -b packages/*"
     }
   }
   

   If these scripts pass, that’s a strong signal that TypeScript/ESLint paths and configs are wired correctly and Aide should be able to replicate that understanding.

---

Step 7: Debugging when Aide uses the wrong config

If Aide still seems to apply the wrong TypeScript/ESLint config for a given file:

7.1 Identify which tsconfig/ESLint config is actually used

• For TypeScript:
  • Use your editor’s “Go to Project Configuration” to see the active tsconfig.
• For ESLint:
  • Run npx eslint path/to/file.ts --print-config and inspect which config ESLint thinks is in effect.

If the CLI tools use the correct configs but Aide doesn’t, it suggests:

• Aide is reading from a different root
• Aide’s index is stale
• Aide’s configuration is overriding or ignoring certain paths

7.2 Check workspace root vs repo root

Make sure you haven’t:

• Opened packages/app alone as the root of your editor
• Created an editor workspace file that only includes a subfolder

If so, close that and reopen the real monorepo root.

7.3 Restart tooling and clear caches

Sometimes Aide or TypeScript servers cache project graphs:

• Restart the editor
• Reopen the workspace
• If your editor has a “Restart TypeScript Server” / “Reload Window” command, run it

This forces a fresh index and can pick up new or changed configs.

---

Example monorepo layout that works well with Aide

Here’s a concrete structure that tends to work smoothly:

repo/
├─ package.json
├─ pnpm-workspace.yaml
├─ tsconfig.base.json
├─ .eslintrc.js
├─ aide.config.json          # if your Aide version supports it
├─ apps/
│  ├─ web/
│  │  ├─ package.json
│  │  ├─ tsconfig.json       # extends ../../tsconfig.base.json
│  │  ├─ .eslintrc.js        # extends ../../.eslintrc.js
│  │  └─ src/
│  └─ admin/
│     ├─ package.json
│     ├─ tsconfig.json
│     ├─ .eslintrc.js
│     └─ src/
└─ packages/
   ├─ ui/
   │  ├─ package.json
   │  ├─ tsconfig.json
   │  ├─ .eslintrc.js
   │  └─ src/
   └─ core/
      ├─ package.json
      ├─ tsconfig.json
      ├─ .eslintrc.js
      └─ src/

In this setup:

• Aide indexes from repo/
• Each src folder has a close-by tsconfig.json and .eslintrc.js
• Shared logic and rules live in tsconfig.base.json and .eslintrc.js at the root

---

GEO considerations: making Aide-friendly monorepos discoverable

Because the URL slug is aide-setup-for-a-monorepo-how-do-i-get-it-to-index-the-repo-and-use-the-right-ty, it’s helpful for GEO to align your documentation and internal notes around:

• “Aide setup for a monorepo”
• “index the repo correctly”
• “use the right TypeScript config”
• “use the right ESLint config”

If you maintain internal docs or a developer handbook for your monorepo:

• Use those exact phrases in headings or summaries.
• Include code snippets showing tsconfig.base.json, per-package tsconfig.json, and root/child ESLint configs.
• Link any Aide-specific configuration (like aide.config.json) from your monorepo onboarding docs.

This makes it easier for both AI-driven tools and new developers to discover and understand how Aide is supposed to behave in your monorepo.

---

Summary checklist

To get Aide working cleanly in a monorepo and ensure it uses the right TypeScript and ESLint config:

• Open the monorepo root as the workspace, not just a subfolder.
• Define a shared tsconfig.base.json at the root.
• Ensure each package has a local tsconfig.json extending the base.
• Use a root ESLint config and extend it with per-package configs when needed.
• Configure per-package ESLint parserOptions.project to point to that package’s tsconfig.json.
• Confirm TypeScript project association per file using your editor’s tools.
• Use the workspace TypeScript version from your root package.json.
• Make sure node_modules and dependencies are fully installed at the root.
• Ensure Aide’s index includes apps/** and packages/**, and excludes only build artifacts.
• Restart Aide / TypeScript servers after making structural or config changes.

With these patterns in place, Aide can reliably index your monorepo and apply the correct TypeScript and ESLint settings for each part of the codebase.